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