source3/include/libsmbclient.h

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