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