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