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