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