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 2 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, write to the Free Software
  23   Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  24   =====================================================================*/
  25
  26 #ifndef SMBCLIENT_H_INCLUDED
  27 #define SMBCLIENT_H_INCLUDED
  28
  29 /*-------------------------------------------------------------------*/
  30 /* The following are special comments to instruct DOXYGEN (automated
  31  * documentation tool:
  32 */
  33 /** \defgroup libsmbclient
  34 */
  35 /** \defgroup structure Data Structures Type and Constants
  36 *   \ingroup libsmbclient
  37 *   Data structures, types, and constants
  38 */
  39 /** \defgroup callback Callback function types
  40 *   \ingroup libsmbclient
  41 *   Callback functions
  42 */
  43 /** \defgroup file File Functions
  44 *   \ingroup libsmbclient
  45 *   Functions used to access individual file contents
  46 */
  47 /** \defgroup directory Directory Functions
  48 *   \ingroup libsmbclient
  49 *   Functions used to access directory entries
  50 */
  51 /** \defgroup attribute Attributes Functions
  52 *   \ingroup libsmbclient
  53 *   Functions used to view or change file and directory attributes
  54 */
  55 /** \defgroup print Print Functions
  56 *   \ingroup libsmbclient
  57 *   Functions used to access printing functionality
  58 */
  59 /** \defgroup misc Miscellaneous Functions
  60 *   \ingroup libsmbclient
  61 *   Functions that don't fit in to other categories
  62 */
  63 /*-------------------------------------------------------------------*/
  64
  65 /* Make sure we have the following includes for now ... */
  66 #include <sys/types.h>
  67 #include <sys/stat.h>
  68 #include <fcntl.h>
  69 #include <utime.h>
  70
  71 #define SMBC_BASE_FD        10000 /* smallest file descriptor returned */
  72
  73 #define SMBC_WORKGROUP      1
  74 #define SMBC_SERVER         2
  75 #define SMBC_FILE_SHARE     3
  76 #define SMBC_PRINTER_SHARE  4
  77 #define SMBC_COMMS_SHARE    5
  78 #define SMBC_IPC_SHARE      6
  79 #define SMBC_DIR            7
  80 #define SMBC_FILE           8
  81 #define SMBC_LINK           9
  82
  83 /**@ingroup structure
  84  * Structure that represents a directory entry.
  85  *
  86  */
  87 struct smbc_dirent
  88 {
  89         /** Type of entity.
  90             SMBC_WORKGROUP=1,
  91             SMBC_SERVER=2,
  92             SMBC_FILE_SHARE=3,
  93             SMBC_PRINTER_SHARE=4,
  94             SMBC_COMMS_SHARE=5,
  95             SMBC_IPC_SHARE=6,
  96             SMBC_DIR=7,
  97             SMBC_FILE=8,
  98             SMBC_LINK=9,*/
  99         unsigned int smbc_type;
 100
 101         /** Length of this smbc_dirent in bytes
 102          */
 103         unsigned int dirlen;
 104         /** The length of the comment string in bytes (includes null
 105          *  terminator)
 106          */
 107         unsigned int commentlen;
 108         /** Points to the null terminated comment string
 109          */
 110         char *comment;
 111         /** The length of the name string in bytes (includes null
 112          *  terminator)
 113          */
 114         unsigned int namelen;
 115         /** Points to the null terminated name string
 116          */
 117         char name[1];
 118 };
 119
 120 /*
 121  * Flags for smbc_setxattr()
 122  *   Specify a bitwise OR of these, or 0 to add or replace as necessary
 123  */
 124 #define SMBC_XATTR_FLAG_CREATE       0x1 /* fail if attr already exists */
 125 #define SMBC_XATTR_FLAG_REPLACE      0x2 /* fail if attr does not exist */
 126
 127
 128 #ifndef ENOATTR
 129 # define ENOATTR ENOENT        /* No such attribute */
 130 #endif
 131
 132
 133
 134
 135 /**@ingroup structure
 136  * Structure that represents a print job.
 137  *
 138  */
 139 #ifndef _CLIENT_H
 140 struct print_job_info
 141 {
 142         /** numeric ID of the print job
 143          */
 144         unsigned short id;
 145
 146         /** represents print job priority (lower numbers mean higher priority)
 147          */
 148         unsigned short priority;
 149
 150         /** Size of the print job
 151          */
 152         size_t size;
 153
 154         /** Name of the user that owns the print job
 155          */
 156         char user[128];
 157
 158         /** Name of the print job. This will have no name if an anonymous print
 159          *  file was opened. Ie smb://server/printer
 160          */
 161         char name[128];
 162
 163         /** Time the print job was spooled
 164          */
 165         time_t t;
 166 };
 167 #endif /* _CLIENT_H */
 168
 169
 170 /**@ingroup structure
 171  * Server handle
 172  */
 173 typedef struct _SMBCSRV  SMBCSRV;
 174
 175 /**@ingroup structure
 176  * File or directory handle
 177  */
 178 typedef struct _SMBCFILE SMBCFILE;
 179
 180 /**@ingroup structure
 181  * File or directory handle
 182  */
 183 typedef struct _SMBCCTX SMBCCTX;
 184
 185
 186
 187
 188
 189 /**@ingroup callback
 190  * Authentication callback function type.
 191  *
 192  * Type for the the authentication function called by the library to
 193  * obtain authentication credentals
 194  *
 195  * @param srv       Server being authenticated to
 196  *
 197  * @param shr       Share being authenticated to
 198  *
 199  * @param wg        Pointer to buffer containing a "hint" for the
 200  *                  workgroup to be authenticated.  Should be filled in
 201  *                  with the correct workgroup if the hint is wrong.
 202  *
 203  * @param wglen     The size of the workgroup buffer in bytes
 204  *
 205  * @param un        Pointer to buffer containing a "hint" for the
 206  *                  user name to be use for authentication. Should be
 207  *                  filled in with the correct workgroup if the hint is
 208  *                  wrong.
 209  *
 210  * @param unlen     The size of the username buffer in bytes
 211  *
 212  * @param pw        Pointer to buffer containing to which password
 213  *                  copied
 214  *
 215  * @param pwlen     The size of the password buffer in bytes
 216  *
 217  */
 218 typedef void (*smbc_get_auth_data_fn)(const char *srv,
 219                                       const char *shr,
 220                                       char *wg, int wglen,
 221                                       char *un, int unlen,
 222                                       char *pw, int pwlen);
 223
 224
 225 /**@ingroup callback
 226  * Print job info callback function type.
 227  *
 228  * @param i         pointer to print job information structure
 229  *
 230  */
 231 typedef void (*smbc_list_print_job_fn)(struct print_job_info *i);
 232
 233
 234 /**@ingroup callback
 235  * Check if a server is still good
 236  *
 237  * @param c         pointer to smb context
 238  *
 239  * @param srv       pointer to server to check
 240  *
 241  * @return          0 when connection is good. 1 on error.
 242  *
 243  */
 244 typedef int (*smbc_check_server_fn)(SMBCCTX * c, SMBCSRV *srv);
 245
 246 /**@ingroup callback
 247  * Remove a server if unused
 248  *
 249  * @param c         pointer to smb context
 250  *
 251  * @param srv       pointer to server to remove
 252  *
 253  * @return          0 on success. 1 on failure.
 254  *
 255  */
 256 typedef int (*smbc_remove_unused_server_fn)(SMBCCTX * c, SMBCSRV *srv);
 257
 258
 259 /**@ingroup callback
 260  * Add a server to the cache system
 261  *
 262  * @param c         pointer to smb context
 263  *
 264  * @param srv       pointer to server to add
 265  *
 266  * @param server    server name
 267  *
 268  * @param share     share name
 269  *
 270  * @param workgroup workgroup used to connect
 271  *
 272  * @param username  username used to connect
 273  *
 274  * @return          0 on success. 1 on failure.
 275  *
 276  */
 277 typedef int (*smbc_add_cached_srv_fn)   (SMBCCTX * c, SMBCSRV *srv,
 278                                     const char * server, const char * share,
 279                                     const char * workgroup, const char * username);
 280
 281 /**@ingroup callback
 282  * Look up a server in the cache system
 283  *
 284  * @param c         pointer to smb context
 285  *
 286  * @param server    server name to match
 287  *
 288  * @param share     share name to match
 289  *
 290  * @param workgroup workgroup to match
 291  *
 292  * @param username  username to match
 293  *
 294  * @return          pointer to SMBCSRV on success. NULL on failure.
 295  *
 296  */
 297 typedef SMBCSRV * (*smbc_get_cached_srv_fn)   (SMBCCTX * c, const char * server,
 298                                                const char * share, const char * workgroup,
 299                                                const char * username);
 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 remove
 307  *
 308  * @return          0 when found and removed. 1 on failure.
 309  *
 310  */
 311 typedef int (*smbc_remove_cached_srv_fn)(SMBCCTX * c, SMBCSRV *srv);
 312
 313
 314 /**@ingroup callback
 315  * Try to remove all servers from the cache system and disconnect
 316  *
 317  * @param c         pointer to smb context
 318  *
 319  * @return          0 when found and removed. 1 on failure.
 320  *
 321  */
 322 typedef int (*smbc_purge_cached_fn)     (SMBCCTX * c);
 323
 324
 325
 326
 327 /**@ingroup structure
 328  * Structure that contains a client context information
 329  * This structure is know as SMBCCTX
 330  */
 331 struct _SMBCCTX {
 332         /** debug level
 333          */
 334         int     debug;
 335
 336         /** netbios name used for making connections
 337          */
 338         char * netbios_name;
 339
 340         /** workgroup name used for making connections
 341          */
 342         char * workgroup;
 343
 344         /** username used for making connections
 345          */
 346         char * user;
 347
 348         /** timeout used for waiting on connections / response data (in milliseconds)
 349          */
 350         int timeout;
 351
 352         /** callable functions for files:
 353          * For usage and return values see the smbc_* functions
 354          */
 355         SMBCFILE * (*open)    (SMBCCTX *c, const char *fname, int flags, mode_t mode);
 356         SMBCFILE * (*creat)   (SMBCCTX *c, const char *path, mode_t mode);
 357         ssize_t    (*read)    (SMBCCTX *c, SMBCFILE *file, void *buf, size_t count);
 358         ssize_t    (*write)   (SMBCCTX *c, SMBCFILE *file, void *buf, size_t count);
 359         int        (*unlink)  (SMBCCTX *c, const char *fname);
 360         int        (*rename)  (SMBCCTX *ocontext, const char *oname,
 361                                SMBCCTX *ncontext, const char *nname);
 362         off_t      (*lseek)   (SMBCCTX *c, SMBCFILE * file, off_t offset, int whence);
 363         int        (*stat)    (SMBCCTX *c, const char *fname, struct stat *st);
 364         int        (*fstat)   (SMBCCTX *c, SMBCFILE *file, struct stat *st);
 365         int        (*close)   (SMBCCTX *c, SMBCFILE *file);
 366
 367         /** callable functions for dirs
 368          */
 369         SMBCFILE * (*opendir) (SMBCCTX *c, const char *fname);
 370         int        (*closedir)(SMBCCTX *c, SMBCFILE *dir);
 371         struct smbc_dirent * (*readdir)(SMBCCTX *c, SMBCFILE *dir);
 372         int        (*getdents)(SMBCCTX *c, SMBCFILE *dir,
 373                                struct smbc_dirent *dirp, int count);
 374         int        (*mkdir)   (SMBCCTX *c, const char *fname, mode_t mode);
 375         int        (*rmdir)   (SMBCCTX *c, const char *fname);
 376         off_t      (*telldir) (SMBCCTX *c, SMBCFILE *dir);
 377         int        (*lseekdir)(SMBCCTX *c, SMBCFILE *dir, off_t offset);
 378         int        (*fstatdir)(SMBCCTX *c, SMBCFILE *dir, struct stat *st);
 379         int        (*chmod)(SMBCCTX *c, const char *fname, mode_t mode);
 380         int        (*utimes)(SMBCCTX *c,
 381                              const char *fname, struct timeval *tbuf);
 382         int        (*setxattr)(SMBCCTX *context,
 383                                const char *fname,
 384                                const char *name,
 385                                const void *value,
 386                                size_t size,
 387                                int flags);
 388         int        (*getxattr)(SMBCCTX *context,
 389                                const char *fname,
 390                                const char *name,
 391                                const void *value,
 392                                size_t size);
 393         int        (*removexattr)(SMBCCTX *context,
 394                                   const char *fname,
 395                                   const char *name);
 396         int        (*listxattr)(SMBCCTX *context,
 397                                 const char *fname,
 398                                 char *list,
 399                                 size_t size);
 400
 401         /** callable functions for printing
 402          */
 403         int        (*print_file)(SMBCCTX *c_file, const char *fname,
 404                                  SMBCCTX *c_print, const char *printq);
 405         SMBCFILE * (*open_print_job)(SMBCCTX *c, const char *fname);
 406         int        (*list_print_jobs)(SMBCCTX *c, const char *fname, smbc_list_print_job_fn fn);
 407         int        (*unlink_print_job)(SMBCCTX *c, const char *fname, int id);
 408
 409
 410         /** Callbacks
 411          * These callbacks _always_ have to be initialized because they will not be checked
 412          * at dereference for increased speed.
 413          */
 414         struct _smbc_callbacks {
 415                 /** authentication function callback: called upon auth requests
 416                  */
 417                 smbc_get_auth_data_fn auth_fn;
 418
 419                 /** check if a server is still good
 420                  */
 421                 smbc_check_server_fn check_server_fn;
 422
 423                 /** remove a server if unused
 424                  */
 425                 smbc_remove_unused_server_fn remove_unused_server_fn;
 426
 427                 /** Cache subsystem
 428                  * For an example cache system see samba/source/libsmb/libsmb_cache.c
 429                  * Cache subsystem functions follow.
 430                  */
 431
 432                 /** server cache addition
 433                  */
 434                 smbc_add_cached_srv_fn add_cached_srv_fn;
 435
 436                 /** server cache lookup
 437                  */
 438                 smbc_get_cached_srv_fn get_cached_srv_fn;
 439
 440                 /** server cache removal
 441                  */
 442                 smbc_remove_cached_srv_fn remove_cached_srv_fn;
 443
 444                 /** server cache purging, try to remove all cached servers (disconnect)
 445                  */
 446                 smbc_purge_cached_fn purge_cached_fn;
 447         } callbacks;
 448
 449
 450         /** Space to store private data of the server cache.
 451          */
 452         struct smbc_server_cache * server_cache;
 453
 454         /** INTERNAL DATA
 455          * do _NOT_ touch this from your program !
 456          */
 457         struct smbc_internal_data * internal;
 458
 459 };
 460
 461
 462 /**@ingroup misc
 463  * Create a new SBMCCTX (a context).
 464  *
 465  * Must be called before the context is passed to smbc_context_init()
 466  *
 467  * @return          The given SMBCCTX pointer on success, NULL on error with errno set:
 468  *                  - ENOMEM Out of memory
 469  *
 470  * @see             smbc_free_context(), smbc_init_context()
 471  *
 472  * @note            Do not forget to smbc_init_context() the returned SMBCCTX pointer !
 473  */
 474 SMBCCTX * smbc_new_context(void);
 475
 476 /**@ingroup misc
 477  * Delete a SBMCCTX (a context) acquired from smbc_new_context().
 478  *
 479  * The context will be deleted if possible.
 480  *
 481  * @param context   A pointer to a SMBCCTX obtained from smbc_new_context()
 482  *
 483  * @param shutdown_ctx   If 1, all connections and files will be closed even if they are busy.
 484  *
 485  *
 486  * @return          Returns 0 on succes. Returns 1 on failure with errno set:
 487  *                  - EBUSY Server connections are still used, Files are open or cache
 488  *                          could not be purged
 489  *                  - EBADF context == NULL
 490  *
 491  * @see             smbc_new_context()
 492  *
 493  * @note            It is advised to clean up all the contexts with shutdown_ctx set to 1
 494  *                  just before exit()'ing. When shutdown_ctx is 0, this function can be
 495  *                  use in periodical cleanup functions for example.
 496  */
 497 int smbc_free_context(SMBCCTX * context, int shutdown_ctx);
 498
 499
 500 /**@ingroup misc
 501  * Initialize a SBMCCTX (a context).
 502  *
 503  * Must be called before using any SMBCCTX API function
 504  *
 505  * @param context   A pointer to a SMBCCTX obtained from smbc_new_context()
 506  *
 507  * @return          A pointer to the given SMBCCTX on success, NULL on error with errno set:
 508  *                  - EBADF  NULL context given
 509  *                  - ENOMEM Out of memory
 510  *                  - ENOENT The smb.conf file would not load
 511  *
 512  * @see             smbc_new_context()
 513  *
 514  * @note            my_context = smbc_init_context(smbc_new_context()) is perfectly safe,
 515  *                  but it might leak memory on smbc_context_init() failure. Avoid this.
 516  *                  You'll have to call smbc_free_context() yourself on failure.
 517  */
 518
 519 SMBCCTX * smbc_init_context(SMBCCTX * context);
 520
 521 /**@ingroup misc
 522  * Initialize the samba client library.
 523  *
 524  * Must be called before using any of the smbclient API function
 525  *
 526  * @param fn        The function that will be called to obtaion
 527  *                  authentication credentials.
 528  *
 529  * @param debug     Allows caller to set the debug level. Can be
 530  *                  changed in smb.conf file. Allows caller to set
 531  *                  debugging if no smb.conf.
 532  *
 533  * @return          0 on success, < 0 on error with errno set:
 534  *                  - ENOMEM Out of memory
 535  *                  - ENOENT The smb.conf file would not load
 536  *
 537  */
 538
 539 int smbc_init(smbc_get_auth_data_fn fn, int debug);
 540
 541 /**@ingroup misc
 542  * Set or retrieve the compatibility library's context pointer
 543  *
 544  * @param context   New context to use, or NULL.  If a new context is provided,
 545  *                  it must have allocated with smbc_new_context() and
 546  *                  initialized with smbc_init_context(), followed, optionally,
 547  *                  by some manual changes to some of the non-internal fields.
 548  *
 549  * @return          The old context.
 550  *
 551  * @see             smbc_new_context(), smbc_init_context(), smbc_init()
 552  *
 553  * @note            This function may be called prior to smbc_init() to force
 554  *                  use of the next context without any internal calls to
 555  *                  smbc_new_context() or smbc_init_context().  It may also
 556  *                  be called after smbc_init() has already called those two
 557  *                  functions, to replace the existing context with a new one.
 558  *                  Care should be taken, in this latter case, to ensure that
 559  *                  the server cache and any data allocated by the
 560  *                  authentication functions have been freed, if necessary.
 561  */
 562
 563 SMBCCTX * smbc_set_context(SMBCCTX * new_context);
 564
 565 /**@ingroup file
 566  * Open a file on an SMB server.
 567  *
 568  * @param furl      The smb url of the file to be opened.
 569  *
 570  * @param flags     Is one of O_RDONLY, O_WRONLY or O_RDWR which
 571  *                  request opening  the  file  read-only,write-only
 572  *                  or read/write. flags may also be bitwise-or'd with
 573  *                  one or  more of  the following:
 574  *                  O_CREAT - If the file does not exist it will be
 575  *                  created.
 576  *                  O_EXCL - When  used with O_CREAT, if the file
 577  *                  already exists it is an error and the open will
 578  *                  fail.
 579  *                  O_TRUNC - If the file already exists it will be
 580  *                  truncated.
 581  *                  O_APPEND The  file  is  opened  in  append mode
 582  *
 583  * @param mode      mode specifies the permissions to use if a new
 584  *                  file is created.  It  is  modified  by  the
 585  *                  process's umask in the usual way: the permissions
 586  *                  of the created file are (mode & ~umask)
 587  *
 588  *                  Not currently use, but there for future use.
 589  *                  We will map this to SYSTEM, HIDDEN, etc bits
 590  *                  that reverses the mapping that smbc_fstat does.
 591  *
 592  * @return          Valid file handle, < 0 on error with errno set:
 593  *                  - ENOMEM  Out of memory
 594  *                  - EINVAL if an invalid parameter passed, like no
 595  *                  file, or smbc_init not called.
 596  *                  - EEXIST  pathname already exists and O_CREAT and
 597  *                  O_EXCL were used.
 598  *                  - EISDIR  pathname  refers  to  a  directory  and
 599  *                  the access requested involved writing.
 600  *                  - EACCES  The requested access to the file is not
 601  *                  allowed
 602  *                  - ENODEV The requested share does not exist
 603  *                  - ENOTDIR A file on the path is not a directory
 604  *                  - ENOENT  A directory component in pathname does
 605  *                  not exist.
 606  *
 607  * @see             smbc_creat()
 608  *
 609  * @note            This call uses an underlying routine that may create
 610  *                  a new connection to the server specified in the URL.
 611  *                  If the credentials supplied in the URL, or via the
 612  *                  auth_fn in the smbc_init call, fail, this call will
 613  *                  try again with an empty username and password. This
 614  *                  often gets mapped to the guest account on some machines.
 615  */
 616
 617 int smbc_open(const char *furl, int flags, mode_t mode);
 618
 619 /**@ingroup file
 620  * Create a file on an SMB server.
 621  *
 622  * Same as calling smbc_open() with flags = O_CREAT|O_WRONLY|O_TRUNC
 623  *
 624  * @param furl      The smb url of the file to be created
 625  *
 626  * @param mode      mode specifies the permissions to use if  a  new
 627  *                  file is created.  It  is  modified  by  the
 628  *                  process's umask in the usual way: the permissions
 629  *                  of the created file are (mode & ~umask)
 630  *
 631  *                  NOTE, the above is not true. We are dealing with
 632  *                  an SMB server, which has no concept of a umask!
 633  *
 634  * @return          Valid file handle, < 0 on error with errno set:
 635  *                  - ENOMEM  Out of memory
 636  *                  - EINVAL if an invalid parameter passed, like no
 637  *                  file, or smbc_init not called.
 638  *                  - EEXIST  pathname already exists and O_CREAT and
 639  *                  O_EXCL were used.
 640  *                  - EISDIR  pathname  refers  to  a  directory  and
 641  *                  the access requested involved writing.
 642  *                  - EACCES  The requested access to the file is not
 643  *                  allowed
 644  *                  - ENOENT  A directory component in pathname does
 645  *                  not exist.
 646  *                  - ENODEV The requested share does not exist.
 647  * @see             smbc_open()
 648  *
 649  */
 650
 651 int smbc_creat(const char *furl, mode_t mode);
 652
 653 /**@ingroup file
 654  * Read from a file using an opened file handle.
 655  *
 656  * @param fd        Open file handle from smbc_open() or smbc_creat()
 657  *
 658  * @param buf       Pointer to buffer to recieve read data
 659  *
 660  * @param bufsize   Size of buf in bytes
 661  *
 662  * @return          Number of bytes read, < 0 on error with errno set:
 663  *                  - EISDIR fd refers to a directory
 664  *                  - EBADF  fd  is  not  a valid file descriptor or
 665  *                  is not open for reading.
 666  *                  - EINVAL fd is attached to an object which is
 667  *                  unsuitable for reading, or no buffer passed or
 668  *                  smbc_init not called.
 669  *
 670  * @see             smbc_open(), smbc_write()
 671  *
 672  */
 673 ssize_t smbc_read(int fd, void *buf, size_t bufsize);
 674
 675
 676 /**@ingroup file
 677  * Write to a file using an opened file handle.
 678  *
 679  * @param fd        Open file handle from smbc_open() or smbc_creat()
 680  *
 681  * @param buf       Pointer to buffer to recieve read data
 682  *
 683  * @param bufsize   Size of buf in bytes
 684  *
 685  * @return          Number of bytes written, < 0 on error with errno set:
 686  *                  - EISDIR fd refers to a directory.
 687  *                  - EBADF  fd  is  not  a valid file descriptor or
 688  *                  is not open for reading.
 689  *                  - EINVAL fd is attached to an object which is
 690  *                  unsuitable for reading, or no buffer passed or
 691  *                  smbc_init not called.
 692  *
 693  * @see             smbc_open(), smbc_read()
 694  *
 695  */
 696 ssize_t smbc_write(int fd, void *buf, size_t bufsize);
 697
 698
 699 /**@ingroup file
 700  * Seek to a specific location in a file.
 701  *
 702  * @param fd        Open file handle from smbc_open() or smbc_creat()
 703  *
 704  * @param offset    Offset in bytes from whence
 705  *
 706  * @param whence    A location in the file:
 707  *                  - SEEK_SET The offset is set to offset bytes from
 708  *                  the beginning of the file
 709  *                  - SEEK_CUR The offset is set to current location
 710  *                  plus offset bytes.
 711  *                  - SEEK_END The offset is set to the size of the
 712  *                  file plus offset bytes.
 713  *
 714  * @return          Upon successful completion, lseek returns the
 715  *                  resulting offset location as measured in bytes
 716  *                  from the beginning  of the file. Otherwise, a value
 717  *                  of (off_t)-1 is returned and errno is set to
 718  *                  indicate the error:
 719  *                  - EBADF  Fildes is not an open file descriptor.
 720  *                  - EINVAL Whence is not a proper value or smbc_init
 721  *                    not called.
 722  *
 723  * @todo Are all the whence values really supported?
 724  *
 725  * @todo Are errno values complete and correct?
 726  */
 727 off_t smbc_lseek(int fd, off_t offset, int whence);
 728
 729
 730 /**@ingroup file
 731  * Close an open file handle.
 732  *
 733  * @param fd        The file handle to close
 734  *
 735  * @return          0 on success, < 0 on error with errno set:
 736  *                  - EBADF  fd isn't a valid open file descriptor
 737  *                  - EINVAL smbc_init() failed or has not been called
 738  *
 739  * @see             smbc_open(), smbc_creat()
 740  */
 741 int smbc_close(int fd);
 742
 743
 744 /**@ingroup directory
 745  * Unlink (delete) a file or directory.
 746  *
 747  * @param furl      The smb url of the file to delete
 748  *
 749  * @return          0 on success, < 0 on error with errno set:
 750  *                  - EACCES or EPERM Write  access  to the directory
 751  *                  containing pathname is not allowed or one
 752  *                  of  the  directories in pathname did not allow
 753  *                  search (execute) permission
 754  *                  - ENOENT A directory component in pathname does
 755  *                  not exist
 756  *                  - EINVAL NULL was passed in the file param or
 757  *                    smbc_init not called.
 758  *                  - EACCES You do not have access to the file
 759  *                  - ENOMEM Insufficient kernel memory was available
 760  *
 761  * @see             smbc_rmdir()s
 762  *
 763  * @todo Are errno values complete and correct?
 764  */
 765 int smbc_unlink(const char *furl);
 766
 767
 768 /**@ingroup directory
 769  * Rename or move a file or directory.
 770  *
 771  * @param ourl      The original smb url (source url) of file or
 772  *                  directory to be moved
 773  *
 774  * @param nurl      The new smb url (destination url) of the file
 775  *                  or directory after the move.  Currently nurl must
 776  *                  be on the same share as ourl.
 777  *
 778  * @return          0 on success, < 0 on error with errno set:
 779  *                  - EISDIR nurl is an existing directory, but ourl is
 780  *                  not a directory.
 781  *                  - EEXIST nurl is  a  non-empty directory,
 782  *                  i.e., contains entries other than "." and ".."
 783  *                  - EINVAL The  new  url  contained  a path prefix
 784  *                  of the old, or, more generally, an  attempt was
 785  *                  made  to make a directory a subdirectory of itself
 786  *                  or smbc_init not called.
 787  *                  - ENOTDIR A component used as a directory in ourl
 788  *                  or nurl path is not, in fact, a directory.  Or,
 789  *                  ourl  is a directory, and newpath exists but is not
 790  *                  a directory.
 791  *                  - EACCES or EPERM Write access to the directory
 792  *                  containing ourl or nurl is not allowed for the
 793  *                  process's effective uid,  or  one of the
 794  *                  directories in ourl or nurl did not allow search
 795  *                  (execute) permission,  or ourl  was  a  directory
 796  *                  and did not allow write permission.
 797  *                  - ENOENT A  directory component in ourl or nurl
 798  *                  does not exist.
 799  *                  - EXDEV Rename across shares not supported.
 800  *                  - ENOMEM Insufficient kernel memory was available.
 801  *                  - EEXIST The target file, nurl, already exists.
 802  *
 803  *
 804  * @todo Are we going to support copying when urls are not on the same
 805  *       share?  I say no... NOTE. I agree for the moment.
 806  *
 807  */
 808 int smbc_rename(const char *ourl, const char *nurl);
 809
 810
 811 /**@ingroup directory
 812  * Open a directory used to obtain directory entries.
 813  *
 814  * @param durl      The smb url of the directory to open
 815  *
 816  * @return          Valid directory handle. < 0 on error with errno set:
 817  *                  - EACCES Permission denied.
 818  *                  - EINVAL A NULL file/URL was passed, or the URL would
 819  *                  not parse, or was of incorrect form or smbc_init not
 820  *                  called.
 821  *                  - ENOENT durl does not exist, or name is an
 822  *                  - ENOMEM Insufficient memory to complete the
 823  *                  operation.
 824  *                  - ENOTDIR name is not a directory.
 825  *                  - EPERM the workgroup could not be found.
 826  *                  - ENODEV the workgroup or server could not be found.
 827  *
 828  * @see             smbc_getdents(), smbc_readdir(), smbc_closedir()
 829  *
 830  */
 831 int smbc_opendir(const char *durl);
 832
 833
 834 /**@ingroup directory
 835  * Close a directory handle opened by smbc_opendir().
 836  *
 837  * @param dh        Directory handle to close
 838  *
 839  * @return          0 on success, < 0 on error with errno set:
 840  *                  - EBADF dh is an invalid directory handle
 841  *
 842  * @see             smbc_opendir()
 843  */
 844 int smbc_closedir(int dh);
 845
 846
 847 /**@ingroup directory
 848  * Get multiple directory entries.
 849  *
 850  * smbc_getdents() reads as many dirent structures from the an open
 851  * directory handle into a specified memory area as will fit.
 852  *
 853  * @param dh        Valid directory as returned by smbc_opendir()
 854  *
 855  * @param dirp      pointer to buffer that will receive the directory
 856  *                  entries.
 857  *
 858  * @param count     The size of the dirp buffer in bytes
 859  *
 860  * @returns         If any dirents returned, return will indicate the
 861  *                  total size. If there were no more dirents available,
 862  *                  0 is returned. < 0 indicates an error.
 863  *                  - EBADF  Invalid directory handle
 864  *                  - EINVAL Result buffer is too small or smbc_init
 865  *                  not called.
 866  *                  - ENOENT No such directory.
 867  * @see             , smbc_dirent, smbc_readdir(), smbc_open()
 868  *
 869  * @todo Are errno values complete and correct?
 870  *
 871  * @todo Add example code so people know how to parse buffers.
 872  */
 873 int smbc_getdents(unsigned int dh, struct smbc_dirent *dirp, int count);
 874
 875
 876 /**@ingroup directory
 877  * Get a single directory entry.
 878  *
 879  * @param dh        Valid directory as returned by smbc_opendir()
 880  *
 881  * @return          A pointer to a smbc_dirent structure, or NULL if an
 882  *                  error occurs or end-of-directory is reached:
 883  *                  - EBADF Invalid directory handle
 884  *                  - EINVAL smbc_init() failed or has not been called
 885  *
 886  * @see             smbc_dirent, smbc_getdents(), smbc_open()
 887  */
 888 struct smbc_dirent* smbc_readdir(unsigned int dh);
 889
 890
 891 /**@ingroup directory
 892  * Get the current directory offset.
 893  *
 894  * smbc_telldir() may be used in conjunction with smbc_readdir() and
 895  * smbc_lseekdir().
 896  *
 897  * @param dh        Valid directory as returned by smbc_opendir()
 898  *
 899  * @return          The current location in the directory stream or -1
 900  *                  if an error occur.  The current location is not
 901  *                  an offset. Becuase of the implementation, it is a
 902  *                  handle that allows the library to find the entry
 903  *                  later.
 904  *                  - EBADF dh is not a valid directory handle
 905  *                  - EINVAL smbc_init() failed or has not been called
 906  *                  - ENOTDIR if dh is not a directory
 907  *
 908  * @see             smbc_readdir()
 909  *
 910  */
 911 off_t smbc_telldir(int dh);
 912
 913
 914 /**@ingroup directory
 915  * lseek on directories.
 916  *
 917  * smbc_lseekdir() may be used in conjunction with smbc_readdir() and
 918  * smbc_telldir(). (rewind by smbc_lseekdir(fd, NULL))
 919  *
 920  * @param fd        Valid directory as returned by smbc_opendir()
 921  *
 922  * @param offset    The offset (as returned by smbc_telldir). Can be
 923  *                  NULL, in which case we will rewind
 924  *
 925  * @return          0 on success, -1 on failure
 926  *                  - EBADF dh is not a valid directory handle
 927  *                  - ENOTDIR if dh is not a directory
 928  *                  - EINVAL offset did not refer to a valid dirent or
 929  *                    smbc_init not called.
 930  *
 931  * @see             smbc_telldir()
 932  *
 933  *
 934  * @todo In what does the reture and errno values mean?
 935  */
 936 int smbc_lseekdir(int fd, off_t offset);
 937
 938 /**@ingroup directory
 939  * Create a directory.
 940  *
 941  * @param durl      The url of the directory to create
 942  *
 943  * @param mode      Specifies  the  permissions to use. It is modified
 944  *                  by the process's umask in the usual way: the
 945  *                  permissions of the created file are (mode & ~umask).
 946  *
 947  * @return          0 on success, < 0 on error with errno set:
 948  *                  - EEXIST directory url already exists
 949  *                  - EACCES The parent directory does not allow write
 950  *                  permission to the process, or one of the directories
 951  *                  - ENOENT A directory component in pathname does not
 952  *                  exist.
 953  *                  - EINVAL NULL durl passed or smbc_init not called.
 954  *                  - ENOMEM Insufficient memory was available.
 955  *
 956  * @see             smbc_rmdir()
 957  *
 958  */
 959 int smbc_mkdir(const char *durl, mode_t mode);
 960
 961
 962 /**@ingroup directory
 963  * Remove a directory.
 964  *
 965  * @param durl      The smb url of the directory to remove
 966  *
 967  * @return          0 on success, < 0 on error with errno set:
 968  *                  - EACCES or EPERM Write access to the directory
 969  *                  containing pathname was not allowed.
 970  *                  - EINVAL durl is NULL or smbc_init not called.
 971  *                  - ENOENT A directory component in pathname does not
 972  *                  exist.
 973  *                  - ENOTEMPTY directory contains entries.
 974  *                  - ENOMEM Insufficient kernel memory was available.
 975  *
 976  * @see             smbc_mkdir(), smbc_unlink()
 977  *
 978  * @todo Are errno values complete and correct?
 979  */
 980 int smbc_rmdir(const char *durl);
 981
 982
 983 /**@ingroup attribute
 984  * Get information about a file or directory.
 985  *
 986  * @param url       The smb url to get information for
 987  *
 988  * @param st        pointer to a buffer that will be filled with
 989  *                  standard Unix struct stat information.
 990  *
 991  * @return          0 on success, < 0 on error with errno set:
 992  *                  - ENOENT A component of the path file_name does not
 993  *                  exist.
 994  *                  - EINVAL a NULL url was passed or smbc_init not called.
 995  *                  - EACCES Permission denied.
 996  *                  - ENOMEM Out of memory
 997  *                  - ENOTDIR The target dir, url, is not a directory.
 998  *
 999  * @see             Unix stat()
1000  *
1001  */
1002 int smbc_stat(const char *url, struct stat *st);
1003
1004
1005 /**@ingroup attribute
1006  * Get file information via an file descriptor.
1007  *
1008  * @param fd        Open file handle from smbc_open() or smbc_creat()
1009  *
1010  * @param st        pointer to a buffer that will be filled with
1011  *                  standard Unix struct stat information.
1012  *
1013  * @return          EBADF  filedes is bad.
1014  *                  - EACCES Permission denied.
1015  *                  - EBADF fd is not a valid file descriptor
1016  *                  - EINVAL Problems occurred in the underlying routines
1017  *                    or smbc_init not called.
1018  *                  - ENOMEM Out of memory
1019  *
1020  * @see             smbc_stat(), Unix stat()
1021  *
1022  */
1023 int smbc_fstat(int fd, struct stat *st);
1024
1025
1026 /**@ingroup attribue
1027  * Change the ownership of a file or directory.
1028  *
1029  * @param url       The smb url of the file or directory to change
1030  *                  ownership of.
1031  *
1032  * @param owner     I have no idea?
1033  *
1034  * @param group     I have not idea?
1035  *
1036  * @return          0 on success, < 0 on error with errno set:
1037  *                  - EPERM  The effective UID does not match the owner
1038  *                  of the file, and is not zero; or the owner or group
1039  *                  were specified incorrectly.
1040  *                  - ENOENT The file does not exist.
1041  *                  - ENOMEM Insufficient was available.
1042  *                  - ENOENT file or directory does not exist
1043  *
1044  * @todo Are we actually going to be able to implement this function
1045  *
1046  * @todo How do we abstract owner and group uid and gid?
1047  *
1048  */
1049 int smbc_chown(const char *url, uid_t owner, gid_t group);
1050
1051
1052 /**@ingroup attribute
1053  * Change the permissions of a file.
1054  *
1055  * @param url       The smb url of the file or directory to change
1056  *                  permissions of
1057  *
1058  * @param mode      The permissions to set:
1059  *                  - Put good explaination of permissions here!
1060  *
1061  * @return          0 on success, < 0 on error with errno set:
1062  *                  - EPERM  The effective UID does not match the owner
1063  *                  of the file, and is not zero
1064  *                  - ENOENT The file does not exist.
1065  *                  - ENOMEM Insufficient was available.
1066  *                  - ENOENT file or directory does not exist
1067  *
1068  * @todo Actually implement this fuction?
1069  *
1070  * @todo Are errno values complete and correct?
1071  */
1072 int smbc_chmod(const char *url, mode_t mode);
1073
1074 /**@ingroup attribute
1075  * Change the last modification time on a file
1076  *
1077  * @param url       The smb url of the file or directory to change
1078  *                  the modification time of
1079  *
1080  * @param tbuf      A timeval structure which contains the desired
1081  *                  modification time.  NOTE: Only the tv_sec field is
1082  *                  used.  The tv_usec (microseconds) portion is ignored.
1083  *
1084  * @return          0 on success, < 0 on error with errno set:
1085  *                  - EINVAL The client library is not properly initialized
1086  *                  - EPERM  Permission was denied.
1087  *
1088  */
1089 int smbc_utimes(const char *url, struct timeval *tbuf);
1090
1091 #ifdef HAVE_UTIME_H
1092 /**@ingroup attribute
1093  * Change the last modification time on a file
1094  *
1095  * @param url       The smb url of the file or directory to change
1096  *                  the modification time of
1097  *
1098  * @param utbuf     A utimebuf structure which contains the desired
1099  *                  modification time.  NOTE: Although the structure contains
1100  *                  an access time as well, the access time value is ignored.
1101  *
1102  * @return          0 on success, < 0 on error with errno set:
1103  *                  - EINVAL The client library is not properly initialized
1104  *                  - ENOMEM No memory was available for internal needs
1105  *                  - EPERM  Permission was denied.
1106  *
1107  */
1108 int smbc_utime(const char *fname, struct utimbuf *utbuf);
1109 #endif
1110
1111 /**@ingroup attribute
1112  * Set extended attributes for a file.  This is used for modifying a file's
1113  * security descriptor (i.e. owner, group, and access control list)
1114  *
1115  * @param url       The smb url of the file or directory to set extended
1116  *                  attributes for.
1117  *
1118  * @param name      The name of an attribute to be changed.  Names are of
1119  *                  one of the following forms:
1120  *
1121  *                     system.nt_sec_desc.<attribute name>
1122  *                     system.nt_sec_desc.*
1123  *                     system.nt_sec_desc.*+
1124  *
1125  *                  where <attribute name> is one of:
1126  *
1127  *                     revision
1128  *                     owner
1129  *                     owner+
1130  *                     group
1131  *                     group+
1132  *                     acl:<name or sid>
1133  *                     acl+:<name or sid>
1134  *
1135  *                  In the forms "system.nt_sec_desc.*" and
1136  *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
1137  *                  literal, i.e. the string is provided exactly as shown, and
1138  *                  the value parameter should contain a complete security
1139  *                  descriptor with name:value pairs separated by tabs,
1140  *                  commas, or newlines (not spaces!).
1141  *
1142  *                  The plus sign ('+') indicates that SIDs should be mapped
1143  *                  to names.  Without the plus sign, SIDs are not mapped;
1144  *                  rather they are simply converted to a string format.
1145  *
1146  * @param value     The value to be assigned to the specified attribute name.
1147  *                  This buffer should contain only the attribute value if the
1148  *                  name was of the "system.nt_sec_desc.<attribute_name>"
1149  *                  form.  If the name was of the "system.nt_sec_desc.*" form
1150  *                  then a complete security descriptor, with name:value pairs
1151  *                  separated by tabs, commas, or newlines (not spaces!),
1152  *                  should be provided in this value buffer.  A complete
1153  *                  security descriptor will contain one or more entries
1154  *                  selected from the following:
1155  *
1156  *                    REVISION:<revision number>
1157  *                    OWNER:<sid or name>
1158  *                    GROUP:<sid or name>
1159  *                    ACL:<sid or name>:<type>/<flags>/<mask>
1160  *
1161  *                  The  revision of the ACL specifies the internal Windows NT
1162  *                  ACL revision for the security descriptor. If not specified
1163  *                  it defaults to  1.  Using values other than 1 may cause
1164  *                  strange behaviour.
1165  *
1166  *                  The owner and group specify the owner and group sids for
1167  *                  the object. If the attribute name (either '*+' with a
1168  *                  complete security descriptor, or individual 'owner+' or
1169  *                  'group+' attribute names) ended with a plus sign, the
1170  *                  specified name is resolved to a SID value, using the
1171  *                  server on which the file or directory resides.  Otherwise,
1172  *                  the value should be provided in SID-printable format as
1173  *                  S-1-x-y-z, and is used directly.  The <sid or name>
1174  *                  associated with the ACL: attribute should be provided
1175  *                  similarly.
1176  *
1177  * @param size      The number of the bytes of data in the value buffer
1178  *
1179  * @param flags     A bit-wise OR of zero or more of the following:
1180  *                    SMBC_XATTR_FLAG_CREATE -
1181  *                      fail if the named attribute already exists
1182  *                    SMBC_XATTR_FLAG_REPLACE -
1183  *                      fail if the attribute does not already exist
1184  *
1185  *                  If neither flag is specified, the specified attributes
1186  *                  will be added or replace existing attributes of the same
1187  *                  name, as necessary.
1188  *
1189  * @return          0 on success, < 0 on error with errno set:
1190  *                  - EINVAL  The client library is not properly initialized
1191  *                            or one of the parameters is not of a correct
1192  *                            form
1193  *                  - ENOMEM No memory was available for internal needs
1194  *                  - EEXIST  If the attribute already exists and the flag
1195  *                            SMBC_XATTR_FLAG_CREAT was specified
1196  *                  - ENOATTR If the attribute does not exist and the flag
1197  *                            SMBC_XATTR_FLAG_REPLACE was specified
1198  *                  - EPERM   Permission was denied.
1199  *                  - ENOTSUP The referenced file system does not support
1200  *                            extended attributes
1201  *
1202  * @note            Attribute names are compared in a case-insensitive
1203  *                  fashion.  All of the following are equivalent, although
1204  *                  the all-lower-case name is the preferred format:
1205  *                    system.nt_sec_desc.owner
1206  *                    SYSTEM.NT_SEC_DESC.OWNER
1207  *                    sYsTeM.nt_sEc_desc.owNER
1208  *
1209  */
1210 int smbc_setxattr(const char *url,
1211                   const char *name,
1212                   const void *value,
1213                   size_t size,
1214                   int flags);
1215
1216
1217 /**@ingroup attribute
1218  * Set extended attributes for a file.  This is used for modifying a file's
1219  * security descriptor (i.e. owner, group, and access control list).  The
1220  * POSIX function which this maps to would act on a symbolic link rather than
1221  * acting on what the symbolic link points to, but with no symbolic links in
1222  * SMB file systems, this function is functionally identical to
1223  * smbc_setxattr().
1224  *
1225  * @param url       The smb url of the file or directory to set extended
1226  *                  attributes for.
1227  *
1228  * @param name      The name of an attribute to be changed.  Names are of
1229  *                  one of the following forms:
1230  *
1231  *                     system.nt_sec_desc.<attribute name>
1232  *                     system.nt_sec_desc.*
1233  *                     system.nt_sec_desc.*+
1234  *
1235  *                  where <attribute name> is one of:
1236  *
1237  *                     revision
1238  *                     owner
1239  *                     owner+
1240  *                     group
1241  *                     group+
1242  *                     acl:<name or sid>
1243  *                     acl+:<name or sid>
1244  *
1245  *                  In the forms "system.nt_sec_desc.*" and
1246  *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
1247  *                  literal, i.e. the string is provided exactly as shown, and
1248  *                  the value parameter should contain a complete security
1249  *                  descriptor with name:value pairs separated by tabs,
1250  *                  commas, or newlines (not spaces!).
1251  *
1252  *                  The plus sign ('+') indicates that SIDs should be mapped
1253  *                  to names.  Without the plus sign, SIDs are not mapped;
1254  *                  rather they are simply converted to a string format.
1255  *
1256  * @param value     The value to be assigned to the specified attribute name.
1257  *                  This buffer should contain only the attribute value if the
1258  *                  name was of the "system.nt_sec_desc.<attribute_name>"
1259  *                  form.  If the name was of the "system.nt_sec_desc.*" form
1260  *                  then a complete security descriptor, with name:value pairs
1261  *                  separated by tabs, commas, or newlines (not spaces!),
1262  *                  should be provided in this value buffer.  A complete
1263  *                  security descriptor will contain one or more entries
1264  *                  selected from the following:
1265  *
1266  *                    REVISION:<revision number>
1267  *                    OWNER:<sid or name>
1268  *                    GROUP:<sid or name>
1269  *                    ACL:<sid or name>:<type>/<flags>/<mask>
1270  *
1271  *                  The  revision of the ACL specifies the internal Windows NT
1272  *                  ACL revision for the security descriptor. If not specified
1273  *                  it defaults to  1.  Using values other than 1 may cause
1274  *                  strange behaviour.
1275  *
1276  *                  The owner and group specify the owner and group sids for
1277  *                  the object. If the attribute name (either '*+' with a
1278  *                  complete security descriptor, or individual 'owner+' or
1279  *                  'group+' attribute names) ended with a plus sign, the
1280  *                  specified name is resolved to a SID value, using the
1281  *                  server on which the file or directory resides.  Otherwise,
1282  *                  the value should be provided in SID-printable format as
1283  *                  S-1-x-y-z, and is used directly.  The <sid or name>
1284  *                  associated with the ACL: attribute should be provided
1285  *                  similarly.
1286  *
1287  * @param size      The number of the bytes of data in the value buffer
1288  *
1289  * @param flags     A bit-wise OR of zero or more of the following:
1290  *                    SMBC_XATTR_FLAG_CREATE -
1291  *                      fail if the named attribute already exists
1292  *                    SMBC_XATTR_FLAG_REPLACE -
1293  *                      fail if the attribute does not already exist
1294  *
1295  *                  If neither flag is specified, the specified attributes
1296  *                  will be added or replace existing attributes of the same
1297  *                  name, as necessary.
1298  *
1299  * @return          0 on success, < 0 on error with errno set:
1300  *                  - EINVAL  The client library is not properly initialized
1301  *                            or one of the parameters is not of a correct
1302  *                            form
1303  *                  - ENOMEM No memory was available for internal needs
1304  *                  - EEXIST  If the attribute already exists and the flag
1305  *                            SMBC_XATTR_FLAG_CREAT was specified
1306  *                  - ENOATTR If the attribute does not exist and the flag
1307  *                            SMBC_XATTR_FLAG_REPLACE was specified
1308  *                  - EPERM   Permission was denied.
1309  *                  - ENOTSUP The referenced file system does not support
1310  *                            extended attributes
1311  *
1312  * @note            Attribute names are compared in a case-insensitive
1313  *                  fashion.  All of the following are equivalent, although
1314  *                  the all-lower-case name is the preferred format:
1315  *                    system.nt_sec_desc.owner
1316  *                    SYSTEM.NT_SEC_DESC.OWNER
1317  *                    sYsTeM.nt_sEc_desc.owNER
1318  *
1319  */
1320 int smbc_lsetxattr(const char *url,
1321                    const char *name,
1322                    const void *value,
1323                    size_t size,
1324                    int flags);
1325
1326
1327 /**@ingroup attribute
1328  * Set extended attributes for a file.  This is used for modifying a file's
1329  * security descriptor (i.e. owner, group, and access control list)
1330  *
1331  * @param fd        A file descriptor associated with an open file (as
1332  *                  previously returned by smbc_open(), to get extended
1333  *                  attributes for.
1334  *
1335  * @param name      The name of an attribute to be changed.  Names are of
1336  *                  one of the following forms:
1337  *
1338  *                     system.nt_sec_desc.<attribute name>
1339  *                     system.nt_sec_desc.*
1340  *                     system.nt_sec_desc.*+
1341  *
1342  *                  where <attribute name> is one of:
1343  *
1344  *                     revision
1345  *                     owner
1346  *                     owner+
1347  *                     group
1348  *                     group+
1349  *                     acl:<name or sid>
1350  *                     acl+:<name or sid>
1351  *
1352  *                  In the forms "system.nt_sec_desc.*" and
1353  *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
1354  *                  literal, i.e. the string is provided exactly as shown, and
1355  *                  the value parameter should contain a complete security
1356  *                  descriptor with name:value pairs separated by tabs,
1357  *                  commas, or newlines (not spaces!).
1358  *
1359  *                  The plus sign ('+') indicates that SIDs should be mapped
1360  *                  to names.  Without the plus sign, SIDs are not mapped;
1361  *                  rather they are simply converted to a string format.
1362  *
1363  * @param value     The value to be assigned to the specified attribute name.
1364  *                  This buffer should contain only the attribute value if the
1365  *                  name was of the "system.nt_sec_desc.<attribute_name>"
1366  *                  form.  If the name was of the "system.nt_sec_desc.*" form
1367  *                  then a complete security descriptor, with name:value pairs
1368  *                  separated by tabs, commas, or newlines (not spaces!),
1369  *                  should be provided in this value buffer.  A complete
1370  *                  security descriptor will contain one or more entries
1371  *                  selected from the following:
1372  *
1373  *                    REVISION:<revision number>
1374  *                    OWNER:<sid or name>
1375  *                    GROUP:<sid or name>
1376  *                    ACL:<sid or name>:<type>/<flags>/<mask>
1377  *
1378  *                  The  revision of the ACL specifies the internal Windows NT
1379  *                  ACL revision for the security descriptor. If not specified
1380  *                  it defaults to  1.  Using values other than 1 may cause
1381  *                  strange behaviour.
1382  *
1383  *                  The owner and group specify the owner and group sids for
1384  *                  the object. If the attribute name (either '*+' with a
1385  *                  complete security descriptor, or individual 'owner+' or
1386  *                  'group+' attribute names) ended with a plus sign, the
1387  *                  specified name is resolved to a SID value, using the
1388  *                  server on which the file or directory resides.  Otherwise,
1389  *                  the value should be provided in SID-printable format as
1390  *                  S-1-x-y-z, and is used directly.  The <sid or name>
1391  *                  associated with the ACL: attribute should be provided
1392  *                  similarly.
1393  *
1394  * @param size      The number of the bytes of data in the value buffer
1395  *
1396  * @param flags     A bit-wise OR of zero or more of the following:
1397  *                    SMBC_XATTR_FLAG_CREATE -
1398  *                      fail if the named attribute already exists
1399  *                    SMBC_XATTR_FLAG_REPLACE -
1400  *                      fail if the attribute does not already exist
1401  *
1402  *                  If neither flag is specified, the specified attributes
1403  *                  will be added or replace existing attributes of the same
1404  *                  name, as necessary.
1405  *
1406  * @return          0 on success, < 0 on error with errno set:
1407  *                  - EINVAL  The client library is not properly initialized
1408  *                            or one of the parameters is not of a correct
1409  *                            form
1410  *                  - ENOMEM No memory was available for internal needs
1411  *                  - EEXIST  If the attribute already exists and the flag
1412  *                            SMBC_XATTR_FLAG_CREAT was specified
1413  *                  - ENOATTR If the attribute does not exist and the flag
1414  *                            SMBC_XATTR_FLAG_REPLACE was specified
1415  *                  - EPERM   Permission was denied.
1416  *                  - ENOTSUP The referenced file system does not support
1417  *                            extended attributes
1418  *
1419  * @note            Attribute names are compared in a case-insensitive
1420  *                  fashion.  All of the following are equivalent, although
1421  *                  the all-lower-case name is the preferred format:
1422  *                    system.nt_sec_desc.owner
1423  *                    SYSTEM.NT_SEC_DESC.OWNER
1424  *                    sYsTeM.nt_sEc_desc.owNER
1425  *
1426  */
1427 int smbc_fsetxattr(int fd,
1428                    const char *name,
1429                    const void *value,
1430                    size_t size,
1431                    int flags);
1432
1433
1434 /**@ingroup attribute
1435  * Get extended attributes for a file.
1436  *
1437  * @param url       The smb url of the file or directory to get extended
1438  *                  attributes for.
1439  *
1440  * @param name      The name of an attribute to be retrieved.  Names are of
1441  *                  one of the following forms:
1442  *
1443  *                     system.nt_sec_desc.<attribute name>
1444  *                     system.nt_sec_desc.*
1445  *                     system.nt_sec_desc.*+
1446  *
1447  *                  where <attribute name> is one of:
1448  *
1449  *                     revision
1450  *                     owner
1451  *                     owner+
1452  *                     group
1453  *                     group+
1454  *                     acl:<name or sid>
1455  *                     acl+:<name or sid>
1456  *
1457  *                  In the forms "system.nt_sec_desc.*" and
1458  *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
1459  *                  literal, i.e. the string is provided exactly as shown, and
1460  *                  the value parameter will return a complete security
1461  *                  descriptor with name:value pairs separated by tabs,
1462  *                  commas, or newlines (not spaces!).
1463  *
1464  *                  The plus sign ('+') indicates that SIDs should be mapped
1465  *                  to names.  Without the plus sign, SIDs are not mapped;
1466  *                  rather they are simply converted to a string format.
1467  *
1468  * @param value     A pointer to a buffer in which the value of the specified
1469  *                  attribute will be placed (unless size is zero).
1470  *
1471  * @param size      The size of the buffer pointed to by value.  This parameter
1472  *                  may also be zero, in which case the size of the buffer
1473  *                  required to hold the attribute value will be returned,
1474  *                  but nothing will be placed into the value buffer.
1475  *
1476  * @return          0 on success, < 0 on error with errno set:
1477  *                  - EINVAL  The client library is not properly initialized
1478  *                            or one of the parameters is not of a correct
1479  *                            form
1480  *                  - ENOMEM No memory was available for internal needs
1481  *                  - EEXIST  If the attribute already exists and the flag
1482  *                            SMBC_XATTR_FLAG_CREAT was specified
1483  *                  - ENOATTR If the attribute does not exist and the flag
1484  *                            SMBC_XATTR_FLAG_REPLACE was specified
1485  *                  - EPERM   Permission was denied.
1486  *                  - ENOTSUP The referenced file system does not support
1487  *                            extended attributes
1488  *
1489  */
1490 int smbc_getxattr(const char *url,
1491                   const char *name,
1492                   const void *value,
1493                   size_t size);
1494
1495
1496 /**@ingroup attribute
1497  * Get extended attributes for a file.  The POSIX function which this maps to
1498  * would act on a symbolic link rather than acting on what the symbolic link
1499  * points to, but with no symbolic links in SMB file systems, this function
1500  * is functionally identical to smbc_getxattr().
1501  *
1502  * @param url       The smb url of the file or directory to get extended
1503  *                  attributes for.
1504  *
1505  * @param name      The name of an attribute to be retrieved.  Names are of
1506  *                  one of the following forms:
1507  *
1508  *                     system.nt_sec_desc.<attribute name>
1509  *                     system.nt_sec_desc.*
1510  *                     system.nt_sec_desc.*+
1511  *
1512  *                  where <attribute name> is one of:
1513  *
1514  *                     revision
1515  *                     owner
1516  *                     owner+
1517  *                     group
1518  *                     group+
1519  *                     acl:<name or sid>
1520  *                     acl+:<name or sid>
1521  *
1522  *                  In the forms "system.nt_sec_desc.*" and
1523  *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
1524  *                  literal, i.e. the string is provided exactly as shown, and
1525  *                  the value parameter will return a complete security
1526  *                  descriptor with name:value pairs separated by tabs,
1527  *                  commas, or newlines (not spaces!).
1528  *
1529  *                  The plus sign ('+') indicates that SIDs should be mapped
1530  *                  to names.  Without the plus sign, SIDs are not mapped;
1531  *                  rather they are simply converted to a string format.
1532  *
1533  * @param value     A pointer to a buffer in which the value of the specified
1534  *                  attribute will be placed (unless size is zero).
1535  *
1536  * @param size      The size of the buffer pointed to by value.  This parameter
1537  *                  may also be zero, in which case the size of the buffer
1538  *                  required to hold the attribute value will be returned,
1539  *                  but nothing will be placed into the value buffer.
1540  *
1541  * @return          0 on success, < 0 on error with errno set:
1542  *                  - EINVAL  The client library is not properly initialized
1543  *                            or one of the parameters is not of a correct
1544  *                            form
1545  *                  - ENOMEM No memory was available for internal needs
1546  *                  - EEXIST  If the attribute already exists and the flag
1547  *                            SMBC_XATTR_FLAG_CREAT was specified
1548  *                  - ENOATTR If the attribute does not exist and the flag
1549  *                            SMBC_XATTR_FLAG_REPLACE was specified
1550  *                  - EPERM   Permission was denied.
1551  *                  - ENOTSUP The referenced file system does not support
1552  *                            extended attributes
1553  *
1554  */
1555 int smbc_lgetxattr(const char *url,
1556                    const char *name,
1557                    const void *value,
1558                    size_t size);
1559
1560
1561 /**@ingroup attribute
1562  * Get extended attributes for a file.
1563  *
1564  * @param fd        A file descriptor associated with an open file (as
1565  *                  previously returned by smbc_open(), to get extended
1566  *                  attributes for.
1567  *
1568  * @param name      The name of an attribute to be retrieved.  Names are of
1569  *                  one of the following forms:
1570  *
1571  *                     system.nt_sec_desc.<attribute name>
1572  *                     system.nt_sec_desc.*
1573  *                     system.nt_sec_desc.*+
1574  *
1575  *                  where <attribute name> is one of:
1576  *
1577  *                     revision
1578  *                     owner
1579  *                     owner+
1580  *                     group
1581  *                     group+
1582  *                     acl:<name or sid>
1583  *                     acl+:<name or sid>
1584  *
1585  *                  In the forms "system.nt_sec_desc.*" and
1586  *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
1587  *                  literal, i.e. the string is provided exactly as shown, and
1588  *                  the value parameter will return a complete security
1589  *                  descriptor with name:value pairs separated by tabs,
1590  *                  commas, or newlines (not spaces!).
1591  *
1592  *                  The plus sign ('+') indicates that SIDs should be mapped
1593  *                  to names.  Without the plus sign, SIDs are not mapped;
1594  *                  rather they are simply converted to a string format.
1595  *
1596  * @param value     A pointer to a buffer in which the value of the specified
1597  *                  attribute will be placed (unless size is zero).
1598  *
1599  * @param size      The size of the buffer pointed to by value.  This parameter
1600  *                  may also be zero, in which case the size of the buffer
1601  *                  required to hold the attribute value will be returned,
1602  *                  but nothing will be placed into the value buffer.
1603  *
1604  * @return          0 on success, < 0 on error with errno set:
1605  *                  - EINVAL  The client library is not properly initialized
1606  *                            or one of the parameters is not of a correct
1607  *                            form
1608  *                  - ENOMEM No memory was available for internal needs
1609  *                  - EEXIST  If the attribute already exists and the flag
1610  *                            SMBC_XATTR_FLAG_CREAT was specified
1611  *                  - ENOATTR If the attribute does not exist and the flag
1612  *                            SMBC_XATTR_FLAG_REPLACE was specified
1613  *                  - EPERM   Permission was denied.
1614  *                  - ENOTSUP The referenced file system does not support
1615  *                            extended attributes
1616  *
1617  */
1618 int smbc_fgetxattr(int fd,
1619                    const char *name,
1620                    const void *value,
1621                    size_t size);
1622
1623
1624 /**@ingroup attribute
1625  * Remove extended attributes for a file.  This is used for modifying a file's
1626  * security descriptor (i.e. owner, group, and access control list)
1627  *
1628  * @param url       The smb url of the file or directory to remove the extended
1629  *                  attributes for.
1630  *
1631  * @param name      The name of an attribute to be removed.  Names are of
1632  *                  one of the following forms:
1633  *
1634  *                     system.nt_sec_desc.<attribute name>
1635  *                     system.nt_sec_desc.*
1636  *                     system.nt_sec_desc.*+
1637  *
1638  *                  where <attribute name> is one of:
1639  *
1640  *                     revision
1641  *                     owner
1642  *                     owner+
1643  *                     group
1644  *                     group+
1645  *                     acl:<name or sid>
1646  *                     acl+:<name or sid>
1647  *
1648  *                  In the forms "system.nt_sec_desc.*" and
1649  *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
1650  *                  literal, i.e. the string is provided exactly as shown, and
1651  *                  the value parameter will return a complete security
1652  *                  descriptor with name:value pairs separated by tabs,
1653  *                  commas, or newlines (not spaces!).
1654  *
1655  *                  The plus sign ('+') indicates that SIDs should be mapped
1656  *                  to names.  Without the plus sign, SIDs are not mapped;
1657  *                  rather they are simply converted to a string format.
1658  *
1659  * @return          0 on success, < 0 on error with errno set:
1660  *                  - EINVAL The client library is not properly initialized
1661  *                  - ENOMEM No memory was available for internal needs
1662  *                  - EPERM  Permission was denied.
1663  *                  - ENOTSUP The referenced file system does not support
1664  *                            extended attributes
1665  *
1666  */
1667 int smbc_removexattr(const char *url,
1668                      const char *name);
1669
1670
1671 /**@ingroup attribute
1672  * Remove extended attributes for a file.  This is used for modifying a file's
1673  * security descriptor (i.e. owner, group, and access control list) The POSIX
1674  * function which this maps to would act on a symbolic link rather than acting
1675  * on what the symbolic link points to, but with no symbolic links in SMB file
1676  * systems, this function is functionally identical to smbc_removexattr().
1677  *
1678  * @param url       The smb url of the file or directory to remove the extended
1679  *                  attributes for.
1680  *
1681  * @param name      The name of an attribute to be removed.  Names are of
1682  *                  one of the following forms:
1683  *
1684  *                     system.nt_sec_desc.<attribute name>
1685  *                     system.nt_sec_desc.*
1686  *                     system.nt_sec_desc.*+
1687  *
1688  *                  where <attribute name> is one of:
1689  *
1690  *                     revision
1691  *                     owner
1692  *                     owner+
1693  *                     group
1694  *                     group+
1695  *                     acl:<name or sid>
1696  *                     acl+:<name or sid>
1697  *
1698  *                  In the forms "system.nt_sec_desc.*" and
1699  *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
1700  *                  literal, i.e. the string is provided exactly as shown, and
1701  *                  the value parameter will return a complete security
1702  *                  descriptor with name:value pairs separated by tabs,
1703  *                  commas, or newlines (not spaces!).
1704  *
1705  *                  The plus sign ('+') indicates that SIDs should be mapped
1706  *                  to names.  Without the plus sign, SIDs are not mapped;
1707  *                  rather they are simply converted to a string format.
1708  *
1709  * @return          0 on success, < 0 on error with errno set:
1710  *                  - EINVAL The client library is not properly initialized
1711  *                  - ENOMEM No memory was available for internal needs
1712  *                  - EPERM  Permission was denied.
1713  *                  - ENOTSUP The referenced file system does not support
1714  *                            extended attributes
1715  *
1716  */
1717 int smbc_lremovexattr(const char *url,
1718                       const char *name);
1719
1720
1721 /**@ingroup attribute
1722  * Remove extended attributes for a file.  This is used for modifying a file's
1723  * security descriptor (i.e. owner, group, and access control list)
1724  *
1725  * @param fd        A file descriptor associated with an open file (as
1726  *                  previously returned by smbc_open(), to get extended
1727  *                  attributes for.
1728  *
1729  * @param name      The name of an attribute to be removed.  Names are of
1730  *                  one of the following forms:
1731  *
1732  *                     system.nt_sec_desc.<attribute name>
1733  *                     system.nt_sec_desc.*
1734  *                     system.nt_sec_desc.*+
1735  *
1736  *                  where <attribute name> is one of:
1737  *
1738  *                     revision
1739  *                     owner
1740  *                     owner+
1741  *                     group
1742  *                     group+
1743  *                     acl:<name or sid>
1744  *                     acl+:<name or sid>
1745  *
1746  *                  In the forms "system.nt_sec_desc.*" and
1747  *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
1748  *                  literal, i.e. the string is provided exactly as shown, and
1749  *                  the value parameter will return a complete security
1750  *                  descriptor with name:value pairs separated by tabs,
1751  *                  commas, or newlines (not spaces!).
1752  *
1753  *                  The plus sign ('+') indicates that SIDs should be mapped
1754  *                  to names.  Without the plus sign, SIDs are not mapped;
1755  *                  rather they are simply converted to a string format.
1756  *
1757  * @return          0 on success, < 0 on error with errno set:
1758  *                  - EINVAL The client library is not properly initialized
1759  *                  - ENOMEM No memory was available for internal needs
1760  *                  - EPERM  Permission was denied.
1761  *                  - ENOTSUP The referenced file system does not support
1762  *                            extended attributes
1763  *
1764  */
1765 int smbc_fremovexattr(int fd,
1766                       const char *name);
1767
1768
1769 /**@ingroup attribute
1770  * List the supported extended attribute names associated with a file
1771  *
1772  * @param url       The smb url of the file or directory to list the extended
1773  *                  attributes for.
1774  *
1775  * @param list      A pointer to a buffer in which the list of attributes for
1776  *                  the specified file or directory will be placed (unless
1777  *                  size is zero).
1778  *
1779  * @param size      The size of the buffer pointed to by list.  This parameter
1780  *                  may also be zero, in which case the size of the buffer
1781  *                  required to hold all of the attribute names will be
1782  *                  returned, but nothing will be placed into the list buffer.
1783  *
1784  * @return          0 on success, < 0 on error with errno set:
1785  *                  - EINVAL The client library is not properly initialized
1786  *                  - ENOMEM No memory was available for internal needs
1787  *                  - EPERM  Permission was denied.
1788  *                  - ENOTSUP The referenced file system does not support
1789  *                            extended attributes
1790  *
1791  * @note            This function always returns all attribute names supported
1792  *                  by NT file systems, regardless of wether the referenced
1793  *                  file system supports extended attributes (e.g. a Windows
1794  *                  2000 machine supports extended attributes if NTFS is used,
1795  *                  but not if FAT is used, and Windows 98 doesn't support
1796  *                  extended attributes at all.  Whether this is a feature or
1797  *                  a bug is yet to be decided.
1798  */
1799 int smbc_listxattr(const char *url,
1800                    char *list,
1801                    size_t size);
1802
1803 /**@ingroup attribute
1804  * List the supported extended attribute names associated with a file The
1805  * POSIX function which this maps to would act on a symbolic link rather than
1806  * acting on what the symbolic link points to, but with no symbolic links in
1807  * SMB file systems, this function is functionally identical to
1808  * smbc_listxattr().
1809  *
1810  * @param url       The smb url of the file or directory to list the extended
1811  *                  attributes for.
1812  *
1813  * @param list      A pointer to a buffer in which the list of attributes for
1814  *                  the specified file or directory will be placed (unless
1815  *                  size is zero).
1816  *
1817  * @param size      The size of the buffer pointed to by list.  This parameter
1818  *                  may also be zero, in which case the size of the buffer
1819  *                  required to hold all of the attribute names will be
1820  *                  returned, but nothing will be placed into the list buffer.
1821  *
1822  * @return          0 on success, < 0 on error with errno set:
1823  *                  - EINVAL The client library is not properly initialized
1824  *                  - ENOMEM No memory was available for internal needs
1825  *                  - EPERM  Permission was denied.
1826  *                  - ENOTSUP The referenced file system does not support
1827  *                            extended attributes
1828  *
1829  * @note            This function always returns all attribute names supported
1830  *                  by NT file systems, regardless of wether the referenced
1831  *                  file system supports extended attributes (e.g. a Windows
1832  *                  2000 machine supports extended attributes if NTFS is used,
1833  *                  but not if FAT is used, and Windows 98 doesn't support
1834  *                  extended attributes at all.  Whether this is a feature or
1835  *                  a bug is yet to be decided.
1836  */
1837 int smbc_llistxattr(const char *url,
1838                     char *list,
1839                     size_t size);
1840
1841 /**@ingroup attribute
1842  * List the supported extended attribute names associated with a file
1843  *
1844  * @param fd        A file descriptor associated with an open file (as
1845  *                  previously returned by smbc_open(), to get extended
1846  *                  attributes for.
1847  *
1848  * @param list      A pointer to a buffer in which the list of attributes for
1849  *                  the specified file or directory will be placed (unless
1850  *                  size is zero).
1851  *
1852  * @param size      The size of the buffer pointed to by list.  This parameter
1853  *                  may also be zero, in which case the size of the buffer
1854  *                  required to hold all of the attribute names will be
1855  *                  returned, but nothing will be placed into the list buffer.
1856  *
1857  * @return          0 on success, < 0 on error with errno set:
1858  *                  - EINVAL The client library is not properly initialized
1859  *                  - ENOMEM No memory was available for internal needs
1860  *                  - EPERM  Permission was denied.
1861  *                  - ENOTSUP The referenced file system does not support
1862  *                            extended attributes
1863  *
1864  * @note            This function always returns all attribute names supported
1865  *                  by NT file systems, regardless of wether the referenced
1866  *                  file system supports extended attributes (e.g. a Windows
1867  *                  2000 machine supports extended attributes if NTFS is used,
1868  *                  but not if FAT is used, and Windows 98 doesn't support
1869  *                  extended attributes at all.  Whether this is a feature or
1870  *                  a bug is yet to be decided.
1871  */
1872 int smbc_flistxattr(int fd,
1873                     char *list,
1874                     size_t size);
1875
1876 /**@ingroup print
1877  * Print a file given the name in fname. It would be a URL ...
1878  *
1879  * @param fname     The URL of a file on a remote SMB server that the
1880  *                  caller wants printed
1881  *
1882  * @param printq    The URL of the print share to print the file to.
1883  *
1884  * @return          0 on success, < 0 on error with errno set:
1885  *
1886  *                  - EINVAL fname or printq was NULL or smbc_init not
1887  *                    not called.
1888  *                  and errors returned by smbc_open
1889  *
1890  */
1891 int smbc_print_file(const char *fname, const char *printq);
1892
1893 /**@ingroup print
1894  * Open a print file that can be written to by other calls. This simply
1895  * does an smbc_open call after checking if there is a file name on the
1896  * URI. If not, a temporary name is added ...
1897  *
1898  * @param fname     The URL of the print share to print to?
1899  *
1900  * @returns         A file handle for the print file if successful.
1901  *                  Returns -1 if an error ocurred and errno has the values
1902  *                  - EINVAL fname was NULL or smbc_init not called.
1903  *                  - all errors returned by smbc_open
1904  *
1905  */
1906 int smbc_open_print_job(const char *fname);
1907
1908 /**@ingroup print
1909  * List the print jobs on a print share, for the moment, pass a callback
1910  *
1911  * @param purl      The url of the print share to list the jobs of
1912  *
1913  * @param fn        Callback function the receives printjob info
1914  *
1915  * @return          0 on success, < 0 on error with errno set:
1916  *                  - EINVAL fname was NULL or smbc_init not called
1917  *                  - EACCES ???
1918  */
1919 int smbc_list_print_jobs(const char *purl, smbc_list_print_job_fn fn);
1920
1921 /**@ingroup print
1922  * Delete a print job
1923  *
1924  * @param purl      Url of the print share
1925  *
1926  * @param id        The id of the job to delete
1927  *
1928  * @return          0 on success, < 0 on error with errno set:
1929  *                  - EINVAL fname was NULL or smbc_init not called
1930  *
1931  * @todo    what errno values are possible here?
1932  */
1933 int smbc_unlink_print_job(const char *purl, int id);
1934
1935 /**@ingroup callback
1936  * Remove a server from the cached server list it's unused.
1937  *
1938  * @param context    pointer to smb context
1939  *
1940  * @param srv        pointer to server to remove
1941  *
1942  * @return On success, 0 is returned. 1 is returned if the server could not
1943  *         be removed. Also useable outside libsmbclient.
1944  */
1945 int smbc_remove_unused_server(SMBCCTX * context, SMBCSRV * srv);
1946
1947 #endif /* SMBCLIENT_H_INCLUDED */