source3/include/libsmbclient.h

   1 /*=====================================================================
   2   Unix SMB/Netbios implementation.
   3   SMB client library API definitions
   4   Copyright (C) Andrew Tridgell 1998
   5   Copyright (C) Richard Sharpe 2000
   6   Copyright (C) John Terpsra 2000
   7   Copyright (C) Tom Jansen (Ninja ISD) 2002
   8   Copyright (C) Derrell Lipman 2003-2008
   9
  10
  11   This program is free software; you can redistribute it and/or modify
  12   it under the terms of the GNU General Public License as published by
  13   the Free Software Foundation; either version 3 of the License, or
  14   (at your option) any later version.
  15
  16   This program is distributed in the hope that it will be useful,
  17   but WITHOUT ANY WARRANTY; without even the implied warranty of
  18   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19   GNU General Public License for more details.
  20
  21   You should have received a copy of the GNU General Public License
  22   along with this program; if not, see <http://www.gnu.org/licenses/>.
  23   =====================================================================*/
  24
  25 #ifndef SMBCLIENT_H_INCLUDED
  26 #define SMBCLIENT_H_INCLUDED
  27
  28 #undef DEPRECATED_SMBC_INTERFACE
  29 #if ! defined(__LIBSMBCLIENT_INTERNAL__) && defined(__GNUC__)
  30 # define DEPRECATED_SMBC_INTERFACE      __attribute__ ((deprecated))
  31 #else
  32 # define DEPRECATED_SMBC_INTERFACE
  33 #endif
  34
  35 #ifdef __cplusplus
  36 extern "C" {
  37 #endif
  38
  39 /*-------------------------------------------------------------------*/
  40 /* The following are special comments to instruct DOXYGEN (automated
  41  * documentation tool:
  42 */
  43 /** \defgroup libsmbclient
  44 */
  45 /** \defgroup structure Data Structures Type and Constants
  46 *   \ingroup libsmbclient
  47 *   Data structures, types, and constants
  48 */
  49 /** \defgroup callback Callback function types
  50 *   \ingroup libsmbclient
  51 *   Callback functions
  52 */
  53 /** \defgroup file File Functions
  54 *   \ingroup libsmbclient
  55 *   Functions used to access individual file contents
  56 */
  57 /** \defgroup directory Directory Functions
  58 *   \ingroup libsmbclient
  59 *   Functions used to access directory entries
  60 */
  61 /** \defgroup attribute Attributes Functions
  62 *   \ingroup libsmbclient
  63 *   Functions used to view or change file and directory attributes
  64 */
  65 /** \defgroup print Print Functions
  66 *   \ingroup libsmbclient
  67 *   Functions used to access printing functionality
  68 */
  69 /** \defgroup misc Miscellaneous Functions
  70 *   \ingroup libsmbclient
  71 *   Functions that don't fit in to other categories
  72 */
  73 /*-------------------------------------------------------------------*/
  74
  75 /* Make sure we have the following includes for now ... */
  76 #include <sys/types.h>
  77 #include <sys/stat.h>
  78 #include <sys/statvfs.h>
  79 #include <fcntl.h>
  80 #include <utime.h>
  81
  82 #define SMBC_BASE_FD        10000 /* smallest file descriptor returned */
  83
  84 #define SMBC_WORKGROUP      1
  85 #define SMBC_SERVER         2
  86 #define SMBC_FILE_SHARE     3
  87 #define SMBC_PRINTER_SHARE  4
  88 #define SMBC_COMMS_SHARE    5
  89 #define SMBC_IPC_SHARE      6
  90 #define SMBC_DIR            7
  91 #define SMBC_FILE           8
  92 #define SMBC_LINK           9
  93
  94 /**@ingroup structure
  95  * Structure that represents a directory entry.
  96  *
  97  */
  98 struct smbc_dirent
  99 {
 100         /** Type of entity.
 101             SMBC_WORKGROUP=1,
 102             SMBC_SERVER=2,
 103             SMBC_FILE_SHARE=3,
 104             SMBC_PRINTER_SHARE=4,
 105             SMBC_COMMS_SHARE=5,
 106             SMBC_IPC_SHARE=6,
 107             SMBC_DIR=7,
 108             SMBC_FILE=8,
 109             SMBC_LINK=9,*/
 110         unsigned int smbc_type;
 111
 112         /** Length of this smbc_dirent in bytes
 113          */
 114         unsigned int dirlen;
 115         /** The length of the comment string in bytes (does not include
 116          *  null terminator)
 117          */
 118         unsigned int commentlen;
 119         /** Points to the null terminated comment string
 120          */
 121         char *comment;
 122         /** The length of the name string in bytes (does not include
 123          *  null terminator)
 124          */
 125         unsigned int namelen;
 126         /** Points to the null terminated name string
 127          */
 128         char name[1];
 129 };
 130
 131 /*
 132  * Flags for smbc_setxattr()
 133  *   Specify a bitwise OR of these, or 0 to add or replace as necessary
 134  */
 135 #define SMBC_XATTR_FLAG_CREATE       0x1 /* fail if attr already exists */
 136 #define SMBC_XATTR_FLAG_REPLACE      0x2 /* fail if attr does not exist */
 137
 138
 139 /*
 140  * Mappings of the DOS mode bits, as returned by smbc_getxattr() when the
 141  * attribute name "system.dos_attr.mode" (or "system.dos_attr.*" or
 142  * "system.*") is specified.
 143  */
 144 #define SMBC_DOS_MODE_READONLY       0x01
 145 #define SMBC_DOS_MODE_HIDDEN         0x02
 146 #define SMBC_DOS_MODE_SYSTEM         0x04
 147 #define SMBC_DOS_MODE_VOLUME_ID      0x08
 148 #define SMBC_DOS_MODE_DIRECTORY      0x10
 149 #define SMBC_DOS_MODE_ARCHIVE        0x20
 150
 151 /*
 152  * Valid values for the option "open_share_mode", when calling
 153  * smbc_setOptionOpenShareMode()
 154  */
 155 typedef enum smbc_share_mode
 156 {
 157     SMBC_SHAREMODE_DENY_DOS     = 0,
 158     SMBC_SHAREMODE_DENY_ALL     = 1,
 159     SMBC_SHAREMODE_DENY_WRITE   = 2,
 160     SMBC_SHAREMODE_DENY_READ    = 3,
 161     SMBC_SHAREMODE_DENY_NONE    = 4,
 162     SMBC_SHAREMODE_DENY_FCB     = 7
 163 } smbc_share_mode;
 164
 165
 166 /**
 167  * Values for option SMB Encryption Level, as set and retrieved with
 168  * smbc_setOptionSmbEncryptionLevel() and smbc_getOptionSmbEncryptionLevel()
 169  */
 170 typedef enum smbc_smb_encrypt_level
 171 {
 172     SMBC_ENCRYPTLEVEL_NONE      = 0,
 173     SMBC_ENCRYPTLEVEL_REQUEST   = 1,
 174     SMBC_ENCRYPTLEVEL_REQUIRE   = 2
 175 } smbc_smb_encrypt_level;
 176
 177
 178 /**
 179  * Capabilities set in the f_flag field of struct statvfs, from
 180  * smbc_statvfs(). These may be OR-ed together to reflect a full set of
 181  * available capabilities.
 182  */
 183 typedef enum smbc_vfs_feature
 184 {
 185     /* Defined by POSIX or in Linux include files (low-order bits) */
 186     SMBC_VFS_FEATURE_RDONLY         = (1 << 0),
 187
 188     /* Specific to libsmbclient (high-order bits) */
 189     SMBC_VFS_FEATURE_DFS              = (1 << 28),
 190     SMBC_VFS_FEATURE_CASE_INSENSITIVE = (1 << 29),
 191     SMBC_VFS_FEATURE_NO_UNIXCIFS      = (1 << 30)
 192 } smbc_vfs_feature;
 193
 194 typedef int smbc_bool;
 195
 196
 197 #ifndef ENOATTR
 198 # define ENOATTR ENOENT        /* No such attribute */
 199 #endif
 200
 201
 202
 203
 204 /**@ingroup structure
 205  * Structure that represents a print job.
 206  *
 207  */
 208 #ifndef _CLIENT_H
 209 struct print_job_info
 210 {
 211         /** numeric ID of the print job
 212          */
 213         unsigned short id;
 214
 215         /** represents print job priority (lower numbers mean higher priority)
 216          */
 217         unsigned short priority;
 218
 219         /** Size of the print job
 220          */
 221         size_t size;
 222
 223         /** Name of the user that owns the print job
 224          */
 225         char user[128];
 226
 227         /** Name of the print job. This will have no name if an anonymous print
 228          *  file was opened. Ie smb://server/printer
 229          */
 230         char name[128];
 231
 232         /** Time the print job was spooled
 233          */
 234         time_t t;
 235 };
 236 #endif /* _CLIENT_H */
 237
 238
 239 /**@ingroup structure
 240  * Server handle
 241  */
 242 typedef struct _SMBCSRV  SMBCSRV;
 243
 244 /**@ingroup structure
 245  * File or directory handle
 246  */
 247 typedef struct _SMBCFILE SMBCFILE;
 248
 249 /**@ingroup structure
 250  * File or directory handle
 251  */
 252 typedef struct _SMBCCTX SMBCCTX;
 253
 254
 255 /*
 256  * Flags for SMBCCTX->flags
 257  *
 258  * NEW CODE SHOULD NOT DIRECTLY MANIPULATE THE CONTEXT STRUCTURE.
 259  * Instead, use:
 260  *   smbc_setOptionUseKerberos()
 261  *   smbc_getOptionUseKerberos()
 262  *   smbc_setOptionFallbackAfterKerberos()
 263  *   smbc_getOptionFallbackAFterKerberos()
 264  *   smbc_setOptionNoAutoAnonymousLogin()
 265  *   smbc_getOptionNoAutoAnonymousLogin()
 266  */
 267 # define SMB_CTX_FLAG_USE_KERBEROS (1 << 0)
 268 # define SMB_CTX_FLAG_FALLBACK_AFTER_KERBEROS (1 << 1)
 269 # define SMBCCTX_FLAG_NO_AUTO_ANONYMOUS_LOGON (1 << 2)
 270
 271
 272
 273 /**@ingroup callback
 274  * Authentication callback function type (traditional method)
 275  *
 276  * Type for the the authentication function called by the library to
 277  * obtain authentication credentals
 278  *
 279  * For kerberos support the function should just be called without
 280  * prompting the user for credentials. Which means a simple 'return'
 281  * should work. Take a look at examples/libsmbclient/get_auth_data_fn.h
 282  * and examples/libsmbclient/testbrowse.c.
 283  *
 284  * @param srv       Server being authenticated to
 285  *
 286  * @param shr       Share being authenticated to
 287  *
 288  * @param wg        Pointer to buffer containing a "hint" for the
 289  *                  workgroup to be authenticated.  Should be filled in
 290  *                  with the correct workgroup if the hint is wrong.
 291  *
 292  * @param wglen     The size of the workgroup buffer in bytes
 293  *
 294  * @param un        Pointer to buffer containing a "hint" for the
 295  *                  user name to be use for authentication. Should be
 296  *                  filled in with the correct workgroup if the hint is
 297  *                  wrong.
 298  *
 299  * @param unlen     The size of the username buffer in bytes
 300  *
 301  * @param pw        Pointer to buffer containing to which password
 302  *                  copied
 303  *
 304  * @param pwlen     The size of the password buffer in bytes
 305  *
 306  */
 307 typedef void (*smbc_get_auth_data_fn)(const char *srv,
 308                                       const char *shr,
 309                                       char *wg, int wglen,
 310                                       char *un, int unlen,
 311                                       char *pw, int pwlen);
 312 /**@ingroup callback
 313  * Authentication callback function type (method that includes context)
 314  *
 315  * Type for the the authentication function called by the library to
 316  * obtain authentication credentals
 317  *
 318  * For kerberos support the function should just be called without
 319  * prompting the user for credentials. Which means a simple 'return'
 320  * should work. Take a look at examples/libsmbclient/get_auth_data_fn.h
 321  * and examples/libsmbclient/testbrowse.c.
 322  *
 323  * @param c         Pointer to the smb context
 324  *
 325  * @param srv       Server being authenticated to
 326  *
 327  * @param shr       Share being authenticated to
 328  *
 329  * @param wg        Pointer to buffer containing a "hint" for the
 330  *                  workgroup to be authenticated.  Should be filled in
 331  *                  with the correct workgroup if the hint is wrong.
 332  *
 333  * @param wglen     The size of the workgroup buffer in bytes
 334  *
 335  * @param un        Pointer to buffer containing a "hint" for the
 336  *                  user name to be use for authentication. Should be
 337  *                  filled in with the correct workgroup if the hint is
 338  *                  wrong.
 339  *
 340  * @param unlen     The size of the username buffer in bytes
 341  *
 342  * @param pw        Pointer to buffer containing to which password
 343  *                  copied
 344  *
 345  * @param pwlen     The size of the password buffer in bytes
 346  *
 347  */
 348 typedef void (*smbc_get_auth_data_with_context_fn)(SMBCCTX *c,
 349                                                    const char *srv,
 350                                                    const char *shr,
 351                                                    char *wg, int wglen,
 352                                                    char *un, int unlen,
 353                                                    char *pw, int pwlen);
 354
 355
 356 /**@ingroup callback
 357  * Print job info callback function type.
 358  *
 359  * @param i         pointer to print job information structure
 360  *
 361  */
 362 typedef void (*smbc_list_print_job_fn)(struct print_job_info *i);
 363
 364
 365 /**@ingroup callback
 366  * Check if a server is still good
 367  *
 368  * @param c         pointer to smb context
 369  *
 370  * @param srv       pointer to server to check
 371  *
 372  * @return          0 when connection is good. 1 on error.
 373  *
 374  */
 375 typedef int (*smbc_check_server_fn)(SMBCCTX * c, SMBCSRV *srv);
 376
 377 /**@ingroup callback
 378  * Remove a server if unused
 379  *
 380  * @param c         pointer to smb context
 381  *
 382  * @param srv       pointer to server to remove
 383  *
 384  * @return          0 on success. 1 on failure.
 385  *
 386  */
 387 typedef int (*smbc_remove_unused_server_fn)(SMBCCTX * c, SMBCSRV *srv);
 388
 389
 390 /**@ingroup callback
 391  * Add a server to the cache system
 392  *
 393  * @param c         pointer to smb context
 394  *
 395  * @param srv       pointer to server to add
 396  *
 397  * @param server    server name
 398  *
 399  * @param share     share name
 400  *
 401  * @param workgroup workgroup used to connect
 402  *
 403  * @param username  username used to connect
 404  *
 405  * @return          0 on success. 1 on failure.
 406  *
 407  */
 408 typedef int (*smbc_add_cached_srv_fn)   (SMBCCTX * c, SMBCSRV *srv,
 409                                     const char * server, const char * share,
 410                                     const char * workgroup, const char * username);
 411
 412 /**@ingroup callback
 413  * Look up a server in the cache system
 414  *
 415  * @param c         pointer to smb context
 416  *
 417  * @param server    server name to match
 418  *
 419  * @param share     share name to match
 420  *
 421  * @param workgroup workgroup to match
 422  *
 423  * @param username  username to match
 424  *
 425  * @return          pointer to SMBCSRV on success. NULL on failure.
 426  *
 427  */
 428 typedef SMBCSRV * (*smbc_get_cached_srv_fn)   (SMBCCTX * c, const char * server,
 429                                                const char * share, const char * workgroup,
 430                                                const char * username);
 431
 432 /**@ingroup callback
 433  * Check if a server is still good
 434  *
 435  * @param c         pointer to smb context
 436  *
 437  * @param srv       pointer to server to remove
 438  *
 439  * @return          0 when found and removed. 1 on failure.
 440  *
 441  */
 442 typedef int (*smbc_remove_cached_srv_fn)(SMBCCTX * c, SMBCSRV *srv);
 443
 444
 445 /**@ingroup callback
 446  * Try to remove all servers from the cache system and disconnect
 447  *
 448  * @param c         pointer to smb context
 449  *
 450  * @return          0 when found and removed. 1 on failure.
 451  *
 452  */
 453 typedef int (*smbc_purge_cached_fn)     (SMBCCTX * c);
 454
 455
 456
 457 /*****************************************
 458  * Getters and setters for CONFIGURATION *
 459  *****************************************/
 460
 461 /** Get the debug level */
 462 int
 463 smbc_getDebug(SMBCCTX *c);
 464
 465 /** Set the debug level */
 466 void
 467 smbc_setDebug(SMBCCTX *c, int debug);
 468
 469 /** Get the netbios name used for making connections */
 470 char *
 471 smbc_getNetbiosName(SMBCCTX *c);
 472
 473 /** Set the netbios name used for making connections */
 474 void
 475 smbc_setNetbiosName(SMBCCTX *c, char * netbios_name);
 476
 477 /** Get the workgroup used for making connections */
 478 char *
 479 smbc_getWorkgroup(SMBCCTX *c);
 480
 481 /** Set the workgroup used for making connections */
 482 void smbc_setWorkgroup(SMBCCTX *c, char * workgroup);
 483
 484 /** Get the username used for making connections */
 485 char *
 486 smbc_getUser(SMBCCTX *c);
 487
 488 /** Set the username used for making connections */
 489 void
 490 smbc_setUser(SMBCCTX *c, char * user);
 491
 492 /**
 493  * Get the timeout used for waiting on connections and response data
 494  * (in milliseconds)
 495  */
 496 int
 497 smbc_getTimeout(SMBCCTX *c);
 498
 499 /**
 500  * Set the timeout used for waiting on connections and response data
 501  * (in milliseconds)
 502  */
 503 void
 504 smbc_setTimeout(SMBCCTX *c, int timeout);
 505
 506
 507
 508 /***********************************
 509  * Getters and setters for OPTIONS *
 510  ***********************************/
 511
 512 /** Get whether to log to standard error instead of standard output */
 513 smbc_bool
 514 smbc_getOptionDebugToStderr(SMBCCTX *c);
 515
 516 /** Set whether to log to standard error instead of standard output */
 517 void
 518 smbc_setOptionDebugToStderr(SMBCCTX *c, smbc_bool b);
 519
 520 /**
 521  * Get whether to use new-style time attribute names, e.g. WRITE_TIME rather
 522  * than the old-style names such as M_TIME.  This allows also setting/getting
 523  * CREATE_TIME which was previously unimplemented.  (Note that the old C_TIME
 524  * was supposed to be CHANGE_TIME but was confused and sometimes referred to
 525  * CREATE_TIME.)
 526  */
 527 smbc_bool
 528 smbc_getOptionFullTimeNames(SMBCCTX *c);
 529
 530 /**
 531  * Set whether to use new-style time attribute names, e.g. WRITE_TIME rather
 532  * than the old-style names such as M_TIME.  This allows also setting/getting
 533  * CREATE_TIME which was previously unimplemented.  (Note that the old C_TIME
 534  * was supposed to be CHANGE_TIME but was confused and sometimes referred to
 535  * CREATE_TIME.)
 536  */
 537 void
 538 smbc_setOptionFullTimeNames(SMBCCTX *c, smbc_bool b);
 539
 540 /**
 541  * Get the share mode to use for files opened with SMBC_open_ctx().  The
 542  * default is SMBC_SHAREMODE_DENY_NONE.
 543  */
 544 smbc_share_mode
 545 smbc_getOptionOpenShareMode(SMBCCTX *c);
 546
 547 /**
 548  * Set the share mode to use for files opened with SMBC_open_ctx().  The
 549  * default is SMBC_SHAREMODE_DENY_NONE.
 550  */
 551 void
 552 smbc_setOptionOpenShareMode(SMBCCTX *c, smbc_share_mode share_mode);
 553
 554 /** Retrieve a previously saved user data handle */
 555 void *
 556 smbc_getOptionUserData(SMBCCTX *c);
 557
 558 /** Save a user data handle */
 559 void
 560 smbc_setOptionUserData(SMBCCTX *c, void *user_data);
 561
 562 /** Get the encoded value for encryption level. */
 563 smbc_smb_encrypt_level
 564 smbc_getOptionSmbEncryptionLevel(SMBCCTX *c);
 565
 566 /** Set the encoded value for encryption level. */
 567 void
 568 smbc_setOptionSmbEncryptionLevel(SMBCCTX *c, smbc_smb_encrypt_level level);
 569
 570 /**
 571  * Get whether to treat file names as case-sensitive if we can't determine
 572  * when connecting to the remote share whether the file system is case
 573  * sensitive. This defaults to FALSE since it's most likely that if we can't
 574  * retrieve the file system attributes, it's a very old file system that does
 575  * not support case sensitivity.
 576  */
 577 smbc_bool
 578 smbc_getOptionCaseSensitive(SMBCCTX *c);
 579
 580 /**
 581  * Set whether to treat file names as case-sensitive if we can't determine
 582  * when connecting to the remote share whether the file system is case
 583  * sensitive. This defaults to FALSE since it's most likely that if we can't
 584  * retrieve the file system attributes, it's a very old file system that does
 585  * not support case sensitivity.
 586  */
 587 void
 588 smbc_setOptionCaseSensitive(SMBCCTX *c, smbc_bool b);
 589
 590
 591 /**
 592  * Get from how many local master browsers should the list of workgroups be
 593  * retrieved.  It can take up to 12 minutes or longer after a server becomes a
 594  * local master browser, for it to have the entire browse list (the list of
 595  * workgroups/domains) from an entire network.  Since a client never knows
 596  * which local master browser will be found first, the one which is found
 597  * first and used to retrieve a browse list may have an incomplete or empty
 598  * browse list.  By requesting the browse list from multiple local master
 599  * browsers, a more complete list can be generated.  For small networks (few
 600  * workgroups), it is recommended that this value be set to 0, causing the
 601  * browse lists from all found local master browsers to be retrieved and
 602  * merged.  For networks with many workgroups, a suitable value for this
 603  * variable is probably somewhere around 3. (Default: 3).
 604  */
 605 int
 606 smbc_getOptionBrowseMaxLmbCount(SMBCCTX *c);
 607
 608 /**
 609  * Set from how many local master browsers should the list of workgroups be
 610  * retrieved.  It can take up to 12 minutes or longer after a server becomes a
 611  * local master browser, for it to have the entire browse list (the list of
 612  * workgroups/domains) from an entire network.  Since a client never knows
 613  * which local master browser will be found first, the one which is found
 614  * first and used to retrieve a browse list may have an incomplete or empty
 615  * browse list.  By requesting the browse list from multiple local master
 616  * browsers, a more complete list can be generated.  For small networks (few
 617  * workgroups), it is recommended that this value be set to 0, causing the
 618  * browse lists from all found local master browsers to be retrieved and
 619  * merged.  For networks with many workgroups, a suitable value for this
 620  * variable is probably somewhere around 3. (Default: 3).
 621  */
 622 void
 623 smbc_setOptionBrowseMaxLmbCount(SMBCCTX *c, int count);
 624
 625 /**
 626  * Get whether to url-encode readdir entries.
 627  *
 628  * There is a difference in the desired return strings from
 629  * smbc_readdir() depending upon whether the filenames are to
 630  * be displayed to the user, or whether they are to be
 631  * appended to the path name passed to smbc_opendir() to call
 632  * a further smbc_ function (e.g. open the file with
 633  * smbc_open()).  In the former case, the filename should be
 634  * in "human readable" form.  In the latter case, the smbc_
 635  * functions expect a URL which must be url-encoded.  Those
 636  * functions decode the URL.  If, for example, smbc_readdir()
 637  * returned a file name of "abc%20def.txt", passing a path
 638  * with this file name attached to smbc_open() would cause
 639  * smbc_open to attempt to open the file "abc def.txt" since
 640  * the %20 is decoded into a space.
 641  *
 642  * Set this option to True if the names returned by
 643  * smbc_readdir() should be url-encoded such that they can be
 644  * passed back to another smbc_ call.  Set it to False if the
 645  * names returned by smbc_readdir() are to be presented to the
 646  * user.
 647  *
 648  * For backwards compatibility, this option defaults to False.
 649  */
 650 smbc_bool
 651 smbc_getOptionUrlEncodeReaddirEntries(SMBCCTX *c);
 652
 653 /**
 654  * Set whether to url-encode readdir entries.
 655  *
 656  * There is a difference in the desired return strings from
 657  * smbc_readdir() depending upon whether the filenames are to
 658  * be displayed to the user, or whether they are to be
 659  * appended to the path name passed to smbc_opendir() to call
 660  * a further smbc_ function (e.g. open the file with
 661  * smbc_open()).  In the former case, the filename should be
 662  * in "human readable" form.  In the latter case, the smbc_
 663  * functions expect a URL which must be url-encoded.  Those
 664  * functions decode the URL.  If, for example, smbc_readdir()
 665  * returned a file name of "abc%20def.txt", passing a path
 666  * with this file name attached to smbc_open() would cause
 667  * smbc_open to attempt to open the file "abc def.txt" since
 668  * the %20 is decoded into a space.
 669  *
 670  * Set this option to True if the names returned by
 671  * smbc_readdir() should be url-encoded such that they can be
 672  * passed back to another smbc_ call.  Set it to False if the
 673  * names returned by smbc_readdir() are to be presented to the
 674  * user.
 675  *
 676  * For backwards compatibility, this option defaults to False.
 677  */
 678 void
 679 smbc_setOptionUrlEncodeReaddirEntries(SMBCCTX *c, smbc_bool b);
 680
 681 /**
 682  * Get whether to use the same connection for all shares on a server.
 683  *
 684  * Some Windows versions appear to have a limit to the number
 685  * of concurrent SESSIONs and/or TREE CONNECTions.  In
 686  * one-shot programs (i.e. the program runs and then quickly
 687  * ends, thereby shutting down all connections), it is
 688  * probably reasonable to establish a new connection for each
 689  * share.  In long-running applications, the limitation can be
 690  * avoided by using only a single connection to each server,
 691  * and issuing a new TREE CONNECT when the share is accessed.
 692  */
 693 smbc_bool
 694 smbc_getOptionOneSharePerServer(SMBCCTX *c);
 695
 696 /**
 697  * Set whether to use the same connection for all shares on a server.
 698  *
 699  * Some Windows versions appear to have a limit to the number
 700  * of concurrent SESSIONs and/or TREE CONNECTions.  In
 701  * one-shot programs (i.e. the program runs and then quickly
 702  * ends, thereby shutting down all connections), it is
 703  * probably reasonable to establish a new connection for each
 704  * share.  In long-running applications, the limitation can be
 705  * avoided by using only a single connection to each server,
 706  * and issuing a new TREE CONNECT when the share is accessed.
 707  */
 708 void
 709 smbc_setOptionOneSharePerServer(SMBCCTX *c, smbc_bool b);
 710
 711 /** Get whether to enable use of kerberos */
 712 smbc_bool
 713 smbc_getOptionUseKerberos(SMBCCTX *c);
 714
 715 /** Set whether to enable use of kerberos */
 716 void
 717 smbc_setOptionUseKerberos(SMBCCTX *c, smbc_bool b);
 718
 719 /** Get whether to fallback after kerberos */
 720 smbc_bool
 721 smbc_getOptionFallbackAfterKerberos(SMBCCTX *c);
 722
 723 /** Set whether to fallback after kerberos */
 724 void
 725 smbc_setOptionFallbackAfterKerberos(SMBCCTX *c, smbc_bool b);
 726
 727 /** Get whether to automatically select anonymous login */
 728 smbc_bool
 729 smbc_getOptionNoAutoAnonymousLogin(SMBCCTX *c);
 730
 731 /** Set whether to automatically select anonymous login */
 732 void
 733 smbc_setOptionNoAutoAnonymousLogin(SMBCCTX *c, smbc_bool b);
 734
 735
 736
 737 /*************************************
 738  * Getters and setters for FUNCTIONS *
 739  *************************************/
 740
 741 /** Get the function for obtaining authentication data */
 742 smbc_get_auth_data_fn smbc_getFunctionAuthData(SMBCCTX *c);
 743
 744 /** Set the function for obtaining authentication data */
 745 void smbc_setFunctionAuthData(SMBCCTX *c, smbc_get_auth_data_fn fn);
 746
 747 /** Get the new-style authentication function which includes the context. */
 748 smbc_get_auth_data_with_context_fn
 749 smbc_getFunctionAuthDataWithContext(SMBCCTX *c);
 750
 751 /** Set the new-style authentication function which includes the context. */
 752 void
 753 smbc_setFunctionAuthDataWithContext(SMBCCTX *c,
 754                                     smbc_get_auth_data_with_context_fn fn);
 755
 756 /** Get the function for checking if a server is still good */
 757 smbc_check_server_fn smbc_getFunctionCheckServer(SMBCCTX *c);
 758
 759 /** Set the function for checking if a server is still good */
 760 void smbc_setFunctionCheckServer(SMBCCTX *c, smbc_check_server_fn fn);
 761
 762 /** Get the function for removing a server if unused */
 763 smbc_remove_unused_server_fn smbc_getFunctionRemoveUnusedServer(SMBCCTX *c);
 764
 765 /** Set the function for removing a server if unused */
 766 void smbc_setFunctionRemoveUnusedServer(SMBCCTX *c,
 767                                         smbc_remove_unused_server_fn fn);
 768
 769 /** Get the function for adding a cached server */
 770 smbc_add_cached_srv_fn smbc_getFunctionAddCachedServer(SMBCCTX *c);
 771
 772 /** Set the function for adding a cached server */
 773 void smbc_setFunctionAddCachedServer(SMBCCTX *c, smbc_add_cached_srv_fn fn);
 774
 775 /** Get the function for server cache lookup */
 776 smbc_get_cached_srv_fn smbc_getFunctionGetCachedServer(SMBCCTX *c);
 777
 778 /** Set the function for server cache lookup */
 779 void smbc_setFunctionGetCachedServer(SMBCCTX *c, smbc_get_cached_srv_fn fn);
 780
 781 /** Get the function for server cache removal */
 782 smbc_remove_cached_srv_fn smbc_getFunctionRemoveCachedServer(SMBCCTX *c);
 783
 784 /** Set the function for server cache removal */
 785 void smbc_setFunctionRemoveCachedServer(SMBCCTX *c,
 786                                         smbc_remove_cached_srv_fn fn);
 787
 788 /**
 789  * Get the function for server cache purging.  This function tries to
 790  * remove all cached servers (e.g. on disconnect)
 791  */
 792 smbc_purge_cached_fn smbc_getFunctionPurgeCachedServers(SMBCCTX *c);
 793
 794 /**
 795  * Set the function for server cache purging.  This function tries to
 796  * remove all cached servers (e.g. on disconnect)
 797  */
 798 void smbc_setFunctionPurgeCachedServers(SMBCCTX *c,
 799                                         smbc_purge_cached_fn fn);
 800
 801 /** Get the function to store private data of the server cache */
 802 struct smbc_server_cache * smbc_getServerCacheData(SMBCCTX *c);
 803
 804 /** Set the function to store private data of the server cache */
 805 void smbc_setServerCacheData(SMBCCTX *c, struct smbc_server_cache * cache);
 806
 807
 808
 809 /*****************************************************************
 810  * Callable functions for files.                                 *
 811  * Each callable has a function signature typedef, a declaration *
 812  * for the getter, and a declaration for the setter.             *
 813  *****************************************************************/
 814
 815 typedef SMBCFILE * (*smbc_open_fn)(SMBCCTX *c,
 816                                    const char *fname,
 817                                    int flags,
 818                                    mode_t mode);
 819 smbc_open_fn smbc_getFunctionOpen(SMBCCTX *c);
 820 void smbc_setFunctionOpen(SMBCCTX *c, smbc_open_fn fn);
 821
 822 typedef SMBCFILE * (*smbc_creat_fn)(SMBCCTX *c,
 823                                     const char *path,
 824                                     mode_t mode);
 825 smbc_creat_fn smbc_getFunctionCreat(SMBCCTX *c);
 826 void smbc_setFunctionCreat(SMBCCTX *c, smbc_creat_fn);
 827
 828 typedef ssize_t (*smbc_read_fn)(SMBCCTX *c,
 829                                 SMBCFILE *file,
 830                                 void *buf,
 831                                 size_t count);
 832 smbc_read_fn smbc_getFunctionRead(SMBCCTX *c);
 833 void smbc_setFunctionRead(SMBCCTX *c, smbc_read_fn fn);
 834
 835 typedef ssize_t (*smbc_write_fn)(SMBCCTX *c,
 836                                  SMBCFILE *file,
 837                                  const void *buf,
 838                                  size_t count);
 839 smbc_write_fn smbc_getFunctionWrite(SMBCCTX *c);
 840 void smbc_setFunctionWrite(SMBCCTX *c, smbc_write_fn fn);
 841
 842 typedef int (*smbc_unlink_fn)(SMBCCTX *c,
 843                               const char *fname);
 844 smbc_unlink_fn smbc_getFunctionUnlink(SMBCCTX *c);
 845 void smbc_setFunctionUnlink(SMBCCTX *c, smbc_unlink_fn fn);
 846
 847 typedef int (*smbc_rename_fn)(SMBCCTX *ocontext,
 848                               const char *oname,
 849                               SMBCCTX *ncontext,
 850                               const char *nname);
 851 smbc_rename_fn smbc_getFunctionRename(SMBCCTX *c);
 852 void smbc_setFunctionRename(SMBCCTX *c, smbc_rename_fn fn);
 853
 854 typedef off_t (*smbc_lseek_fn)(SMBCCTX *c,
 855                                SMBCFILE * file,
 856                                off_t offset,
 857                                int whence);
 858 smbc_lseek_fn smbc_getFunctionLseek(SMBCCTX *c);
 859 void smbc_setFunctionLseek(SMBCCTX *c, smbc_lseek_fn fn);
 860
 861 typedef int (*smbc_stat_fn)(SMBCCTX *c,
 862                             const char *fname,
 863                             struct stat *st);
 864 smbc_stat_fn smbc_getFunctionStat(SMBCCTX *c);
 865 void smbc_setFunctionStat(SMBCCTX *c, smbc_stat_fn fn);
 866
 867 typedef int (*smbc_fstat_fn)(SMBCCTX *c,
 868                              SMBCFILE *file,
 869                              struct stat *st);
 870 smbc_fstat_fn smbc_getFunctionFstat(SMBCCTX *c);
 871 void smbc_setFunctionFstat(SMBCCTX *c, smbc_fstat_fn fn);
 872
 873 typedef int (*smbc_statvfs_fn)(SMBCCTX *c,
 874                                char *path,
 875                                struct statvfs *st);
 876 smbc_statvfs_fn smbc_getFunctionStatVFS(SMBCCTX *c);
 877 void smbc_setFunctionStatVFS(SMBCCTX *c, smbc_statvfs_fn fn);
 878
 879 typedef int (*smbc_fstatvfs_fn)(SMBCCTX *c,
 880                                 SMBCFILE *file,
 881                                 struct statvfs *st);
 882 smbc_fstatvfs_fn smbc_getFunctionFstatVFS(SMBCCTX *c);
 883 void smbc_setFunctionFstatVFS(SMBCCTX *c, smbc_fstatvfs_fn fn);
 884
 885 typedef int (*smbc_ftruncate_fn)(SMBCCTX *c,
 886                                  SMBCFILE *f,
 887                                  off_t size);
 888 smbc_ftruncate_fn smbc_getFunctionFtruncate(SMBCCTX *c);
 889 void smbc_setFunctionFtruncate(SMBCCTX *c, smbc_ftruncate_fn fn);
 890
 891 typedef int (*smbc_close_fn)(SMBCCTX *c,
 892                              SMBCFILE *file);
 893 smbc_close_fn smbc_getFunctionClose(SMBCCTX *c);
 894 void smbc_setFunctionClose(SMBCCTX *c, smbc_close_fn fn);
 895
 896
 897
 898 /*****************************************************************
 899  * Callable functions for directories.                           *
 900  * Each callable has a function signature typedef, a declaration *
 901  * for the getter, and a declaration for the setter.             *
 902  *****************************************************************/
 903
 904 typedef SMBCFILE * (*smbc_opendir_fn)(SMBCCTX *c,
 905                                       const char *fname);
 906 smbc_opendir_fn smbc_getFunctionOpendir(SMBCCTX *c);
 907 void smbc_setFunctionOpendir(SMBCCTX *c, smbc_opendir_fn fn);
 908
 909 typedef int (*smbc_closedir_fn)(SMBCCTX *c,
 910                                 SMBCFILE *dir);
 911 smbc_closedir_fn smbc_getFunctionClosedir(SMBCCTX *c);
 912 void smbc_setFunctionClosedir(SMBCCTX *c, smbc_closedir_fn fn);
 913
 914 typedef struct smbc_dirent * (*smbc_readdir_fn)(SMBCCTX *c,
 915                                                 SMBCFILE *dir);
 916 smbc_readdir_fn smbc_getFunctionReaddir(SMBCCTX *c);
 917 void smbc_setFunctionReaddir(SMBCCTX *c, smbc_readdir_fn fn);
 918
 919 typedef int (*smbc_getdents_fn)(SMBCCTX *c,
 920                                 SMBCFILE *dir,
 921                                 struct smbc_dirent *dirp,
 922                                 int count);
 923 smbc_getdents_fn smbc_getFunctionGetdents(SMBCCTX *c);
 924 void smbc_setFunctionGetdents(SMBCCTX *c, smbc_getdents_fn fn);
 925
 926 typedef int (*smbc_mkdir_fn)(SMBCCTX *c,
 927                              const char *fname,
 928                              mode_t mode);
 929 smbc_mkdir_fn smbc_getFunctionMkdir(SMBCCTX *c);
 930 void smbc_setFunctionMkdir(SMBCCTX *c, smbc_mkdir_fn fn);
 931
 932 typedef int (*smbc_rmdir_fn)(SMBCCTX *c,
 933                              const char *fname);
 934 smbc_rmdir_fn smbc_getFunctionRmdir(SMBCCTX *c);
 935 void smbc_setFunctionRmdir(SMBCCTX *c, smbc_rmdir_fn fn);
 936
 937 typedef off_t (*smbc_telldir_fn)(SMBCCTX *c,
 938                                  SMBCFILE *dir);
 939 smbc_telldir_fn smbc_getFunctionTelldir(SMBCCTX *c);
 940 void smbc_setFunctionTelldir(SMBCCTX *c, smbc_telldir_fn fn);
 941
 942 typedef int (*smbc_lseekdir_fn)(SMBCCTX *c,
 943                                 SMBCFILE *dir,
 944                                 off_t offset);
 945 smbc_lseekdir_fn smbc_getFunctionLseekdir(SMBCCTX *c);
 946 void smbc_setFunctionLseekdir(SMBCCTX *c, smbc_lseekdir_fn fn);
 947
 948 typedef int (*smbc_fstatdir_fn)(SMBCCTX *c,
 949                                 SMBCFILE *dir,
 950                                 struct stat *st);
 951 smbc_fstatdir_fn smbc_getFunctionFstatdir(SMBCCTX *c);
 952 void smbc_setFunctionFstatdir(SMBCCTX *c, smbc_fstatdir_fn fn);
 953
 954
 955
 956 /*****************************************************************
 957  * Callable functions applicable to both files and directories.  *
 958  * Each callable has a function signature typedef, a declaration *
 959  * for the getter, and a declaration for the setter.             *
 960  *****************************************************************/
 961
 962 typedef int (*smbc_chmod_fn)(SMBCCTX *c,
 963                              const char *fname,
 964                              mode_t mode);
 965 smbc_chmod_fn smbc_getFunctionChmod(SMBCCTX *c);
 966 void smbc_setFunctionChmod(SMBCCTX *c, smbc_chmod_fn fn);
 967
 968 typedef int (*smbc_utimes_fn)(SMBCCTX *c,
 969                               const char *fname,
 970                               struct timeval *tbuf);
 971 smbc_utimes_fn smbc_getFunctionUtimes(SMBCCTX *c);
 972 void smbc_setFunctionUtimes(SMBCCTX *c, smbc_utimes_fn fn);
 973
 974 typedef int (*smbc_setxattr_fn)(SMBCCTX *context,
 975                                 const char *fname,
 976                                 const char *name,
 977                                 const void *value,
 978                                 size_t size,
 979                                 int flags);
 980 smbc_setxattr_fn smbc_getFunctionSetxattr(SMBCCTX *c);
 981 void smbc_setFunctionSetxattr(SMBCCTX *c, smbc_setxattr_fn fn);
 982
 983 typedef int (*smbc_getxattr_fn)(SMBCCTX *context,
 984                                 const char *fname,
 985                                 const char *name,
 986                                 const void *value,
 987                                 size_t size);
 988 smbc_getxattr_fn smbc_getFunctionGetxattr(SMBCCTX *c);
 989 void smbc_setFunctionGetxattr(SMBCCTX *c, smbc_getxattr_fn fn);
 990
 991 typedef int (*smbc_removexattr_fn)(SMBCCTX *context,
 992                                    const char *fname,
 993                                    const char *name);
 994 smbc_removexattr_fn smbc_getFunctionRemovexattr(SMBCCTX *c);
 995 void smbc_setFunctionRemovexattr(SMBCCTX *c, smbc_removexattr_fn fn);
 996
 997 typedef int (*smbc_listxattr_fn)(SMBCCTX *context,
 998                                  const char *fname,
 999                                  char *list,
1000                                  size_t size);
1001 smbc_listxattr_fn smbc_getFunctionListxattr(SMBCCTX *c);
1002 void smbc_setFunctionListxattr(SMBCCTX *c, smbc_listxattr_fn fn);
1003
1004
1005
1006 /*****************************************************************
1007  * Callable functions for printing.                              *
1008  * Each callable has a function signature typedef, a declaration *
1009  * for the getter, and a declaration for the setter.             *
1010  *****************************************************************/
1011
1012 typedef int (*smbc_print_file_fn)(SMBCCTX *c_file,
1013                                   const char *fname,
1014                                   SMBCCTX *c_print,
1015                                   const char *printq);
1016 smbc_print_file_fn smbc_getFunctionPrintFile(SMBCCTX *c);
1017 void smbc_setFunctionPrintFile(SMBCCTX *c, smbc_print_file_fn fn);
1018
1019 typedef SMBCFILE * (*smbc_open_print_job_fn)(SMBCCTX *c,
1020                                              const char *fname);
1021 smbc_open_print_job_fn smbc_getFunctionOpenPrintJob(SMBCCTX *c);
1022 void smbc_setFunctionOpenPrintJob(SMBCCTX *c,
1023                                   smbc_open_print_job_fn fn);
1024
1025 typedef int (*smbc_list_print_jobs_fn)(SMBCCTX *c,
1026                                        const char *fname,
1027                                        smbc_list_print_job_fn fn);
1028 smbc_list_print_jobs_fn smbc_getFunctionListPrintJobs(SMBCCTX *c);
1029 void smbc_setFunctionListPrintJobs(SMBCCTX *c,
1030                                    smbc_list_print_jobs_fn fn);
1031
1032 typedef int (*smbc_unlink_print_job_fn)(SMBCCTX *c,
1033                                         const char *fname,
1034                                         int id);
1035 smbc_unlink_print_job_fn smbc_getFunctionUnlinkPrintJob(SMBCCTX *c);
1036 void smbc_setFunctionUnlinkPrintJob(SMBCCTX *c,
1037                                     smbc_unlink_print_job_fn fn);
1038
1039
1040 /**@ingroup misc
1041  * Create a new SBMCCTX (a context).
1042  *
1043  * Must be called before the context is passed to smbc_context_init()
1044  *
1045  * @return          The given SMBCCTX pointer on success, NULL on error with errno set:
1046  *                  - ENOMEM Out of memory
1047  *
1048  * @see             smbc_free_context(), smbc_init_context()
1049  *
1050  * @note            Do not forget to smbc_init_context() the returned SMBCCTX pointer !
1051  */
1052 SMBCCTX * smbc_new_context(void);
1053
1054 /**@ingroup misc
1055  * Delete a SBMCCTX (a context) acquired from smbc_new_context().
1056  *
1057  * The context will be deleted if possible.
1058  *
1059  * @param context   A pointer to a SMBCCTX obtained from smbc_new_context()
1060  *
1061  * @param shutdown_ctx   If 1, all connections and files will be closed even if they are busy.
1062  *
1063  *
1064  * @return          Returns 0 on succes. Returns 1 on failure with errno set:
1065  *                  - EBUSY Server connections are still used, Files are open or cache
1066  *                          could not be purged
1067  *                  - EBADF context == NULL
1068  *
1069  * @see             smbc_new_context()
1070  *
1071  * @note            It is advised to clean up all the contexts with shutdown_ctx set to 1
1072  *                  just before exit()'ing. When shutdown_ctx is 0, this function can be
1073  *                  use in periodical cleanup functions for example.
1074  */
1075 int smbc_free_context(SMBCCTX * context, int shutdown_ctx);
1076
1077
1078 /**@ingroup misc
1079  *
1080  * @deprecated.  Use smbc_setOption*() functions instead.
1081  */
1082 void
1083 smbc_option_set(SMBCCTX *context,
1084                 char *option_name,
1085                 ... /* option_value */);
1086
1087 /*
1088  * @deprecated.  Use smbc_getOption*() functions instead.
1089  */
1090 void *
1091 smbc_option_get(SMBCCTX *context,
1092                 char *option_name);
1093
1094 /**@ingroup misc
1095  * Initialize a SBMCCTX (a context).
1096  *
1097  * Must be called before using any SMBCCTX API function
1098  *
1099  * @param context   A pointer to a SMBCCTX obtained from smbc_new_context()
1100  *
1101  * @return          A pointer to the given SMBCCTX on success,
1102  *                  NULL on error with errno set:
1103  *                  - EBADF  NULL context given
1104  *                  - ENOMEM Out of memory
1105  *                  - ENOENT The smb.conf file would not load
1106  *
1107  * @see             smbc_new_context()
1108  *
1109  * @note            my_context = smbc_init_context(smbc_new_context())
1110  *                  is perfectly safe, but it might leak memory on
1111  *                  smbc_context_init() failure. Avoid this.
1112  *                  You'll have to call smbc_free_context() yourself
1113  *                  on failure.
1114  */
1115
1116 SMBCCTX * smbc_init_context(SMBCCTX * context);
1117
1118 /**@ingroup misc
1119  * Initialize the samba client library.
1120  *
1121  * Must be called before using any of the smbclient API function
1122  *
1123  * @param fn        The function that will be called to obtaion
1124  *                  authentication credentials.
1125  *
1126  * @param debug     Allows caller to set the debug level. Can be
1127  *                  changed in smb.conf file. Allows caller to set
1128  *                  debugging if no smb.conf.
1129  *
1130  * @return          0 on success, < 0 on error with errno set:
1131  *                  - ENOMEM Out of memory
1132  *                  - ENOENT The smb.conf file would not load
1133  *
1134  */
1135
1136 int smbc_init(smbc_get_auth_data_fn fn, int debug);
1137
1138 /**@ingroup misc
1139  * Set or retrieve the compatibility library's context pointer
1140  *
1141  * @param context   New context to use, or NULL.  If a new context is provided,
1142  *                  it must have allocated with smbc_new_context() and
1143  *                  initialized with smbc_init_context(), followed, optionally,
1144  *                  by some manual changes to some of the non-internal fields.
1145  *
1146  * @return          The old context.
1147  *
1148  * @see             smbc_new_context(), smbc_init_context(), smbc_init()
1149  *
1150  * @note            This function may be called prior to smbc_init() to force
1151  *                  use of the next context without any internal calls to
1152  *                  smbc_new_context() or smbc_init_context().  It may also
1153  *                  be called after smbc_init() has already called those two
1154  *                  functions, to replace the existing context with a new one.
1155  *                  Care should be taken, in this latter case, to ensure that
1156  *                  the server cache and any data allocated by the
1157  *                  authentication functions have been freed, if necessary.
1158  */
1159
1160 SMBCCTX * smbc_set_context(SMBCCTX * new_context);
1161
1162 /**@ingroup file
1163  * Open a file on an SMB server.
1164  *
1165  * @param furl      The smb url of the file to be opened.
1166  *
1167  * @param flags     Is one of O_RDONLY, O_WRONLY or O_RDWR which
1168  *                  request opening  the  file  read-only,write-only
1169  *                  or read/write. flags may also be bitwise-or'd with
1170  *                  one or  more of  the following:
1171  *                  O_CREAT - If the file does not exist it will be
1172  *                  created.
1173  *                  O_EXCL - When  used with O_CREAT, if the file
1174  *                  already exists it is an error and the open will
1175  *                  fail.
1176  *                  O_TRUNC - If the file already exists it will be
1177  *                  truncated.
1178  *                  O_APPEND The  file  is  opened  in  append mode
1179  *
1180  * @param mode      mode specifies the permissions to use if a new
1181  *                  file is created.  It  is  modified  by  the
1182  *                  process's umask in the usual way: the permissions
1183  *                  of the created file are (mode & ~umask)
1184  *
1185  *                  Not currently use, but there for future use.
1186  *                  We will map this to SYSTEM, HIDDEN, etc bits
1187  *                  that reverses the mapping that smbc_fstat does.
1188  *
1189  * @return          Valid file handle, < 0 on error with errno set:
1190  *                  - ENOMEM  Out of memory
1191  *                  - EINVAL if an invalid parameter passed, like no
1192  *                  file, or smbc_init not called.
1193  *                  - EEXIST  pathname already exists and O_CREAT and
1194  *                  O_EXCL were used.
1195  *                  - EISDIR  pathname  refers  to  a  directory  and
1196  *                  the access requested involved writing.
1197  *                  - EACCES  The requested access to the file is not
1198  *                  allowed
1199  *                  - ENODEV The requested share does not exist
1200  *                  - ENOTDIR A file on the path is not a directory
1201  *                  - ENOENT  A directory component in pathname does
1202  *                  not exist.
1203  *
1204  * @see             smbc_creat()
1205  *
1206  * @note            This call uses an underlying routine that may create
1207  *                  a new connection to the server specified in the URL.
1208  *                  If the credentials supplied in the URL, or via the
1209  *                  auth_fn in the smbc_init call, fail, this call will
1210  *                  try again with an empty username and password. This
1211  *                  often gets mapped to the guest account on some machines.
1212  */
1213
1214 int smbc_open(const char *furl, int flags, mode_t mode);
1215
1216 /**@ingroup file
1217  * Create a file on an SMB server.
1218  *
1219  * Same as calling smbc_open() with flags = O_CREAT|O_WRONLY|O_TRUNC
1220  *
1221  * @param furl      The smb url of the file to be created
1222  *
1223  * @param mode      mode specifies the permissions to use if  a  new
1224  *                  file is created.  It  is  modified  by  the
1225  *                  process's umask in the usual way: the permissions
1226  *                  of the created file are (mode & ~umask)
1227  *
1228  *                  NOTE, the above is not true. We are dealing with
1229  *                  an SMB server, which has no concept of a umask!
1230  *
1231  * @return          Valid file handle, < 0 on error with errno set:
1232  *                  - ENOMEM  Out of memory
1233  *                  - EINVAL if an invalid parameter passed, like no
1234  *                  file, or smbc_init not called.
1235  *                  - EEXIST  pathname already exists and O_CREAT and
1236  *                  O_EXCL were used.
1237  *                  - EISDIR  pathname  refers  to  a  directory  and
1238  *                  the access requested involved writing.
1239  *                  - EACCES  The requested access to the file is not
1240  *                  allowed
1241  *                  - ENOENT  A directory component in pathname does
1242  *                  not exist.
1243  *                  - ENODEV The requested share does not exist.
1244  * @see             smbc_open()
1245  *
1246  */
1247
1248 int smbc_creat(const char *furl, mode_t mode);
1249
1250 /**@ingroup file
1251  * Read from a file using an opened file handle.
1252  *
1253  * @param fd        Open file handle from smbc_open() or smbc_creat()
1254  *
1255  * @param buf       Pointer to buffer to recieve read data
1256  *
1257  * @param bufsize   Size of buf in bytes
1258  *
1259  * @return          Number of bytes read, < 0 on error with errno set:
1260  *                  - EISDIR fd refers to a directory
1261  *                  - EBADF  fd  is  not  a valid file descriptor or
1262  *                  is not open for reading.
1263  *                  - EINVAL fd is attached to an object which is
1264  *                  unsuitable for reading, or no buffer passed or
1265  *                  smbc_init not called.
1266  *
1267  * @see             smbc_open(), smbc_write()
1268  *
1269  */
1270 ssize_t smbc_read(int fd, void *buf, size_t bufsize);
1271
1272
1273 /**@ingroup file
1274  * Write to a file using an opened file handle.
1275  *
1276  * @param fd        Open file handle from smbc_open() or smbc_creat()
1277  *
1278  * @param buf       Pointer to buffer to recieve read data
1279  *
1280  * @param bufsize   Size of buf in bytes
1281  *
1282  * @return          Number of bytes written, < 0 on error with errno set:
1283  *                  - EISDIR fd refers to a directory.
1284  *                  - EBADF  fd  is  not  a valid file descriptor or
1285  *                  is not open for reading.
1286  *                  - EINVAL fd is attached to an object which is
1287  *                  unsuitable for reading, or no buffer passed or
1288  *                  smbc_init not called.
1289  *
1290  * @see             smbc_open(), smbc_read()
1291  *
1292  */
1293 ssize_t smbc_write(int fd, const void *buf, size_t bufsize);
1294
1295
1296 /**@ingroup file
1297  * Seek to a specific location in a file.
1298  *
1299  * @param fd        Open file handle from smbc_open() or smbc_creat()
1300  *
1301  * @param offset    Offset in bytes from whence
1302  *
1303  * @param whence    A location in the file:
1304  *                  - SEEK_SET The offset is set to offset bytes from
1305  *                  the beginning of the file
1306  *                  - SEEK_CUR The offset is set to current location
1307  *                  plus offset bytes.
1308  *                  - SEEK_END The offset is set to the size of the
1309  *                  file plus offset bytes.
1310  *
1311  * @return          Upon successful completion, lseek returns the
1312  *                  resulting offset location as measured in bytes
1313  *                  from the beginning  of the file. Otherwise, a value
1314  *                  of (off_t)-1 is returned and errno is set to
1315  *                  indicate the error:
1316  *                  - EBADF  Fildes is not an open file descriptor.
1317  *                  - EINVAL Whence is not a proper value or smbc_init
1318  *                    not called.
1319  *
1320  * @todo Are all the whence values really supported?
1321  *
1322  * @todo Are errno values complete and correct?
1323  */
1324 off_t smbc_lseek(int fd, off_t offset, int whence);
1325
1326
1327 /**@ingroup file
1328  * Close an open file handle.
1329  *
1330  * @param fd        The file handle to close
1331  *
1332  * @return          0 on success, < 0 on error with errno set:
1333  *                  - EBADF  fd isn't a valid open file descriptor
1334  *                  - EINVAL smbc_init() failed or has not been called
1335  *
1336  * @see             smbc_open(), smbc_creat()
1337  */
1338 int smbc_close(int fd);
1339
1340
1341 /**@ingroup directory
1342  * Unlink (delete) a file or directory.
1343  *
1344  * @param furl      The smb url of the file to delete
1345  *
1346  * @return          0 on success, < 0 on error with errno set:
1347  *                  - EACCES or EPERM Write  access  to the directory
1348  *                  containing pathname is not allowed or one
1349  *                  of  the  directories in pathname did not allow
1350  *                  search (execute) permission
1351  *                  - ENOENT A directory component in pathname does
1352  *                  not exist
1353  *                  - EINVAL NULL was passed in the file param or
1354  *                    smbc_init not called.
1355  *                  - EACCES You do not have access to the file
1356  *                  - ENOMEM Insufficient kernel memory was available
1357  *
1358  * @see             smbc_rmdir()s
1359  *
1360  * @todo Are errno values complete and correct?
1361  */
1362 int smbc_unlink(const char *furl);
1363
1364
1365 /**@ingroup directory
1366  * Rename or move a file or directory.
1367  *
1368  * @param ourl      The original smb url (source url) of file or
1369  *                  directory to be moved
1370  *
1371  * @param nurl      The new smb url (destination url) of the file
1372  *                  or directory after the move.  Currently nurl must
1373  *                  be on the same share as ourl.
1374  *
1375  * @return          0 on success, < 0 on error with errno set:
1376  *                  - EISDIR nurl is an existing directory, but ourl is
1377  *                  not a directory.
1378  *                  - EEXIST nurl is  a  non-empty directory,
1379  *                  i.e., contains entries other than "." and ".."
1380  *                  - EINVAL The  new  url  contained  a path prefix
1381  *                  of the old, or, more generally, an  attempt was
1382  *                  made  to make a directory a subdirectory of itself
1383  *                  or smbc_init not called.
1384  *                  - ENOTDIR A component used as a directory in ourl
1385  *                  or nurl path is not, in fact, a directory.  Or,
1386  *                  ourl  is a directory, and newpath exists but is not
1387  *                  a directory.
1388  *                  - EACCES or EPERM Write access to the directory
1389  *                  containing ourl or nurl is not allowed for the
1390  *                  process's effective uid,  or  one of the
1391  *                  directories in ourl or nurl did not allow search
1392  *                  (execute) permission,  or ourl  was  a  directory
1393  *                  and did not allow write permission.
1394  *                  - ENOENT A  directory component in ourl or nurl
1395  *                  does not exist.
1396  *                  - EXDEV Rename across shares not supported.
1397  *                  - ENOMEM Insufficient kernel memory was available.
1398  *                  - EEXIST The target file, nurl, already exists.
1399  *
1400  *
1401  * @todo Are we going to support copying when urls are not on the same
1402  *       share?  I say no... NOTE. I agree for the moment.
1403  *
1404  */
1405 int smbc_rename(const char *ourl, const char *nurl);
1406
1407
1408 /**@ingroup directory
1409  * Open a directory used to obtain directory entries.
1410  *
1411  * @param durl      The smb url of the directory to open
1412  *
1413  * @return          Valid directory handle. < 0 on error with errno set:
1414  *                  - EACCES Permission denied.
1415  *                  - EINVAL A NULL file/URL was passed, or the URL would
1416  *                  not parse, or was of incorrect form or smbc_init not
1417  *                  called.
1418  *                  - ENOENT durl does not exist, or name is an
1419  *                  - ENOMEM Insufficient memory to complete the
1420  *                  operation.
1421  *                  - ENOTDIR name is not a directory.
1422  *                  - EPERM the workgroup could not be found.
1423  *                  - ENODEV the workgroup or server could not be found.
1424  *
1425  * @see             smbc_getdents(), smbc_readdir(), smbc_closedir()
1426  *
1427  */
1428 int smbc_opendir(const char *durl);
1429
1430
1431 /**@ingroup directory
1432  * Close a directory handle opened by smbc_opendir().
1433  *
1434  * @param dh        Directory handle to close
1435  *
1436  * @return          0 on success, < 0 on error with errno set:
1437  *                  - EBADF dh is an invalid directory handle
1438  *
1439  * @see             smbc_opendir()
1440  */
1441 int smbc_closedir(int dh);
1442
1443
1444 /**@ingroup directory
1445  * Get multiple directory entries.
1446  *
1447  * smbc_getdents() reads as many dirent structures from the an open
1448  * directory handle into a specified memory area as will fit.
1449  *
1450  * @param dh        Valid directory as returned by smbc_opendir()
1451  *
1452  * @param dirp      pointer to buffer that will receive the directory
1453  *                  entries.
1454  *
1455  * @param count     The size of the dirp buffer in bytes
1456  *
1457  * @returns         If any dirents returned, return will indicate the
1458  *                  total size. If there were no more dirents available,
1459  *                  0 is returned. < 0 indicates an error.
1460  *                  - EBADF  Invalid directory handle
1461  *                  - EINVAL Result buffer is too small or smbc_init
1462  *                  not called.
1463  *                  - ENOENT No such directory.
1464  * @see             , smbc_dirent, smbc_readdir(), smbc_open()
1465  *
1466  * @todo Are errno values complete and correct?
1467  *
1468  * @todo Add example code so people know how to parse buffers.
1469  */
1470 int smbc_getdents(unsigned int dh, struct smbc_dirent *dirp, int count);
1471
1472
1473 /**@ingroup directory
1474  * Get a single directory entry.
1475  *
1476  * @param dh        Valid directory as returned by smbc_opendir()
1477  *
1478  * @return          A pointer to a smbc_dirent structure, or NULL if an
1479  *                  error occurs or end-of-directory is reached:
1480  *                  - EBADF Invalid directory handle
1481  *                  - EINVAL smbc_init() failed or has not been called
1482  *
1483  * @see             smbc_dirent, smbc_getdents(), smbc_open()
1484  */
1485 struct smbc_dirent* smbc_readdir(unsigned int dh);
1486
1487
1488 /**@ingroup directory
1489  * Get the current directory offset.
1490  *
1491  * smbc_telldir() may be used in conjunction with smbc_readdir() and
1492  * smbc_lseekdir().
1493  *
1494  * @param dh        Valid directory as returned by smbc_opendir()
1495  *
1496  * @return          The current location in the directory stream or -1
1497  *                  if an error occur.  The current location is not
1498  *                  an offset. Becuase of the implementation, it is a
1499  *                  handle that allows the library to find the entry
1500  *                  later.
1501  *                  - EBADF dh is not a valid directory handle
1502  *                  - EINVAL smbc_init() failed or has not been called
1503  *                  - ENOTDIR if dh is not a directory
1504  *
1505  * @see             smbc_readdir()
1506  *
1507  */
1508 off_t smbc_telldir(int dh);
1509
1510
1511 /**@ingroup directory
1512  * lseek on directories.
1513  *
1514  * smbc_lseekdir() may be used in conjunction with smbc_readdir() and
1515  * smbc_telldir(). (rewind by smbc_lseekdir(fd, NULL))
1516  *
1517  * @param fd        Valid directory as returned by smbc_opendir()
1518  *
1519  * @param offset    The offset (as returned by smbc_telldir). Can be
1520  *                  NULL, in which case we will rewind
1521  *
1522  * @return          0 on success, -1 on failure
1523  *                  - EBADF dh is not a valid directory handle
1524  *                  - ENOTDIR if dh is not a directory
1525  *                  - EINVAL offset did not refer to a valid dirent or
1526  *                    smbc_init not called.
1527  *
1528  * @see             smbc_telldir()
1529  *
1530  *
1531  * @todo In what does the reture and errno values mean?
1532  */
1533 int smbc_lseekdir(int fd, off_t offset);
1534
1535 /**@ingroup directory
1536  * Create a directory.
1537  *
1538  * @param durl      The url of the directory to create
1539  *
1540  * @param mode      Specifies  the  permissions to use. It is modified
1541  *                  by the process's umask in the usual way: the
1542  *                  permissions of the created file are (mode & ~umask).
1543  *
1544  * @return          0 on success, < 0 on error with errno set:
1545  *                  - EEXIST directory url already exists
1546  *                  - EACCES The parent directory does not allow write
1547  *                  permission to the process, or one of the directories
1548  *                  - ENOENT A directory component in pathname does not
1549  *                  exist.
1550  *                  - EINVAL NULL durl passed or smbc_init not called.
1551  *                  - ENOMEM Insufficient memory was available.
1552  *
1553  * @see             smbc_rmdir()
1554  *
1555  */
1556 int smbc_mkdir(const char *durl, mode_t mode);
1557
1558
1559 /**@ingroup directory
1560  * Remove a directory.
1561  *
1562  * @param durl      The smb url of the directory to remove
1563  *
1564  * @return          0 on success, < 0 on error with errno set:
1565  *                  - EACCES or EPERM Write access to the directory
1566  *                  containing pathname was not allowed.
1567  *                  - EINVAL durl is NULL or smbc_init not called.
1568  *                  - ENOENT A directory component in pathname does not
1569  *                  exist.
1570  *                  - ENOTEMPTY directory contains entries.
1571  *                  - ENOMEM Insufficient kernel memory was available.
1572  *
1573  * @see             smbc_mkdir(), smbc_unlink()
1574  *
1575  * @todo Are errno values complete and correct?
1576  */
1577 int smbc_rmdir(const char *durl);
1578
1579
1580 /**@ingroup attribute
1581  * Get information about a file or directory.
1582  *
1583  * @param url       The smb url to get information for
1584  *
1585  * @param st        pointer to a buffer that will be filled with
1586  *                  standard Unix struct stat information.
1587  *
1588  * @return          0 on success, < 0 on error with errno set:
1589  *                  - ENOENT A component of the path file_name does not
1590  *                  exist.
1591  *                  - EINVAL a NULL url was passed or smbc_init not called.
1592  *                  - EACCES Permission denied.
1593  *                  - ENOMEM Out of memory
1594  *                  - ENOTDIR The target dir, url, is not a directory.
1595  *
1596  * @see             Unix stat()
1597  *
1598  */
1599 int smbc_stat(const char *url, struct stat *st);
1600
1601
1602 /**@ingroup attribute
1603  * Get file information via an file descriptor.
1604  *
1605  * @param fd        Open file handle from smbc_open() or smbc_creat()
1606  *
1607  * @param st        pointer to a buffer that will be filled with
1608  *                  standard Unix struct stat information.
1609  *
1610  * @return          EBADF  filedes is bad.
1611  *                  - EACCES Permission denied.
1612  *                  - EBADF fd is not a valid file descriptor
1613  *                  - EINVAL Problems occurred in the underlying routines
1614  *                    or smbc_init not called.
1615  *                  - ENOMEM Out of memory
1616  *
1617  * @see             smbc_stat(), Unix stat()
1618  *
1619  */
1620 int smbc_fstat(int fd, struct stat *st);
1621
1622
1623 /**@ingroup attribute
1624  * Get file system information for a specified path.
1625  *
1626  * @param url       The smb url to get information for
1627  *
1628  * @param st        pointer to a buffer that will be filled with
1629  *                  standard Unix struct statvfs information.
1630  *
1631  * @return          EBADF  filedes is bad.
1632  *                  - EACCES Permission denied.
1633  *                  - EBADF fd is not a valid file descriptor
1634  *                  - EINVAL Problems occurred in the underlying routines
1635  *                    or smbc_init not called.
1636  *                  - ENOMEM Out of memory
1637  *
1638  * @see             Unix fstatvfs()
1639  *
1640  */
1641 int
1642 smbc_statvfs(char *url,
1643              struct statvfs *st);
1644
1645 /**@ingroup attribute
1646  * Get file system information via an file descriptor.
1647  *
1648  * @param fd        Open file handle from smbc_open(), smbc_creat(),
1649  *                  or smbc_opendir()
1650  *
1651  * @param st        pointer to a buffer that will be filled with
1652  *                  standard Unix struct statvfs information.
1653  *
1654  * @return          EBADF  filedes is bad.
1655  *                  - EACCES Permission denied.
1656  *                  - EBADF fd is not a valid file descriptor
1657  *                  - EINVAL Problems occurred in the underlying routines
1658  *                    or smbc_init not called.
1659  *                  - ENOMEM Out of memory
1660  *
1661  * @see             Unix fstatvfs()
1662  *
1663  */
1664 int
1665 smbc_fstatvfs(int fd,
1666               struct statvfs *st);
1667
1668
1669 /**@ingroup attribute
1670  * Truncate a file given a file descriptor
1671  *
1672  * @param fd        Open file handle from smbc_open() or smbc_creat()
1673  *
1674  * @param size      size to truncate the file to
1675  *
1676  * @return          EBADF  filedes is bad.
1677  *                  - EACCES Permission denied.
1678  *                  - EBADF fd is not a valid file descriptor
1679  *                  - EINVAL Problems occurred in the underlying routines
1680  *                    or smbc_init not called.
1681  *                  - ENOMEM Out of memory
1682  *
1683  * @see             , Unix ftruncate()
1684  *
1685  */
1686 int smbc_ftruncate(int fd, off_t size);
1687
1688
1689 /**@ingroup attribute
1690  * Change the permissions of a file.
1691  *
1692  * @param url       The smb url of the file or directory to change
1693  *                  permissions of
1694  *
1695  * @param mode      The permissions to set:
1696  *                  - Put good explaination of permissions here!
1697  *
1698  * @return          0 on success, < 0 on error with errno set:
1699  *                  - EPERM  The effective UID does not match the owner
1700  *                  of the file, and is not zero
1701  *                  - ENOENT The file does not exist.
1702  *                  - ENOMEM Insufficient was available.
1703  *                  - ENOENT file or directory does not exist
1704  *
1705  * @todo Actually implement this fuction?
1706  *
1707  * @todo Are errno values complete and correct?
1708  */
1709 int smbc_chmod(const char *url, mode_t mode);
1710
1711 /**
1712  * @ingroup attribute
1713  * Change the last modification time on a file
1714  *
1715  * @param url       The smb url of the file or directory to change
1716  *                  the modification time of
1717  *
1718  * @param tbuf      An array of two timeval structures which contains,
1719  *                  respectively, the desired access and modification times.
1720  *                  NOTE: Only the tv_sec field off each timeval structure is
1721  *                  used.  The tv_usec (microseconds) portion is ignored.
1722  *
1723  * @return          0 on success, < 0 on error with errno set:
1724  *                  - EINVAL The client library is not properly initialized
1725  *                  - EPERM  Permission was denied.
1726  *
1727  */
1728 int smbc_utimes(const char *url, struct timeval *tbuf);
1729
1730 #ifdef HAVE_UTIME_H
1731 /**
1732  * @ingroup attribute
1733  * Change the last modification time on a file
1734  *
1735  * @param url       The smb url of the file or directory to change
1736  *                  the modification time of
1737  *
1738  * @param utbuf     A pointer to a utimebuf structure which contains the
1739  *                  desired access and modification times.
1740  *
1741  * @return          0 on success, < 0 on error with errno set:
1742  *                  - EINVAL The client library is not properly initialized
1743  *                  - ENOMEM No memory was available for internal needs
1744  *                  - EPERM  Permission was denied.
1745  *
1746  */
1747 int smbc_utime(const char *fname, struct utimbuf *utbuf);
1748 #endif
1749
1750 /**@ingroup attribute
1751  * Set extended attributes for a file.  This is used for modifying a file's
1752  * security descriptor (i.e. owner, group, and access control list)
1753  *
1754  * @param url       The smb url of the file or directory to set extended
1755  *                  attributes for.
1756  *
1757  * @param name      The name of an attribute to be changed.  Names are of
1758  *                  one of the following forms:
1759  *
1760  *                     system.nt_sec_desc.<attribute name>
1761  *                     system.nt_sec_desc.*
1762  *                     system.nt_sec_desc.*+
1763  *
1764  *                  where <attribute name> is one of:
1765  *
1766  *                     revision
1767  *                     owner
1768  *                     owner+
1769  *                     group
1770  *                     group+
1771  *                     acl:<name or sid>
1772  *                     acl+:<name or sid>
1773  *
1774  *                  In the forms "system.nt_sec_desc.*" and
1775  *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
1776  *                  literal, i.e. the string is provided exactly as shown, and
1777  *                  the value parameter should contain a complete security
1778  *                  descriptor with name:value pairs separated by tabs,
1779  *                  commas, or newlines (not spaces!).
1780  *
1781  *                  The plus sign ('+') indicates that SIDs should be mapped
1782  *                  to names.  Without the plus sign, SIDs are not mapped;
1783  *                  rather they are simply converted to a string format.
1784  *
1785  * @param value     The value to be assigned to the specified attribute name.
1786  *                  This buffer should contain only the attribute value if the
1787  *                  name was of the "system.nt_sec_desc.<attribute_name>"
1788  *                  form.  If the name was of the "system.nt_sec_desc.*" form
1789  *                  then a complete security descriptor, with name:value pairs
1790  *                  separated by tabs, commas, or newlines (not spaces!),
1791  *                  should be provided in this value buffer.  A complete
1792  *                  security descriptor will contain one or more entries
1793  *                  selected from the following:
1794  *
1795  *                    REVISION:<revision number>
1796  *                    OWNER:<sid or name>
1797  *                    GROUP:<sid or name>
1798  *                    ACL:<sid or name>:<type>/<flags>/<mask>
1799  *
1800  *                  The  revision of the ACL specifies the internal Windows NT
1801  *                  ACL revision for the security descriptor. If not specified
1802  *                  it defaults to  1.  Using values other than 1 may cause
1803  *                  strange behaviour.
1804  *
1805  *                  The owner and group specify the owner and group sids for
1806  *                  the object. If the attribute name (either '*+' with a
1807  *                  complete security descriptor, or individual 'owner+' or
1808  *                  'group+' attribute names) ended with a plus sign, the
1809  *                  specified name is resolved to a SID value, using the
1810  *                  server on which the file or directory resides.  Otherwise,
1811  *                  the value should be provided in SID-printable format as
1812  *                  S-1-x-y-z, and is used directly.  The <sid or name>
1813  *                  associated with the ACL: attribute should be provided
1814  *                  similarly.
1815  *
1816  * @param size      The number of the bytes of data in the value buffer
1817  *
1818  * @param flags     A bit-wise OR of zero or more of the following:
1819  *                    SMBC_XATTR_FLAG_CREATE -
1820  *                      fail if the named attribute already exists
1821  *                    SMBC_XATTR_FLAG_REPLACE -
1822  *                      fail if the attribute does not already exist
1823  *
1824  *                  If neither flag is specified, the specified attributes
1825  *                  will be added or replace existing attributes of the same
1826  *                  name, as necessary.
1827  *
1828  * @return          0 on success, < 0 on error with errno set:
1829  *                  - EINVAL  The client library is not properly initialized
1830  *                            or one of the parameters is not of a correct
1831  *                            form
1832  *                  - ENOMEM No memory was available for internal needs
1833  *                  - EEXIST  If the attribute already exists and the flag
1834  *                            SMBC_XATTR_FLAG_CREAT was specified
1835  *                  - ENOATTR If the attribute does not exist and the flag
1836  *                            SMBC_XATTR_FLAG_REPLACE was specified
1837  *                  - EPERM   Permission was denied.
1838  *                  - ENOTSUP The referenced file system does not support
1839  *                            extended attributes
1840  *
1841  * @note            Attribute names are compared in a case-insensitive
1842  *                  fashion.  All of the following are equivalent, although
1843  *                  the all-lower-case name is the preferred format:
1844  *                    system.nt_sec_desc.owner
1845  *                    SYSTEM.NT_SEC_DESC.OWNER
1846  *                    sYsTeM.nt_sEc_desc.owNER
1847  *
1848  */
1849 int smbc_setxattr(const char *url,
1850                   const char *name,
1851                   const void *value,
1852                   size_t size,
1853                   int flags);
1854
1855
1856 /**@ingroup attribute
1857  * Set extended attributes for a file.  This is used for modifying a file's
1858  * security descriptor (i.e. owner, group, and access control list).  The
1859  * POSIX function which this maps to would act on a symbolic link rather than
1860  * acting on what the symbolic link points to, but with no symbolic links in
1861  * SMB file systems, this function is functionally identical to
1862  * smbc_setxattr().
1863  *
1864  * @param url       The smb url of the file or directory to set extended
1865  *                  attributes for.
1866  *
1867  * @param name      The name of an attribute to be changed.  Names are of
1868  *                  one of the following forms:
1869  *
1870  *                     system.nt_sec_desc.<attribute name>
1871  *                     system.nt_sec_desc.*
1872  *                     system.nt_sec_desc.*+
1873  *
1874  *                  where <attribute name> is one of:
1875  *
1876  *                     revision
1877  *                     owner
1878  *                     owner+
1879  *                     group
1880  *                     group+
1881  *                     acl:<name or sid>
1882  *                     acl+:<name or sid>
1883  *
1884  *                  In the forms "system.nt_sec_desc.*" and
1885  *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
1886  *                  literal, i.e. the string is provided exactly as shown, and
1887  *                  the value parameter should contain a complete security
1888  *                  descriptor with name:value pairs separated by tabs,
1889  *                  commas, or newlines (not spaces!).
1890  *
1891  *                  The plus sign ('+') indicates that SIDs should be mapped
1892  *                  to names.  Without the plus sign, SIDs are not mapped;
1893  *                  rather they are simply converted to a string format.
1894  *
1895  * @param value     The value to be assigned to the specified attribute name.
1896  *                  This buffer should contain only the attribute value if the
1897  *                  name was of the "system.nt_sec_desc.<attribute_name>"
1898  *                  form.  If the name was of the "system.nt_sec_desc.*" form
1899  *                  then a complete security descriptor, with name:value pairs
1900  *                  separated by tabs, commas, or newlines (not spaces!),
1901  *                  should be provided in this value buffer.  A complete
1902  *                  security descriptor will contain one or more entries
1903  *                  selected from the following:
1904  *
1905  *                    REVISION:<revision number>
1906  *                    OWNER:<sid or name>
1907  *                    GROUP:<sid or name>
1908  *                    ACL:<sid or name>:<type>/<flags>/<mask>
1909  *
1910  *                  The  revision of the ACL specifies the internal Windows NT
1911  *                  ACL revision for the security descriptor. If not specified
1912  *                  it defaults to  1.  Using values other than 1 may cause
1913  *                  strange behaviour.
1914  *
1915  *                  The owner and group specify the owner and group sids for
1916  *                  the object. If the attribute name (either '*+' with a
1917  *                  complete security descriptor, or individual 'owner+' or
1918  *                  'group+' attribute names) ended with a plus sign, the
1919  *                  specified name is resolved to a SID value, using the
1920  *                  server on which the file or directory resides.  Otherwise,
1921  *                  the value should be provided in SID-printable format as
1922  *                  S-1-x-y-z, and is used directly.  The <sid or name>
1923  *                  associated with the ACL: attribute should be provided
1924  *                  similarly.
1925  *
1926  * @param size      The number of the bytes of data in the value buffer
1927  *
1928  * @param flags     A bit-wise OR of zero or more of the following:
1929  *                    SMBC_XATTR_FLAG_CREATE -
1930  *                      fail if the named attribute already exists
1931  *                    SMBC_XATTR_FLAG_REPLACE -
1932  *                      fail if the attribute does not already exist
1933  *
1934  *                  If neither flag is specified, the specified attributes
1935  *                  will be added or replace existing attributes of the same
1936  *                  name, as necessary.
1937  *
1938  * @return          0 on success, < 0 on error with errno set:
1939  *                  - EINVAL  The client library is not properly initialized
1940  *                            or one of the parameters is not of a correct
1941  *                            form
1942  *                  - ENOMEM No memory was available for internal needs
1943  *                  - EEXIST  If the attribute already exists and the flag
1944  *                            SMBC_XATTR_FLAG_CREAT was specified
1945  *                  - ENOATTR If the attribute does not exist and the flag
1946  *                            SMBC_XATTR_FLAG_REPLACE was specified
1947  *                  - EPERM   Permission was denied.
1948  *                  - ENOTSUP The referenced file system does not support
1949  *                            extended attributes
1950  *
1951  * @note            Attribute names are compared in a case-insensitive
1952  *                  fashion.  All of the following are equivalent, although
1953  *                  the all-lower-case name is the preferred format:
1954  *                    system.nt_sec_desc.owner
1955  *                    SYSTEM.NT_SEC_DESC.OWNER
1956  *                    sYsTeM.nt_sEc_desc.owNER
1957  *
1958  */
1959 int smbc_lsetxattr(const char *url,
1960                    const char *name,
1961                    const void *value,
1962                    size_t size,
1963                    int flags);
1964
1965
1966 /**@ingroup attribute
1967  * Set extended attributes for a file.  This is used for modifying a file's
1968  * security descriptor (i.e. owner, group, and access control list)
1969  *
1970  * @param fd        A file descriptor associated with an open file (as
1971  *                  previously returned by smbc_open(), to get extended
1972  *                  attributes for.
1973  *
1974  * @param name      The name of an attribute to be changed.  Names are of
1975  *                  one of the following forms:
1976  *
1977  *                     system.nt_sec_desc.<attribute name>
1978  *                     system.nt_sec_desc.*
1979  *                     system.nt_sec_desc.*+
1980  *
1981  *                  where <attribute name> is one of:
1982  *
1983  *                     revision
1984  *                     owner
1985  *                     owner+
1986  *                     group
1987  *                     group+
1988  *                     acl:<name or sid>
1989  *                     acl+:<name or sid>
1990  *
1991  *                  In the forms "system.nt_sec_desc.*" and
1992  *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
1993  *                  literal, i.e. the string is provided exactly as shown, and
1994  *                  the value parameter should contain a complete security
1995  *                  descriptor with name:value pairs separated by tabs,
1996  *                  commas, or newlines (not spaces!).
1997  *
1998  *                  The plus sign ('+') indicates that SIDs should be mapped
1999  *                  to names.  Without the plus sign, SIDs are not mapped;
2000  *                  rather they are simply converted to a string format.
2001  *
2002  * @param value     The value to be assigned to the specified attribute name.
2003  *                  This buffer should contain only the attribute value if the
2004  *                  name was of the "system.nt_sec_desc.<attribute_name>"
2005  *                  form.  If the name was of the "system.nt_sec_desc.*" form
2006  *                  then a complete security descriptor, with name:value pairs
2007  *                  separated by tabs, commas, or newlines (not spaces!),
2008  *                  should be provided in this value buffer.  A complete
2009  *                  security descriptor will contain one or more entries
2010  *                  selected from the following:
2011  *
2012  *                    REVISION:<revision number>
2013  *                    OWNER:<sid or name>
2014  *                    GROUP:<sid or name>
2015  *                    ACL:<sid or name>:<type>/<flags>/<mask>
2016  *
2017  *                  The  revision of the ACL specifies the internal Windows NT
2018  *                  ACL revision for the security descriptor. If not specified
2019  *                  it defaults to  1.  Using values other than 1 may cause
2020  *                  strange behaviour.
2021  *
2022  *                  The owner and group specify the owner and group sids for
2023  *                  the object. If the attribute name (either '*+' with a
2024  *                  complete security descriptor, or individual 'owner+' or
2025  *                  'group+' attribute names) ended with a plus sign, the
2026  *                  specified name is resolved to a SID value, using the
2027  *                  server on which the file or directory resides.  Otherwise,
2028  *                  the value should be provided in SID-printable format as
2029  *                  S-1-x-y-z, and is used directly.  The <sid or name>
2030  *                  associated with the ACL: attribute should be provided
2031  *                  similarly.
2032  *
2033  * @param size      The number of the bytes of data in the value buffer
2034  *
2035  * @param flags     A bit-wise OR of zero or more of the following:
2036  *                    SMBC_XATTR_FLAG_CREATE -
2037  *                      fail if the named attribute already exists
2038  *                    SMBC_XATTR_FLAG_REPLACE -
2039  *                      fail if the attribute does not already exist
2040  *
2041  *                  If neither flag is specified, the specified attributes
2042  *                  will be added or replace existing attributes of the same
2043  *                  name, as necessary.
2044  *
2045  * @return          0 on success, < 0 on error with errno set:
2046  *                  - EINVAL  The client library is not properly initialized
2047  *                            or one of the parameters is not of a correct
2048  *                            form
2049  *                  - ENOMEM No memory was available for internal needs
2050  *                  - EEXIST  If the attribute already exists and the flag
2051  *                            SMBC_XATTR_FLAG_CREAT was specified
2052  *                  - ENOATTR If the attribute does not exist and the flag
2053  *                            SMBC_XATTR_FLAG_REPLACE was specified
2054  *                  - EPERM   Permission was denied.
2055  *                  - ENOTSUP The referenced file system does not support
2056  *                            extended attributes
2057  *
2058  * @note            Attribute names are compared in a case-insensitive
2059  *                  fashion.  All of the following are equivalent, although
2060  *                  the all-lower-case name is the preferred format:
2061  *                    system.nt_sec_desc.owner
2062  *                    SYSTEM.NT_SEC_DESC.OWNER
2063  *                    sYsTeM.nt_sEc_desc.owNER
2064  *
2065  */
2066 int smbc_fsetxattr(int fd,
2067                    const char *name,
2068                    const void *value,
2069                    size_t size,
2070                    int flags);
2071
2072
2073 /**@ingroup attribute
2074  * Get extended attributes for a file.
2075  *
2076  * @param url       The smb url of the file or directory to get extended
2077  *                  attributes for.
2078  *
2079  * @param name      The name of an attribute to be retrieved.  Names are of
2080  *                  one of the following forms:
2081  *
2082  *                     system.nt_sec_desc.<attribute name>
2083  *                     system.nt_sec_desc.*
2084  *                     system.nt_sec_desc.*+
2085  *
2086  *                  where <attribute name> is one of:
2087  *
2088  *                     revision
2089  *                     owner
2090  *                     owner+
2091  *                     group
2092  *                     group+
2093  *                     acl:<name or sid>
2094  *                     acl+:<name or sid>
2095  *
2096  *                  In the forms "system.nt_sec_desc.*" and
2097  *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
2098  *                  literal, i.e. the string is provided exactly as shown, and
2099  *                  the value parameter will return a complete security
2100  *                  descriptor with name:value pairs separated by tabs,
2101  *                  commas, or newlines (not spaces!).
2102  *
2103  *                  The plus sign ('+') indicates that SIDs should be mapped
2104  *                  to names.  Without the plus sign, SIDs are not mapped;
2105  *                  rather they are simply converted to a string format.
2106  *
2107  * @param value     A pointer to a buffer in which the value of the specified
2108  *                  attribute will be placed (unless size is zero).
2109  *
2110  * @param size      The size of the buffer pointed to by value.  This parameter
2111  *                  may also be zero, in which case the size of the buffer
2112  *                  required to hold the attribute value will be returned,
2113  *                  but nothing will be placed into the value buffer.
2114  *
2115  * @return          0 on success, < 0 on error with errno set:
2116  *                  - EINVAL  The client library is not properly initialized
2117  *                            or one of the parameters is not of a correct
2118  *                            form
2119  *                  - ENOMEM No memory was available for internal needs
2120  *                  - EEXIST  If the attribute already exists and the flag
2121  *                            SMBC_XATTR_FLAG_CREAT was specified
2122  *                  - ENOATTR If the attribute does not exist and the flag
2123  *                            SMBC_XATTR_FLAG_REPLACE was specified
2124  *                  - EPERM   Permission was denied.
2125  *                  - ENOTSUP The referenced file system does not support
2126  *                            extended attributes
2127  *
2128  */
2129 int smbc_getxattr(const char *url,
2130                   const char *name,
2131                   const void *value,
2132                   size_t size);
2133
2134
2135 /**@ingroup attribute
2136  * Get extended attributes for a file.  The POSIX function which this maps to
2137  * would act on a symbolic link rather than acting on what the symbolic link
2138  * points to, but with no symbolic links in SMB file systems, this function
2139  * is functionally identical to smbc_getxattr().
2140  *
2141  * @param url       The smb url of the file or directory to get extended
2142  *                  attributes for.
2143  *
2144  * @param name      The name of an attribute to be retrieved.  Names are of
2145  *                  one of the following forms:
2146  *
2147  *                     system.nt_sec_desc.<attribute name>
2148  *                     system.nt_sec_desc.*
2149  *                     system.nt_sec_desc.*+
2150  *
2151  *                  where <attribute name> is one of:
2152  *
2153  *                     revision
2154  *                     owner
2155  *                     owner+
2156  *                     group
2157  *                     group+
2158  *                     acl:<name or sid>
2159  *                     acl+:<name or sid>
2160  *
2161  *                  In the forms "system.nt_sec_desc.*" and
2162  *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
2163  *                  literal, i.e. the string is provided exactly as shown, and
2164  *                  the value parameter will return a complete security
2165  *                  descriptor with name:value pairs separated by tabs,
2166  *                  commas, or newlines (not spaces!).
2167  *
2168  *                  The plus sign ('+') indicates that SIDs should be mapped
2169  *                  to names.  Without the plus sign, SIDs are not mapped;
2170  *                  rather they are simply converted to a string format.
2171  *
2172  * @param value     A pointer to a buffer in which the value of the specified
2173  *                  attribute will be placed (unless size is zero).
2174  *
2175  * @param size      The size of the buffer pointed to by value.  This parameter
2176  *                  may also be zero, in which case the size of the buffer
2177  *                  required to hold the attribute value will be returned,
2178  *                  but nothing will be placed into the value buffer.
2179  *
2180  * @return          0 on success, < 0 on error with errno set:
2181  *                  - EINVAL  The client library is not properly initialized
2182  *                            or one of the parameters is not of a correct
2183  *                            form
2184  *                  - ENOMEM No memory was available for internal needs
2185  *                  - EEXIST  If the attribute already exists and the flag
2186  *                            SMBC_XATTR_FLAG_CREAT was specified
2187  *                  - ENOATTR If the attribute does not exist and the flag
2188  *                            SMBC_XATTR_FLAG_REPLACE was specified
2189  *                  - EPERM   Permission was denied.
2190  *                  - ENOTSUP The referenced file system does not support
2191  *                            extended attributes
2192  *
2193  */
2194 int smbc_lgetxattr(const char *url,
2195                    const char *name,
2196                    const void *value,
2197                    size_t size);
2198
2199
2200 /**@ingroup attribute
2201  * Get extended attributes for a file.
2202  *
2203  * @param fd        A file descriptor associated with an open file (as
2204  *                  previously returned by smbc_open(), to get extended
2205  *                  attributes for.
2206  *
2207  * @param name      The name of an attribute to be retrieved.  Names are of
2208  *                  one of the following forms:
2209  *
2210  *                     system.nt_sec_desc.<attribute name>
2211  *                     system.nt_sec_desc.*
2212  *                     system.nt_sec_desc.*+
2213  *
2214  *                  where <attribute name> is one of:
2215  *
2216  *                     revision
2217  *                     owner
2218  *                     owner+
2219  *                     group
2220  *                     group+
2221  *                     acl:<name or sid>
2222  *                     acl+:<name or sid>
2223  *
2224  *                  In the forms "system.nt_sec_desc.*" and
2225  *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
2226  *                  literal, i.e. the string is provided exactly as shown, and
2227  *                  the value parameter will return a complete security
2228  *                  descriptor with name:value pairs separated by tabs,
2229  *                  commas, or newlines (not spaces!).
2230  *
2231  *                  The plus sign ('+') indicates that SIDs should be mapped
2232  *                  to names.  Without the plus sign, SIDs are not mapped;
2233  *                  rather they are simply converted to a string format.
2234  *
2235  * @param value     A pointer to a buffer in which the value of the specified
2236  *                  attribute will be placed (unless size is zero).
2237  *
2238  * @param size      The size of the buffer pointed to by value.  This parameter
2239  *                  may also be zero, in which case the size of the buffer
2240  *                  required to hold the attribute value will be returned,
2241  *                  but nothing will be placed into the value buffer.
2242  *
2243  * @return          0 on success, < 0 on error with errno set:
2244  *                  - EINVAL  The client library is not properly initialized
2245  *                            or one of the parameters is not of a correct
2246  *                            form
2247  *                  - ENOMEM No memory was available for internal needs
2248  *                  - EEXIST  If the attribute already exists and the flag
2249  *                            SMBC_XATTR_FLAG_CREAT was specified
2250  *                  - ENOATTR If the attribute does not exist and the flag
2251  *                            SMBC_XATTR_FLAG_REPLACE was specified
2252  *                  - EPERM   Permission was denied.
2253  *                  - ENOTSUP The referenced file system does not support
2254  *                            extended attributes
2255  *
2256  */
2257 int smbc_fgetxattr(int fd,
2258                    const char *name,
2259                    const void *value,
2260                    size_t size);
2261
2262
2263 /**@ingroup attribute
2264  * Remove extended attributes for a file.  This is used for modifying a file's
2265  * security descriptor (i.e. owner, group, and access control list)
2266  *
2267  * @param url       The smb url of the file or directory to remove the extended
2268  *                  attributes for.
2269  *
2270  * @param name      The name of an attribute to be removed.  Names are of
2271  *                  one of the following forms:
2272  *
2273  *                     system.nt_sec_desc.<attribute name>
2274  *                     system.nt_sec_desc.*
2275  *                     system.nt_sec_desc.*+
2276  *
2277  *                  where <attribute name> is one of:
2278  *
2279  *                     revision
2280  *                     owner
2281  *                     owner+
2282  *                     group
2283  *                     group+
2284  *                     acl:<name or sid>
2285  *                     acl+:<name or sid>
2286  *
2287  *                  In the forms "system.nt_sec_desc.*" and
2288  *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
2289  *                  literal, i.e. the string is provided exactly as shown, and
2290  *                  the value parameter will return a complete security
2291  *                  descriptor with name:value pairs separated by tabs,
2292  *                  commas, or newlines (not spaces!).
2293  *
2294  *                  The plus sign ('+') indicates that SIDs should be mapped
2295  *                  to names.  Without the plus sign, SIDs are not mapped;
2296  *                  rather they are simply converted to a string format.
2297  *
2298  * @return          0 on success, < 0 on error with errno set:
2299  *                  - EINVAL The client library is not properly initialized
2300  *                  - ENOMEM No memory was available for internal needs
2301  *                  - EPERM  Permission was denied.
2302  *                  - ENOTSUP The referenced file system does not support
2303  *                            extended attributes
2304  *
2305  */
2306 int smbc_removexattr(const char *url,
2307                      const char *name);
2308
2309
2310 /**@ingroup attribute
2311  * Remove extended attributes for a file.  This is used for modifying a file's
2312  * security descriptor (i.e. owner, group, and access control list) The POSIX
2313  * function which this maps to would act on a symbolic link rather than acting
2314  * on what the symbolic link points to, but with no symbolic links in SMB file
2315  * systems, this function is functionally identical to smbc_removexattr().
2316  *
2317  * @param url       The smb url of the file or directory to remove the extended
2318  *                  attributes for.
2319  *
2320  * @param name      The name of an attribute to be removed.  Names are of
2321  *                  one of the following forms:
2322  *
2323  *                     system.nt_sec_desc.<attribute name>
2324  *                     system.nt_sec_desc.*
2325  *                     system.nt_sec_desc.*+
2326  *
2327  *                  where <attribute name> is one of:
2328  *
2329  *                     revision
2330  *                     owner
2331  *                     owner+
2332  *                     group
2333  *                     group+
2334  *                     acl:<name or sid>
2335  *                     acl+:<name or sid>
2336  *
2337  *                  In the forms "system.nt_sec_desc.*" and
2338  *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
2339  *                  literal, i.e. the string is provided exactly as shown, and
2340  *                  the value parameter will return a complete security
2341  *                  descriptor with name:value pairs separated by tabs,
2342  *                  commas, or newlines (not spaces!).
2343  *
2344  *                  The plus sign ('+') indicates that SIDs should be mapped
2345  *                  to names.  Without the plus sign, SIDs are not mapped;
2346  *                  rather they are simply converted to a string format.
2347  *
2348  * @return          0 on success, < 0 on error with errno set:
2349  *                  - EINVAL The client library is not properly initialized
2350  *                  - ENOMEM No memory was available for internal needs
2351  *                  - EPERM  Permission was denied.
2352  *                  - ENOTSUP The referenced file system does not support
2353  *                            extended attributes
2354  *
2355  */
2356 int smbc_lremovexattr(const char *url,
2357                       const char *name);
2358
2359
2360 /**@ingroup attribute
2361  * Remove extended attributes for a file.  This is used for modifying a file's
2362  * security descriptor (i.e. owner, group, and access control list)
2363  *
2364  * @param fd        A file descriptor associated with an open file (as
2365  *                  previously returned by smbc_open(), to get extended
2366  *                  attributes for.
2367  *
2368  * @param name      The name of an attribute to be removed.  Names are of
2369  *                  one of the following forms:
2370  *
2371  *                     system.nt_sec_desc.<attribute name>
2372  *                     system.nt_sec_desc.*
2373  *                     system.nt_sec_desc.*+
2374  *
2375  *                  where <attribute name> is one of:
2376  *
2377  *                     revision
2378  *                     owner
2379  *                     owner+
2380  *                     group
2381  *                     group+
2382  *                     acl:<name or sid>
2383  *                     acl+:<name or sid>
2384  *
2385  *                  In the forms "system.nt_sec_desc.*" and
2386  *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
2387  *                  literal, i.e. the string is provided exactly as shown, and
2388  *                  the value parameter will return a complete security
2389  *                  descriptor with name:value pairs separated by tabs,
2390  *                  commas, or newlines (not spaces!).
2391  *
2392  *                  The plus sign ('+') indicates that SIDs should be mapped
2393  *                  to names.  Without the plus sign, SIDs are not mapped;
2394  *                  rather they are simply converted to a string format.
2395  *
2396  * @return          0 on success, < 0 on error with errno set:
2397  *                  - EINVAL The client library is not properly initialized
2398  *                  - ENOMEM No memory was available for internal needs
2399  *                  - EPERM  Permission was denied.
2400  *                  - ENOTSUP The referenced file system does not support
2401  *                            extended attributes
2402  *
2403  */
2404 int smbc_fremovexattr(int fd,
2405                       const char *name);
2406
2407
2408 /**@ingroup attribute
2409  * List the supported extended attribute names associated with a file
2410  *
2411  * @param url       The smb url of the file or directory to list the extended
2412  *                  attributes for.
2413  *
2414  * @param list      A pointer to a buffer in which the list of attributes for
2415  *                  the specified file or directory will be placed (unless
2416  *                  size is zero).
2417  *
2418  * @param size      The size of the buffer pointed to by list.  This parameter
2419  *                  may also be zero, in which case the size of the buffer
2420  *                  required to hold all of the attribute names will be
2421  *                  returned, but nothing will be placed into the list buffer.
2422  *
2423  * @return          0 on success, < 0 on error with errno set:
2424  *                  - EINVAL The client library is not properly initialized
2425  *                  - ENOMEM No memory was available for internal needs
2426  *                  - EPERM  Permission was denied.
2427  *                  - ENOTSUP The referenced file system does not support
2428  *                            extended attributes
2429  *
2430  * @note            This function always returns all attribute names supported
2431  *                  by NT file systems, regardless of whether the referenced
2432  *                  file system supports extended attributes (e.g. a Windows
2433  *                  2000 machine supports extended attributes if NTFS is used,
2434  *                  but not if FAT is used, and Windows 98 doesn't support
2435  *                  extended attributes at all.  Whether this is a feature or
2436  *                  a bug is yet to be decided.
2437  */
2438 int smbc_listxattr(const char *url,
2439                    char *list,
2440                    size_t size);
2441
2442 /**@ingroup attribute
2443  * List the supported extended attribute names associated with a file The
2444  * POSIX function which this maps to would act on a symbolic link rather than
2445  * acting on what the symbolic link points to, but with no symbolic links in
2446  * SMB file systems, this function is functionally identical to
2447  * smbc_listxattr().
2448  *
2449  * @param url       The smb url of the file or directory to list the extended
2450  *                  attributes for.
2451  *
2452  * @param list      A pointer to a buffer in which the list of attributes for
2453  *                  the specified file or directory will be placed (unless
2454  *                  size is zero).
2455  *
2456  * @param size      The size of the buffer pointed to by list.  This parameter
2457  *                  may also be zero, in which case the size of the buffer
2458  *                  required to hold all of the attribute names will be
2459  *                  returned, but nothing will be placed into the list buffer.
2460  *
2461  * @return          0 on success, < 0 on error with errno set:
2462  *                  - EINVAL The client library is not properly initialized
2463  *                  - ENOMEM No memory was available for internal needs
2464  *                  - EPERM  Permission was denied.
2465  *                  - ENOTSUP The referenced file system does not support
2466  *                            extended attributes
2467  *
2468  * @note            This function always returns all attribute names supported
2469  *                  by NT file systems, regardless of wether the referenced
2470  *                  file system supports extended attributes (e.g. a Windows
2471  *                  2000 machine supports extended attributes if NTFS is used,
2472  *                  but not if FAT is used, and Windows 98 doesn't support
2473  *                  extended attributes at all.  Whether this is a feature or
2474  *                  a bug is yet to be decided.
2475  */
2476 int smbc_llistxattr(const char *url,
2477                     char *list,
2478                     size_t size);
2479
2480 /**@ingroup attribute
2481  * List the supported extended attribute names associated with a file
2482  *
2483  * @param fd        A file descriptor associated with an open file (as
2484  *                  previously returned by smbc_open(), to get extended
2485  *                  attributes for.
2486  *
2487  * @param list      A pointer to a buffer in which the list of attributes for
2488  *                  the specified file or directory will be placed (unless
2489  *                  size is zero).
2490  *
2491  * @param size      The size of the buffer pointed to by list.  This parameter
2492  *                  may also be zero, in which case the size of the buffer
2493  *                  required to hold all of the attribute names will be
2494  *                  returned, but nothing will be placed into the list buffer.
2495  *
2496  * @return          0 on success, < 0 on error with errno set:
2497  *                  - EINVAL The client library is not properly initialized
2498  *                  - ENOMEM No memory was available for internal needs
2499  *                  - EPERM  Permission was denied.
2500  *                  - ENOTSUP The referenced file system does not support
2501  *                            extended attributes
2502  *
2503  * @note            This function always returns all attribute names supported
2504  *                  by NT file systems, regardless of wether the referenced
2505  *                  file system supports extended attributes (e.g. a Windows
2506  *                  2000 machine supports extended attributes if NTFS is used,
2507  *                  but not if FAT is used, and Windows 98 doesn't support
2508  *                  extended attributes at all.  Whether this is a feature or
2509  *                  a bug is yet to be decided.
2510  */
2511 int smbc_flistxattr(int fd,
2512                     char *list,
2513                     size_t size);
2514
2515 /**@ingroup print
2516  * Print a file given the name in fname. It would be a URL ...
2517  *
2518  * @param fname     The URL of a file on a remote SMB server that the
2519  *                  caller wants printed
2520  *
2521  * @param printq    The URL of the print share to print the file to.
2522  *
2523  * @return          0 on success, < 0 on error with errno set:
2524  *
2525  *                  - EINVAL fname or printq was NULL or smbc_init not
2526  *                    not called.
2527  *                  and errors returned by smbc_open
2528  *
2529  */
2530 int smbc_print_file(const char *fname, const char *printq);
2531
2532 /**@ingroup print
2533  * Open a print file that can be written to by other calls. This simply
2534  * does an smbc_open call after checking if there is a file name on the
2535  * URI. If not, a temporary name is added ...
2536  *
2537  * @param fname     The URL of the print share to print to?
2538  *
2539  * @returns         A file handle for the print file if successful.
2540  *                  Returns -1 if an error ocurred and errno has the values
2541  *                  - EINVAL fname was NULL or smbc_init not called.
2542  *                  - all errors returned by smbc_open
2543  *
2544  */
2545 int smbc_open_print_job(const char *fname);
2546
2547 /**@ingroup print
2548  * List the print jobs on a print share, for the moment, pass a callback
2549  *
2550  * @param purl      The url of the print share to list the jobs of
2551  *
2552  * @param fn        Callback function the receives printjob info
2553  *
2554  * @return          0 on success, < 0 on error with errno set:
2555  *                  - EINVAL fname was NULL or smbc_init not called
2556  *                  - EACCES ???
2557  */
2558 int smbc_list_print_jobs(const char *purl, smbc_list_print_job_fn fn);
2559
2560 /**@ingroup print
2561  * Delete a print job
2562  *
2563  * @param purl      Url of the print share
2564  *
2565  * @param id        The id of the job to delete
2566  *
2567  * @return          0 on success, < 0 on error with errno set:
2568  *                  - EINVAL fname was NULL or smbc_init not called
2569  *
2570  * @todo    what errno values are possible here?
2571  */
2572 int smbc_unlink_print_job(const char *purl, int id);
2573
2574 /**@ingroup callback
2575  * Remove a server from the cached server list it's unused.
2576  *
2577  * @param context    pointer to smb context
2578  *
2579  * @param srv        pointer to server to remove
2580  *
2581  * @return On success, 0 is returned. 1 is returned if the server could not
2582  *         be removed. Also useable outside libsmbclient.
2583  */
2584 int smbc_remove_unused_server(SMBCCTX * context, SMBCSRV * srv);
2585
2586 #ifdef __cplusplus
2587 }
2588 #endif
2589
2590 /**@ingroup directory
2591  * Convert strings of %xx to their single character equivalent.
2592  *
2593  * @param dest      A pointer to a buffer in which the resulting decoded
2594  *                  string should be placed.  This may be a pointer to the
2595  *                  same buffer as src_segment.
2596  *
2597  * @param src       A pointer to the buffer containing the URL to be decoded.
2598  *                  Any %xx sequences herein are converted to their single
2599  *                  character equivalent.  Each 'x' must be a valid hexadecimal
2600  *                  digit, or that % sequence is left undecoded.
2601  *
2602  * @param max_dest_len
2603  *                  The size of the buffer pointed to by dest_segment.
2604  *
2605  * @return          The number of % sequences which could not be converted
2606  *                  due to lack of two following hexadecimal digits.
2607  */
2608 #ifdef __cplusplus
2609 extern "C" {
2610 #endif
2611 int
2612 smbc_urldecode(char *dest, char * src, size_t max_dest_len);
2613 #ifdef __cplusplus
2614 }
2615 #endif
2616
2617
2618 /*
2619  * Convert any characters not specifically allowed in a URL into their %xx
2620  * equivalent.
2621  *
2622  * @param dest      A pointer to a buffer in which the resulting encoded
2623  *                  string should be placed.  Unlike smbc_urldecode(), this
2624  *                  must be a buffer unique from src.
2625  *
2626  * @param src       A pointer to the buffer containing the string to be encoded.
2627  *                  Any character not specifically allowed in a URL is converted
2628  *                  into its hexadecimal value and encoded as %xx.
2629  *
2630  * @param max_dest_len
2631  *                  The size of the buffer pointed to by dest_segment.
2632  *
2633  * @returns         The remaining buffer length.
2634  */
2635 #ifdef __cplusplus
2636 extern "C" {
2637 #endif
2638 int
2639 smbc_urlencode(char * dest, char * src, int max_dest_len);
2640 #ifdef __cplusplus
2641 }
2642 #endif
2643
2644
2645 /**@ingroup directory
2646  * Return the version of the linked Samba code, and thus the version of the
2647  * libsmbclient code.
2648  *
2649  * @return          The version string.
2650  */
2651 #ifdef __cplusplus
2652 extern "C" {
2653 #endif
2654 const char *
2655 smbc_version(void);
2656 #ifdef __cplusplus
2657 }
2658 #endif
2659
2660 /**@ingroup misc
2661  * Set the users credentials globally so they can be used for DFS
2662  * referrals. Probably best to use this function in the smbc_get_auth_data_fn
2663  * callback.
2664  *
2665  * @param workgroup      Workgroup of the user.
2666  *
2667  * @param user           Username of user.
2668  *
2669  * @param password       Password of user.
2670  *
2671  * @param use_kerberos   Whether to use Kerberos
2672  *
2673  * @param signing_state  One of these strings (all equivalents on same line):
2674  *                         "off", "no", "false"
2675  *                         "on", "yes", "true", "auto"
2676  *                         "force", "required", "forced"
2677  */
2678
2679 void
2680 smbc_set_credentials(const char *workgroup,
2681                      const char *user,
2682                      const char *password,
2683                      smbc_bool use_kerberos,
2684                      const char *signing_state);
2685
2686 /*
2687  * Wrapper around smbc_set_credentials.
2688  * Used to set correct credentials that will
2689  * be used to connect to DFS target share
2690  * in libsmbclient
2691  */
2692
2693 void
2694 smbc_set_credentials_with_fallback(SMBCCTX *ctx,
2695                                    const char *workgroup,
2696                                    const char *user,
2697                                    const char *password);
2698
2699 /**
2700  * @ingroup structure
2701  * Structure that contains a client context information
2702  * This structure is known as SMBCCTX
2703  *
2704  * DO NOT DIRECTLY MANIPULATE THE CONTEXT STRUCTURE!  The data in the context
2705  * structure should all be considered private to the library.  It remains here
2706  * only for backward compatibility.
2707  *
2708  * See the comments herein for use of the setter and getter functions which
2709  * should now be used for manipulating these values.  New features, functions,
2710  * etc., are not added here but rather in _internal where they are not
2711  * directly visible to applications.  This makes it much easier to maintain
2712  * ABI compatibility.
2713  */
2714 struct _SMBCCTX
2715 {
2716         /**
2717          * debug level
2718          *
2719          * DEPRECATED:
2720          * Use smbc_getDebug() and smbc_setDebug()
2721          */
2722         int     debug DEPRECATED_SMBC_INTERFACE;
2723
2724         /**
2725          * netbios name used for making connections
2726          *
2727          * DEPRECATED:
2728          * Use smbc_getNetbiosName() and smbc_setNetbiosName()
2729          */
2730         char * netbios_name DEPRECATED_SMBC_INTERFACE;
2731
2732         /**
2733          * workgroup name used for making connections
2734          *
2735          * DEPRECATED:
2736          * Use smbc_getWorkgroup() and smbc_setWorkgroup()
2737          */
2738         char * workgroup DEPRECATED_SMBC_INTERFACE;
2739
2740         /**
2741          * username used for making connections
2742          *
2743          * DEPRECATED:
2744          * Use smbc_getUser() and smbc_setUser()
2745          */
2746         char * user DEPRECATED_SMBC_INTERFACE;
2747
2748         /**
2749          * timeout used for waiting on connections / response data (in
2750          * milliseconds)
2751          *
2752          * DEPRECATED:
2753          * Use smbc_getTimeout() and smbc_setTimeout()
2754          */
2755         int timeout DEPRECATED_SMBC_INTERFACE;
2756
2757         /**
2758          * callable functions for files:
2759          * For usage and return values see the SMBC_* functions
2760          *
2761          * DEPRECATED:
2762          *
2763          * Use smbc_getFunction*() and smbc_setFunction*(), e.g.
2764          * smbc_getFunctionOpen(), smbc_setFunctionUnlink(), etc.
2765          */
2766         smbc_open_fn                    open DEPRECATED_SMBC_INTERFACE;
2767         smbc_creat_fn                   creat DEPRECATED_SMBC_INTERFACE;
2768         smbc_read_fn                    read DEPRECATED_SMBC_INTERFACE;
2769         smbc_write_fn                   write DEPRECATED_SMBC_INTERFACE;
2770         smbc_unlink_fn                  unlink DEPRECATED_SMBC_INTERFACE;
2771         smbc_rename_fn                  rename DEPRECATED_SMBC_INTERFACE;
2772         smbc_lseek_fn                   lseek DEPRECATED_SMBC_INTERFACE;
2773         smbc_stat_fn                    stat DEPRECATED_SMBC_INTERFACE;
2774         smbc_fstat_fn                   fstat DEPRECATED_SMBC_INTERFACE;
2775 #if 0 /* internal */
2776         smbc_ftruncate_fn               ftruncate_fn;
2777 #endif
2778         smbc_close_fn                   close_fn DEPRECATED_SMBC_INTERFACE;
2779         smbc_opendir_fn                 opendir DEPRECATED_SMBC_INTERFACE;
2780         smbc_closedir_fn                closedir DEPRECATED_SMBC_INTERFACE;
2781         smbc_readdir_fn                 readdir DEPRECATED_SMBC_INTERFACE;
2782         smbc_getdents_fn                getdents DEPRECATED_SMBC_INTERFACE;
2783         smbc_mkdir_fn                   mkdir DEPRECATED_SMBC_INTERFACE;
2784         smbc_rmdir_fn                   rmdir DEPRECATED_SMBC_INTERFACE;
2785         smbc_telldir_fn                 telldir DEPRECATED_SMBC_INTERFACE;
2786         smbc_lseekdir_fn                lseekdir DEPRECATED_SMBC_INTERFACE;
2787         smbc_fstatdir_fn                fstatdir DEPRECATED_SMBC_INTERFACE;
2788         smbc_chmod_fn                   chmod DEPRECATED_SMBC_INTERFACE;
2789         smbc_utimes_fn                  utimes DEPRECATED_SMBC_INTERFACE;
2790         smbc_setxattr_fn                setxattr DEPRECATED_SMBC_INTERFACE;
2791         smbc_getxattr_fn                getxattr DEPRECATED_SMBC_INTERFACE;
2792         smbc_removexattr_fn             removexattr DEPRECATED_SMBC_INTERFACE;
2793         smbc_listxattr_fn               listxattr DEPRECATED_SMBC_INTERFACE;
2794
2795         /* Printing-related functions */
2796         smbc_print_file_fn              print_file DEPRECATED_SMBC_INTERFACE;
2797         smbc_open_print_job_fn          open_print_job DEPRECATED_SMBC_INTERFACE;
2798         smbc_list_print_jobs_fn         list_print_jobs DEPRECATED_SMBC_INTERFACE;
2799         smbc_unlink_print_job_fn        unlink_print_job DEPRECATED_SMBC_INTERFACE;
2800
2801         /*
2802         ** Callbacks
2803         *
2804         * DEPRECATED:
2805         *
2806         * See the comment above each field, for the getter and setter
2807         * functions that should now be used.
2808         */
2809         struct _smbc_callbacks
2810         {
2811                 /**
2812                  * authentication function callback: called upon auth requests
2813                  *
2814                  * DEPRECATED:
2815                  * Use smbc_getFunctionAuthData(), smbc_setFunctionAuthData()
2816                  */
2817                 smbc_get_auth_data_fn auth_fn DEPRECATED_SMBC_INTERFACE;
2818
2819                 /**
2820                  * check if a server is still good
2821                  *
2822                  * DEPRECATED:
2823                  * Use smbc_getFunctionCheckServer(),
2824                  * smbc_setFunctionCheckServer()
2825                  */
2826                 smbc_check_server_fn check_server_fn DEPRECATED_SMBC_INTERFACE;
2827
2828                 /**
2829                  * remove a server if unused
2830                  *
2831                  * DEPRECATED:
2832                  * Use smbc_getFunctionRemoveUnusedServer(),
2833                  * smbc_setFunctionCheckServer()
2834                  */
2835                 smbc_remove_unused_server_fn remove_unused_server_fn DEPRECATED_SMBC_INTERFACE;
2836
2837                 /** Cache subsystem
2838                  *
2839                  * For an example cache system see
2840                  * samba/source/libsmb/libsmb_cache.c
2841                  *
2842                  * Cache subsystem * functions follow.
2843                  */
2844
2845                 /**
2846                  * server cache addition
2847                  *
2848                  * DEPRECATED:
2849                  * Use smbc_getFunctionAddCachedServer(),
2850                  * smbc_setFunctionAddCachedServer()
2851                  */
2852                 smbc_add_cached_srv_fn add_cached_srv_fn DEPRECATED_SMBC_INTERFACE;
2853
2854                 /**
2855                  * server cache lookup
2856                  *
2857                  * DEPRECATED:
2858                  * Use smbc_getFunctionGetCachedServer(),
2859                  * smbc_setFunctionGetCachedServer()
2860                  */
2861                 smbc_get_cached_srv_fn get_cached_srv_fn DEPRECATED_SMBC_INTERFACE;
2862
2863                 /**
2864                  * server cache removal
2865                  *
2866                  * DEPRECATED:
2867                  * Use smbc_getFunctionRemoveCachedServer(),
2868                  * smbc_setFunctionRemoveCachedServer()
2869                  */
2870                 smbc_remove_cached_srv_fn remove_cached_srv_fn DEPRECATED_SMBC_INTERFACE;
2871
2872                 /**
2873                  * server cache purging, try to remove all cached servers
2874                  * (disconnect)
2875                  *
2876                  * DEPRECATED:
2877                  * Use smbc_getFunctionPurgeCachedServers(),
2878                  * smbc_setFunctionPurgeCachedServers()
2879                  */
2880                 smbc_purge_cached_fn purge_cached_fn DEPRECATED_SMBC_INTERFACE;
2881         } callbacks;
2882
2883         /**
2884          * Space where the private data of the server cache used to be
2885          *
2886          * DEPRECATED:
2887          * Use smbc_getServerCacheData(), smbc_setServerCacheData()
2888          */
2889         void * reserved DEPRECATED_SMBC_INTERFACE;
2890
2891         /*
2892          * Very old configuration options.
2893          *
2894          * DEPRECATED:
2895          * Use one of the following functions instead:
2896          *   smbc_setOptionUseKerberos()
2897          *   smbc_getOptionUseKerberos()
2898          *   smbc_setOptionFallbackAfterKerberos()
2899          *   smbc_getOptionFallbackAfterKerberos()
2900          *   smbc_setOptionNoAutoAnonymousLogin()
2901          *   smbc_getOptionNoAutoAnonymousLogin()
2902          */
2903         int flags DEPRECATED_SMBC_INTERFACE;
2904
2905         /**
2906          * user options selections that apply to this session
2907          *
2908          * NEW OPTIONS ARE NOT ADDED HERE!
2909          *
2910          * DEPRECATED:
2911          * To set and retrieve options, use the smbc_setOption*() and
2912          * smbc_getOption*() functions.
2913          */
2914         struct _smbc_options {
2915                 int browse_max_lmb_count DEPRECATED_SMBC_INTERFACE;
2916                 int urlencode_readdir_entries DEPRECATED_SMBC_INTERFACE;
2917                 int one_share_per_server DEPRECATED_SMBC_INTERFACE;
2918         } options DEPRECATED_SMBC_INTERFACE;
2919
2920         /** INTERNAL DATA
2921          * do _NOT_ touch this from your program !
2922          */
2923         struct SMBC_internal_data * internal;
2924 };
2925
2926
2927 #endif /* SMBCLIENT_H_INCLUDED */