source3/include/libsmbclient.h

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