source3/include/libsmbclient.h

   1 /*=====================================================================
   2   Unix SMB/Netbios implementation.
   3   SMB client library API definitions
   4   Copyright (C) Andrew Tridgell 1998
   5   Copyright (C) Richard Sharpe 2000
   6   Copyright (C) John Terpsra 2000
   7   Copyright (C) Tom Jansen (Ninja ISD) 2002
   8   Copyright (C) Derrell Lipman 2003
   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_fn)     (SMBCCTX * c);
 390
 391
 392 /**@ingroup structure
 393  * Structure that contains a client context information
 394  * This structure is know as SMBCCTX
 395  */
 396 struct _SMBCCTX {
 397         /** debug level
 398          */
 399         int     debug;
 400
 401         /** netbios name used for making connections
 402          */
 403         char * netbios_name;
 404
 405         /** workgroup name used for making connections
 406          */
 407         char * workgroup;
 408
 409         /** username used for making connections
 410          */
 411         char * user;
 412
 413         /** timeout used for waiting on connections / response data (in milliseconds)
 414          */
 415         int timeout;
 416
 417         /** callable functions for files:
 418          * For usage and return values see the smbc_* functions
 419          */
 420         SMBCFILE * (*open)    (SMBCCTX *c, const char *fname, int flags, mode_t mode);
 421         SMBCFILE * (*creat)   (SMBCCTX *c, const char *path, mode_t mode);
 422         ssize_t    (*read)    (SMBCCTX *c, SMBCFILE *file, void *buf, size_t count);
 423         ssize_t    (*write)   (SMBCCTX *c, SMBCFILE *file, void *buf, size_t count);
 424         int        (*unlink)  (SMBCCTX *c, const char *fname);
 425         int        (*rename)  (SMBCCTX *ocontext, const char *oname,
 426                                SMBCCTX *ncontext, const char *nname);
 427         off_t      (*lseek)   (SMBCCTX *c, SMBCFILE * file, off_t offset, int whence);
 428         int        (*stat)    (SMBCCTX *c, const char *fname, struct stat *st);
 429         int        (*fstat)   (SMBCCTX *c, SMBCFILE *file, struct stat *st);
 430         /* ftruncate added near _internal for ABI compatibility */
 431
 432         int        (*close_fn) (SMBCCTX *c, SMBCFILE *file);
 433
 434         /** callable functions for dirs
 435          */
 436         SMBCFILE * (*opendir) (SMBCCTX *c, const char *fname);
 437         int        (*closedir)(SMBCCTX *c, SMBCFILE *dir);
 438         struct smbc_dirent * (*readdir)(SMBCCTX *c, SMBCFILE *dir);
 439         int        (*getdents)(SMBCCTX *c, SMBCFILE *dir,
 440                                struct smbc_dirent *dirp, int count);
 441         int        (*mkdir)   (SMBCCTX *c, const char *fname, mode_t mode);
 442         int        (*rmdir)   (SMBCCTX *c, const char *fname);
 443         off_t      (*telldir) (SMBCCTX *c, SMBCFILE *dir);
 444         int        (*lseekdir)(SMBCCTX *c, SMBCFILE *dir, off_t offset);
 445         int        (*fstatdir)(SMBCCTX *c, SMBCFILE *dir, struct stat *st);
 446         int        (*chmod)(SMBCCTX *c, const char *fname, mode_t mode);
 447         int        (*utimes)(SMBCCTX *c,
 448                              const char *fname, struct timeval *tbuf);
 449         int        (*setxattr)(SMBCCTX *context,
 450                                const char *fname,
 451                                const char *name,
 452                                const void *value,
 453                                size_t size,
 454                                int flags);
 455         int        (*getxattr)(SMBCCTX *context,
 456                                const char *fname,
 457                                const char *name,
 458                                const void *value,
 459                                size_t size);
 460         int        (*removexattr)(SMBCCTX *context,
 461                                   const char *fname,
 462                                   const char *name);
 463         int        (*listxattr)(SMBCCTX *context,
 464                                 const char *fname,
 465                                 char *list,
 466                                 size_t size);
 467
 468         /** callable functions for printing
 469          */
 470         int        (*print_file)(SMBCCTX *c_file, const char *fname,
 471                                  SMBCCTX *c_print, const char *printq);
 472         SMBCFILE * (*open_print_job)(SMBCCTX *c, const char *fname);
 473         int        (*list_print_jobs)(SMBCCTX *c, const char *fname, smbc_list_print_job_fn fn);
 474         int        (*unlink_print_job)(SMBCCTX *c, const char *fname, int id);
 475
 476
 477         /*
 478         ** Callbacks
 479         * These callbacks _always_ have to be initialized because they will
 480         * not be checked at dereference for increased speed.
 481         */
 482         struct _smbc_callbacks {
 483                 /** authentication function callback: called upon auth requests
 484                  */
 485                 smbc_get_auth_data_fn auth_fn;
 486
 487                 /** check if a server is still good
 488                  */
 489                 smbc_check_server_fn check_server_fn;
 490
 491                 /** remove a server if unused
 492                  */
 493                 smbc_remove_unused_server_fn remove_unused_server_fn;
 494
 495                 /** Cache subsystem
 496                  * For an example cache system see samba/source/libsmb/libsmb_cache.c
 497                  * Cache subsystem functions follow.
 498                  */
 499
 500                 /** server cache addition
 501                  */
 502                 smbc_add_cached_srv_fn add_cached_srv_fn;
 503
 504                 /** server cache lookup
 505                  */
 506                 smbc_get_cached_srv_fn get_cached_srv_fn;
 507
 508                 /** server cache removal
 509                  */
 510                 smbc_remove_cached_srv_fn remove_cached_srv_fn;
 511
 512                 /** server cache purging, try to remove all cached servers (disconnect)
 513                  */
 514                 smbc_purge_cached_fn purge_cached_fn;
 515         } callbacks;
 516
 517
 518         /** Space to store private data of the server cache.
 519          */
 520         struct smbc_server_cache * server_cache;
 521
 522         int flags;
 523
 524         /** user options selections that apply to this session
 525          *
 526          *  NEW OPTIONS ARE NOT ADDED HERE!
 527          *
 528          *  We must maintain ABI backward compatibility.  We now use
 529          *  smbc_option_set() and smbc_option_get() for all newly added
 530          *  options.
 531          */
 532         struct _smbc_options {
 533
 534                 /*
 535                  * From how many local master browsers should the list of
 536                  * workgroups be retrieved?  It can take up to 12 minutes or
 537                  * longer after a server becomes a local master browser, for
 538                  * it to have the entire browse list (the list of
 539                  * workgroups/domains) from an entire network.  Since a client
 540                  * never knows which local master browser will be found first,
 541                  * the one which is found first and used to retrieve a browse
 542                  * list may have an incomplete or empty browse list.  By
 543                  * requesting the browse list from multiple local master
 544                  * browsers, a more complete list can be generated.  For small
 545                  * networks (few workgroups), it is recommended that this
 546                  * value be set to 0, causing the browse lists from all found
 547                  * local master browsers to be retrieved and merged.  For
 548                  * networks with many workgroups, a suitable value for this
 549                  * variable is probably somewhere around 3. (Default: 3).
 550                  */
 551                 int browse_max_lmb_count;
 552
 553                 /*
 554                  * There is a difference in the desired return strings from
 555                  * smbc_readdir() depending upon whether the filenames are to
 556                  * be displayed to the user, or whether they are to be
 557                  * appended to the path name passed to smbc_opendir() to call
 558                  * a further smbc_ function (e.g. open the file with
 559                  * smbc_open()).  In the former case, the filename should be
 560                  * in "human readable" form.  In the latter case, the smbc_
 561                  * functions expect a URL which must be url-encoded.  Those
 562                  * functions decode the URL.  If, for example, smbc_readdir()
 563                  * returned a file name of "abc%20def.txt", passing a path
 564                  * with this file name attached to smbc_open() would cause
 565                  * smbc_open to attempt to open the file "abc def.txt" since
 566                  * the %20 is decoded into a space.
 567                  *
 568                  * Set this option to True if the names returned by
 569                  * smbc_readdir() should be url-encoded such that they can be
 570                  * passed back to another smbc_ call.  Set it to False if the
 571                  * names returned by smbc_readdir() are to be presented to the
 572                  * user.
 573                  *
 574                  * For backwards compatibility, this option defaults to False.
 575                  */
 576                 int urlencode_readdir_entries;
 577
 578                 /*
 579                  * Some Windows versions appear to have a limit to the number
 580                  * of concurrent SESSIONs and/or TREE CONNECTions.  In
 581                  * one-shot programs (i.e. the program runs and then quickly
 582                  * ends, thereby shutting down all connections), it is
 583                  * probably reasonable to establish a new connection for each
 584                  * share.  In long-running applications, the limitation can be
 585                  * avoided by using only a single connection to each server,
 586                  * and issuing a new TREE CONNECT when the share is accessed.
 587                  */
 588                 int one_share_per_server;
 589         } options;
 590
 591         /* Add additional functions here for ABI backward compatibility */
 592         int        (*ftruncate)(SMBCCTX *c, SMBCFILE *f, off_t size);
 593
 594         /** INTERNAL DATA
 595          * do _NOT_ touch this from your program !
 596          */
 597         struct smbc_internal_data * internal;
 598 };
 599
 600 /* Flags for SMBCCTX->flags */
 601 #define SMB_CTX_FLAG_USE_KERBEROS (1 << 0)
 602 #define SMB_CTX_FLAG_FALLBACK_AFTER_KERBEROS (1 << 1)
 603 #define SMBCCTX_FLAG_NO_AUTO_ANONYMOUS_LOGON (1 << 2) /* don't try to do automatic anon login */
 604
 605 /**@ingroup misc
 606  * Create a new SBMCCTX (a context).
 607  *
 608  * Must be called before the context is passed to smbc_context_init()
 609  *
 610  * @return          The given SMBCCTX pointer on success, NULL on error with errno set:
 611  *                  - ENOMEM Out of memory
 612  *
 613  * @see             smbc_free_context(), smbc_init_context()
 614  *
 615  * @note            Do not forget to smbc_init_context() the returned SMBCCTX pointer !
 616  */
 617 SMBCCTX * smbc_new_context(void);
 618
 619 /**@ingroup misc
 620  * Delete a SBMCCTX (a context) acquired from smbc_new_context().
 621  *
 622  * The context will be deleted if possible.
 623  *
 624  * @param context   A pointer to a SMBCCTX obtained from smbc_new_context()
 625  *
 626  * @param shutdown_ctx   If 1, all connections and files will be closed even if they are busy.
 627  *
 628  *
 629  * @return          Returns 0 on succes. Returns 1 on failure with errno set:
 630  *                  - EBUSY Server connections are still used, Files are open or cache
 631  *                          could not be purged
 632  *                  - EBADF context == NULL
 633  *
 634  * @see             smbc_new_context()
 635  *
 636  * @note            It is advised to clean up all the contexts with shutdown_ctx set to 1
 637  *                  just before exit()'ing. When shutdown_ctx is 0, this function can be
 638  *                  use in periodical cleanup functions for example.
 639  */
 640 int smbc_free_context(SMBCCTX * context, int shutdown_ctx);
 641
 642
 643 /**@ingroup misc
 644  * Each time the context structure is changed, we have binary backward
 645  * compatibility issues.  Instead of modifying the public portions of the
 646  * context structure to add new options, instead, we put them in the internal
 647  * portion of the context structure and provide a set function for these new
 648  * options.
 649  *
 650  * @param context   A pointer to a SMBCCTX obtained from smbc_new_context()
 651  *
 652  * @param option_name
 653  *                  The name of the option for which the value is to be set
 654  *
 655  * @param option_value
 656  *                  The new value of the option being set
 657  *
 658  */
 659 void
 660 smbc_option_set(SMBCCTX *context,
 661                 char *option_name,
 662                 ... /* option_value */);
 663 /*
 664  * Retrieve the current value of an option
 665  *
 666  * @param context   A pointer to a SMBCCTX obtained from smbc_new_context()
 667  *
 668  * @param option_name
 669  *                  The name of the option for which the value is to be
 670  *                  retrieved
 671  *
 672  * @return          The value of the specified option.
 673  */
 674 void *
 675 smbc_option_get(SMBCCTX *context,
 676                 char *option_name);
 677
 678 /**@ingroup misc
 679  * Initialize a SBMCCTX (a context).
 680  *
 681  * Must be called before using any SMBCCTX API function
 682  *
 683  * @param context   A pointer to a SMBCCTX obtained from smbc_new_context()
 684  *
 685  * @return          A pointer to the given SMBCCTX on success,
 686  *                  NULL on error with errno set:
 687  *                  - EBADF  NULL context given
 688  *                  - ENOMEM Out of memory
 689  *                  - ENOENT The smb.conf file would not load
 690  *
 691  * @see             smbc_new_context()
 692  *
 693  * @note            my_context = smbc_init_context(smbc_new_context())
 694  *                  is perfectly safe, but it might leak memory on
 695  *                  smbc_context_init() failure. Avoid this.
 696  *                  You'll have to call smbc_free_context() yourself
 697  *                  on failure.
 698  */
 699
 700 SMBCCTX * smbc_init_context(SMBCCTX * context);
 701
 702 /**@ingroup misc
 703  * Initialize the samba client library.
 704  *
 705  * Must be called before using any of the smbclient API function
 706  *
 707  * @param fn        The function that will be called to obtaion
 708  *                  authentication credentials.
 709  *
 710  * @param debug     Allows caller to set the debug level. Can be
 711  *                  changed in smb.conf file. Allows caller to set
 712  *                  debugging if no smb.conf.
 713  *
 714  * @return          0 on success, < 0 on error with errno set:
 715  *                  - ENOMEM Out of memory
 716  *                  - ENOENT The smb.conf file would not load
 717  *
 718  */
 719
 720 int smbc_init(smbc_get_auth_data_fn fn, int debug);
 721
 722 /**@ingroup misc
 723  * Set or retrieve the compatibility library's context pointer
 724  *
 725  * @param context   New context to use, or NULL.  If a new context is provided,
 726  *                  it must have allocated with smbc_new_context() and
 727  *                  initialized with smbc_init_context(), followed, optionally,
 728  *                  by some manual changes to some of the non-internal fields.
 729  *
 730  * @return          The old context.
 731  *
 732  * @see             smbc_new_context(), smbc_init_context(), smbc_init()
 733  *
 734  * @note            This function may be called prior to smbc_init() to force
 735  *                  use of the next context without any internal calls to
 736  *                  smbc_new_context() or smbc_init_context().  It may also
 737  *                  be called after smbc_init() has already called those two
 738  *                  functions, to replace the existing context with a new one.
 739  *                  Care should be taken, in this latter case, to ensure that
 740  *                  the server cache and any data allocated by the
 741  *                  authentication functions have been freed, if necessary.
 742  */
 743
 744 SMBCCTX * smbc_set_context(SMBCCTX * new_context);
 745
 746 /**@ingroup file
 747  * Open a file on an SMB server.
 748  *
 749  * @param furl      The smb url of the file to be opened.
 750  *
 751  * @param flags     Is one of O_RDONLY, O_WRONLY or O_RDWR which
 752  *                  request opening  the  file  read-only,write-only
 753  *                  or read/write. flags may also be bitwise-or'd with
 754  *                  one or  more of  the following:
 755  *                  O_CREAT - If the file does not exist it will be
 756  *                  created.
 757  *                  O_EXCL - When  used with O_CREAT, if the file
 758  *                  already exists it is an error and the open will
 759  *                  fail.
 760  *                  O_TRUNC - If the file already exists it will be
 761  *                  truncated.
 762  *                  O_APPEND The  file  is  opened  in  append mode
 763  *
 764  * @param mode      mode specifies the permissions to use if a new
 765  *                  file is created.  It  is  modified  by  the
 766  *                  process's umask in the usual way: the permissions
 767  *                  of the created file are (mode & ~umask)
 768  *
 769  *                  Not currently use, but there for future use.
 770  *                  We will map this to SYSTEM, HIDDEN, etc bits
 771  *                  that reverses the mapping that smbc_fstat does.
 772  *
 773  * @return          Valid file handle, < 0 on error with errno set:
 774  *                  - ENOMEM  Out of memory
 775  *                  - EINVAL if an invalid parameter passed, like no
 776  *                  file, or smbc_init not called.
 777  *                  - EEXIST  pathname already exists and O_CREAT and
 778  *                  O_EXCL were used.
 779  *                  - EISDIR  pathname  refers  to  a  directory  and
 780  *                  the access requested involved writing.
 781  *                  - EACCES  The requested access to the file is not
 782  *                  allowed
 783  *                  - ENODEV The requested share does not exist
 784  *                  - ENOTDIR A file on the path is not a directory
 785  *                  - ENOENT  A directory component in pathname does
 786  *                  not exist.
 787  *
 788  * @see             smbc_creat()
 789  *
 790  * @note            This call uses an underlying routine that may create
 791  *                  a new connection to the server specified in the URL.
 792  *                  If the credentials supplied in the URL, or via the
 793  *                  auth_fn in the smbc_init call, fail, this call will
 794  *                  try again with an empty username and password. This
 795  *                  often gets mapped to the guest account on some machines.
 796  */
 797
 798 int smbc_open(const char *furl, int flags, mode_t mode);
 799
 800 /**@ingroup file
 801  * Create a file on an SMB server.
 802  *
 803  * Same as calling smbc_open() with flags = O_CREAT|O_WRONLY|O_TRUNC
 804  *
 805  * @param furl      The smb url of the file to be created
 806  *
 807  * @param mode      mode specifies the permissions to use if  a  new
 808  *                  file is created.  It  is  modified  by  the
 809  *                  process's umask in the usual way: the permissions
 810  *                  of the created file are (mode & ~umask)
 811  *
 812  *                  NOTE, the above is not true. We are dealing with
 813  *                  an SMB server, which has no concept of a umask!
 814  *
 815  * @return          Valid file handle, < 0 on error with errno set:
 816  *                  - ENOMEM  Out of memory
 817  *                  - EINVAL if an invalid parameter passed, like no
 818  *                  file, or smbc_init not called.
 819  *                  - EEXIST  pathname already exists and O_CREAT and
 820  *                  O_EXCL were used.
 821  *                  - EISDIR  pathname  refers  to  a  directory  and
 822  *                  the access requested involved writing.
 823  *                  - EACCES  The requested access to the file is not
 824  *                  allowed
 825  *                  - ENOENT  A directory component in pathname does
 826  *                  not exist.
 827  *                  - ENODEV The requested share does not exist.
 828  * @see             smbc_open()
 829  *
 830  */
 831
 832 int smbc_creat(const char *furl, mode_t mode);
 833
 834 /**@ingroup file
 835  * Read from a file using an opened file handle.
 836  *
 837  * @param fd        Open file handle from smbc_open() or smbc_creat()
 838  *
 839  * @param buf       Pointer to buffer to recieve read data
 840  *
 841  * @param bufsize   Size of buf in bytes
 842  *
 843  * @return          Number of bytes read, < 0 on error with errno set:
 844  *                  - EISDIR fd refers to a directory
 845  *                  - EBADF  fd  is  not  a valid file descriptor or
 846  *                  is not open for reading.
 847  *                  - EINVAL fd is attached to an object which is
 848  *                  unsuitable for reading, or no buffer passed or
 849  *                  smbc_init not called.
 850  *
 851  * @see             smbc_open(), smbc_write()
 852  *
 853  */
 854 ssize_t smbc_read(int fd, void *buf, size_t bufsize);
 855
 856
 857 /**@ingroup file
 858  * Write to a file using an opened file handle.
 859  *
 860  * @param fd        Open file handle from smbc_open() or smbc_creat()
 861  *
 862  * @param buf       Pointer to buffer to recieve read data
 863  *
 864  * @param bufsize   Size of buf in bytes
 865  *
 866  * @return          Number of bytes written, < 0 on error with errno set:
 867  *                  - EISDIR fd refers to a directory.
 868  *                  - EBADF  fd  is  not  a valid file descriptor or
 869  *                  is not open for reading.
 870  *                  - EINVAL fd is attached to an object which is
 871  *                  unsuitable for reading, or no buffer passed or
 872  *                  smbc_init not called.
 873  *
 874  * @see             smbc_open(), smbc_read()
 875  *
 876  */
 877 ssize_t smbc_write(int fd, void *buf, size_t bufsize);
 878
 879
 880 /**@ingroup file
 881  * Seek to a specific location in a file.
 882  *
 883  * @param fd        Open file handle from smbc_open() or smbc_creat()
 884  *
 885  * @param offset    Offset in bytes from whence
 886  *
 887  * @param whence    A location in the file:
 888  *                  - SEEK_SET The offset is set to offset bytes from
 889  *                  the beginning of the file
 890  *                  - SEEK_CUR The offset is set to current location
 891  *                  plus offset bytes.
 892  *                  - SEEK_END The offset is set to the size of the
 893  *                  file plus offset bytes.
 894  *
 895  * @return          Upon successful completion, lseek returns the
 896  *                  resulting offset location as measured in bytes
 897  *                  from the beginning  of the file. Otherwise, a value
 898  *                  of (off_t)-1 is returned and errno is set to
 899  *                  indicate the error:
 900  *                  - EBADF  Fildes is not an open file descriptor.
 901  *                  - EINVAL Whence is not a proper value or smbc_init
 902  *                    not called.
 903  *
 904  * @todo Are all the whence values really supported?
 905  *
 906  * @todo Are errno values complete and correct?
 907  */
 908 off_t smbc_lseek(int fd, off_t offset, int whence);
 909
 910
 911 /**@ingroup file
 912  * Close an open file handle.
 913  *
 914  * @param fd        The file handle to close
 915  *
 916  * @return          0 on success, < 0 on error with errno set:
 917  *                  - EBADF  fd isn't a valid open file descriptor
 918  *                  - EINVAL smbc_init() failed or has not been called
 919  *
 920  * @see             smbc_open(), smbc_creat()
 921  */
 922 int smbc_close(int fd);
 923
 924
 925 /**@ingroup directory
 926  * Unlink (delete) a file or directory.
 927  *
 928  * @param furl      The smb url of the file to delete
 929  *
 930  * @return          0 on success, < 0 on error with errno set:
 931  *                  - EACCES or EPERM Write  access  to the directory
 932  *                  containing pathname is not allowed or one
 933  *                  of  the  directories in pathname did not allow
 934  *                  search (execute) permission
 935  *                  - ENOENT A directory component in pathname does
 936  *                  not exist
 937  *                  - EINVAL NULL was passed in the file param or
 938  *                    smbc_init not called.
 939  *                  - EACCES You do not have access to the file
 940  *                  - ENOMEM Insufficient kernel memory was available
 941  *
 942  * @see             smbc_rmdir()s
 943  *
 944  * @todo Are errno values complete and correct?
 945  */
 946 int smbc_unlink(const char *furl);
 947
 948
 949 /**@ingroup directory
 950  * Rename or move a file or directory.
 951  *
 952  * @param ourl      The original smb url (source url) of file or
 953  *                  directory to be moved
 954  *
 955  * @param nurl      The new smb url (destination url) of the file
 956  *                  or directory after the move.  Currently nurl must
 957  *                  be on the same share as ourl.
 958  *
 959  * @return          0 on success, < 0 on error with errno set:
 960  *                  - EISDIR nurl is an existing directory, but ourl is
 961  *                  not a directory.
 962  *                  - EEXIST nurl is  a  non-empty directory,
 963  *                  i.e., contains entries other than "." and ".."
 964  *                  - EINVAL The  new  url  contained  a path prefix
 965  *                  of the old, or, more generally, an  attempt was
 966  *                  made  to make a directory a subdirectory of itself
 967  *                  or smbc_init not called.
 968  *                  - ENOTDIR A component used as a directory in ourl
 969  *                  or nurl path is not, in fact, a directory.  Or,
 970  *                  ourl  is a directory, and newpath exists but is not
 971  *                  a directory.
 972  *                  - EACCES or EPERM Write access to the directory
 973  *                  containing ourl or nurl is not allowed for the
 974  *                  process's effective uid,  or  one of the
 975  *                  directories in ourl or nurl did not allow search
 976  *                  (execute) permission,  or ourl  was  a  directory
 977  *                  and did not allow write permission.
 978  *                  - ENOENT A  directory component in ourl or nurl
 979  *                  does not exist.
 980  *                  - EXDEV Rename across shares not supported.
 981  *                  - ENOMEM Insufficient kernel memory was available.
 982  *                  - EEXIST The target file, nurl, already exists.
 983  *
 984  *
 985  * @todo Are we going to support copying when urls are not on the same
 986  *       share?  I say no... NOTE. I agree for the moment.
 987  *
 988  */
 989 int smbc_rename(const char *ourl, const char *nurl);
 990
 991
 992 /**@ingroup directory
 993  * Open a directory used to obtain directory entries.
 994  *
 995  * @param durl      The smb url of the directory to open
 996  *
 997  * @return          Valid directory handle. < 0 on error with errno set:
 998  *                  - EACCES Permission denied.
 999  *                  - EINVAL A NULL file/URL was passed, or the URL would
1000  *                  not parse, or was of incorrect form or smbc_init not
1001  *                  called.
1002  *                  - ENOENT durl does not exist, or name is an
1003  *                  - ENOMEM Insufficient memory to complete the
1004  *                  operation.
1005  *                  - ENOTDIR name is not a directory.
1006  *                  - EPERM the workgroup could not be found.
1007  *                  - ENODEV the workgroup or server could not be found.
1008  *
1009  * @see             smbc_getdents(), smbc_readdir(), smbc_closedir()
1010  *
1011  */
1012 int smbc_opendir(const char *durl);
1013
1014
1015 /**@ingroup directory
1016  * Close a directory handle opened by smbc_opendir().
1017  *
1018  * @param dh        Directory handle to close
1019  *
1020  * @return          0 on success, < 0 on error with errno set:
1021  *                  - EBADF dh is an invalid directory handle
1022  *
1023  * @see             smbc_opendir()
1024  */
1025 int smbc_closedir(int dh);
1026
1027
1028 /**@ingroup directory
1029  * Get multiple directory entries.
1030  *
1031  * smbc_getdents() reads as many dirent structures from the an open
1032  * directory handle into a specified memory area as will fit.
1033  *
1034  * @param dh        Valid directory as returned by smbc_opendir()
1035  *
1036  * @param dirp      pointer to buffer that will receive the directory
1037  *                  entries.
1038  *
1039  * @param count     The size of the dirp buffer in bytes
1040  *
1041  * @returns         If any dirents returned, return will indicate the
1042  *                  total size. If there were no more dirents available,
1043  *                  0 is returned. < 0 indicates an error.
1044  *                  - EBADF  Invalid directory handle
1045  *                  - EINVAL Result buffer is too small or smbc_init
1046  *                  not called.
1047  *                  - ENOENT No such directory.
1048  * @see             , smbc_dirent, smbc_readdir(), smbc_open()
1049  *
1050  * @todo Are errno values complete and correct?
1051  *
1052  * @todo Add example code so people know how to parse buffers.
1053  */
1054 int smbc_getdents(unsigned int dh, struct smbc_dirent *dirp, int count);
1055
1056
1057 /**@ingroup directory
1058  * Get a single directory entry.
1059  *
1060  * @param dh        Valid directory as returned by smbc_opendir()
1061  *
1062  * @return          A pointer to a smbc_dirent structure, or NULL if an
1063  *                  error occurs or end-of-directory is reached:
1064  *                  - EBADF Invalid directory handle
1065  *                  - EINVAL smbc_init() failed or has not been called
1066  *
1067  * @see             smbc_dirent, smbc_getdents(), smbc_open()
1068  */
1069 struct smbc_dirent* smbc_readdir(unsigned int dh);
1070
1071
1072 /**@ingroup directory
1073  * Get the current directory offset.
1074  *
1075  * smbc_telldir() may be used in conjunction with smbc_readdir() and
1076  * smbc_lseekdir().
1077  *
1078  * @param dh        Valid directory as returned by smbc_opendir()
1079  *
1080  * @return          The current location in the directory stream or -1
1081  *                  if an error occur.  The current location is not
1082  *                  an offset. Becuase of the implementation, it is a
1083  *                  handle that allows the library to find the entry
1084  *                  later.
1085  *                  - EBADF dh is not a valid directory handle
1086  *                  - EINVAL smbc_init() failed or has not been called
1087  *                  - ENOTDIR if dh is not a directory
1088  *
1089  * @see             smbc_readdir()
1090  *
1091  */
1092 off_t smbc_telldir(int dh);
1093
1094
1095 /**@ingroup directory
1096  * lseek on directories.
1097  *
1098  * smbc_lseekdir() may be used in conjunction with smbc_readdir() and
1099  * smbc_telldir(). (rewind by smbc_lseekdir(fd, NULL))
1100  *
1101  * @param fd        Valid directory as returned by smbc_opendir()
1102  *
1103  * @param offset    The offset (as returned by smbc_telldir). Can be
1104  *                  NULL, in which case we will rewind
1105  *
1106  * @return          0 on success, -1 on failure
1107  *                  - EBADF dh is not a valid directory handle
1108  *                  - ENOTDIR if dh is not a directory
1109  *                  - EINVAL offset did not refer to a valid dirent or
1110  *                    smbc_init not called.
1111  *
1112  * @see             smbc_telldir()
1113  *
1114  *
1115  * @todo In what does the reture and errno values mean?
1116  */
1117 int smbc_lseekdir(int fd, off_t offset);
1118
1119 /**@ingroup directory
1120  * Create a directory.
1121  *
1122  * @param durl      The url of the directory to create
1123  *
1124  * @param mode      Specifies  the  permissions to use. It is modified
1125  *                  by the process's umask in the usual way: the
1126  *                  permissions of the created file are (mode & ~umask).
1127  *
1128  * @return          0 on success, < 0 on error with errno set:
1129  *                  - EEXIST directory url already exists
1130  *                  - EACCES The parent directory does not allow write
1131  *                  permission to the process, or one of the directories
1132  *                  - ENOENT A directory component in pathname does not
1133  *                  exist.
1134  *                  - EINVAL NULL durl passed or smbc_init not called.
1135  *                  - ENOMEM Insufficient memory was available.
1136  *
1137  * @see             smbc_rmdir()
1138  *
1139  */
1140 int smbc_mkdir(const char *durl, mode_t mode);
1141
1142
1143 /**@ingroup directory
1144  * Remove a directory.
1145  *
1146  * @param durl      The smb url of the directory to remove
1147  *
1148  * @return          0 on success, < 0 on error with errno set:
1149  *                  - EACCES or EPERM Write access to the directory
1150  *                  containing pathname was not allowed.
1151  *                  - EINVAL durl is NULL or smbc_init not called.
1152  *                  - ENOENT A directory component in pathname does not
1153  *                  exist.
1154  *                  - ENOTEMPTY directory contains entries.
1155  *                  - ENOMEM Insufficient kernel memory was available.
1156  *
1157  * @see             smbc_mkdir(), smbc_unlink()
1158  *
1159  * @todo Are errno values complete and correct?
1160  */
1161 int smbc_rmdir(const char *durl);
1162
1163
1164 /**@ingroup attribute
1165  * Get information about a file or directory.
1166  *
1167  * @param url       The smb url to get information for
1168  *
1169  * @param st        pointer to a buffer that will be filled with
1170  *                  standard Unix struct stat information.
1171  *
1172  * @return          0 on success, < 0 on error with errno set:
1173  *                  - ENOENT A component of the path file_name does not
1174  *                  exist.
1175  *                  - EINVAL a NULL url was passed or smbc_init not called.
1176  *                  - EACCES Permission denied.
1177  *                  - ENOMEM Out of memory
1178  *                  - ENOTDIR The target dir, url, is not a directory.
1179  *
1180  * @see             Unix stat()
1181  *
1182  */
1183 int smbc_stat(const char *url, struct stat *st);
1184
1185
1186 /**@ingroup attribute
1187  * Get file information via an file descriptor.
1188  *
1189  * @param fd        Open file handle from smbc_open() or smbc_creat()
1190  *
1191  * @param st        pointer to a buffer that will be filled with
1192  *                  standard Unix struct stat information.
1193  *
1194  * @return          EBADF  filedes is bad.
1195  *                  - EACCES Permission denied.
1196  *                  - EBADF fd is not a valid file descriptor
1197  *                  - EINVAL Problems occurred in the underlying routines
1198  *                    or smbc_init not called.
1199  *                  - ENOMEM Out of memory
1200  *
1201  * @see             smbc_stat(), Unix stat()
1202  *
1203  */
1204 int smbc_fstat(int fd, struct stat *st);
1205
1206
1207 /**@ingroup attribute
1208  * Truncate a file given a file descriptor
1209  *
1210  * @param fd        Open file handle from smbc_open() or smbc_creat()
1211  *
1212  * @param size      size to truncate the file to
1213  *
1214  * @return          EBADF  filedes is bad.
1215  *                  - EACCES Permission denied.
1216  *                  - EBADF fd is not a valid file descriptor
1217  *                  - EINVAL Problems occurred in the underlying routines
1218  *                    or smbc_init not called.
1219  *                  - ENOMEM Out of memory
1220  *
1221  * @see             , Unix ftruncate()
1222  *
1223  */
1224 int smbc_ftruncate(int fd, off_t size);
1225
1226
1227 /**@ingroup attribue
1228  * Change the ownership of a file or directory.
1229  *
1230  * @param url       The smb url of the file or directory to change
1231  *                  ownership of.
1232  *
1233  * @param owner     I have no idea?
1234  *
1235  * @param group     I have not idea?
1236  *
1237  * @return          0 on success, < 0 on error with errno set:
1238  *                  - EPERM  The effective UID does not match the owner
1239  *                  of the file, and is not zero; or the owner or group
1240  *                  were specified incorrectly.
1241  *                  - ENOENT The file does not exist.
1242  *                  - ENOMEM Insufficient was available.
1243  *                  - ENOENT file or directory does not exist
1244  *
1245  * @todo Are we actually going to be able to implement this function
1246  *
1247  * @todo How do we abstract owner and group uid and gid?
1248  *
1249  */
1250 int smbc_chown(const char *url, uid_t owner, gid_t group);
1251
1252
1253 /**@ingroup attribute
1254  * Change the permissions of a file.
1255  *
1256  * @param url       The smb url of the file or directory to change
1257  *                  permissions of
1258  *
1259  * @param mode      The permissions to set:
1260  *                  - Put good explaination of permissions here!
1261  *
1262  * @return          0 on success, < 0 on error with errno set:
1263  *                  - EPERM  The effective UID does not match the owner
1264  *                  of the file, and is not zero
1265  *                  - ENOENT The file does not exist.
1266  *                  - ENOMEM Insufficient was available.
1267  *                  - ENOENT file or directory does not exist
1268  *
1269  * @todo Actually implement this fuction?
1270  *
1271  * @todo Are errno values complete and correct?
1272  */
1273 int smbc_chmod(const char *url, mode_t mode);
1274
1275 /**
1276  * @ingroup attribute
1277  * Change the last modification time on a file
1278  *
1279  * @param url       The smb url of the file or directory to change
1280  *                  the modification time of
1281  *
1282  * @param tbuf      An array of two timeval structures which contains,
1283  *                  respectively, the desired access and modification times.
1284  *                  NOTE: Only the tv_sec field off each timeval structure is
1285  *                  used.  The tv_usec (microseconds) portion is ignored.
1286  *
1287  * @return          0 on success, < 0 on error with errno set:
1288  *                  - EINVAL The client library is not properly initialized
1289  *                  - EPERM  Permission was denied.
1290  *
1291  */
1292 int smbc_utimes(const char *url, struct timeval *tbuf);
1293
1294 #ifdef HAVE_UTIME_H
1295 /**
1296  * @ingroup attribute
1297  * Change the last modification time on a file
1298  *
1299  * @param url       The smb url of the file or directory to change
1300  *                  the modification time of
1301  *
1302  * @param utbuf     A pointer to a utimebuf structure which contains the
1303  *                  desired access and modification times.
1304  *
1305  * @return          0 on success, < 0 on error with errno set:
1306  *                  - EINVAL The client library is not properly initialized
1307  *                  - ENOMEM No memory was available for internal needs
1308  *                  - EPERM  Permission was denied.
1309  *
1310  */
1311 int smbc_utime(const char *fname, struct utimbuf *utbuf);
1312 #endif
1313
1314 /**@ingroup attribute
1315  * Set extended attributes for a file.  This is used for modifying a file's
1316  * security descriptor (i.e. owner, group, and access control list)
1317  *
1318  * @param url       The smb url of the file or directory to set extended
1319  *                  attributes for.
1320  *
1321  * @param name      The name of an attribute to be changed.  Names are of
1322  *                  one of the following forms:
1323  *
1324  *                     system.nt_sec_desc.<attribute name>
1325  *                     system.nt_sec_desc.*
1326  *                     system.nt_sec_desc.*+
1327  *
1328  *                  where <attribute name> is one of:
1329  *
1330  *                     revision
1331  *                     owner
1332  *                     owner+
1333  *                     group
1334  *                     group+
1335  *                     acl:<name or sid>
1336  *                     acl+:<name or sid>
1337  *
1338  *                  In the forms "system.nt_sec_desc.*" and
1339  *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
1340  *                  literal, i.e. the string is provided exactly as shown, and
1341  *                  the value parameter should contain a complete security
1342  *                  descriptor with name:value pairs separated by tabs,
1343  *                  commas, or newlines (not spaces!).
1344  *
1345  *                  The plus sign ('+') indicates that SIDs should be mapped
1346  *                  to names.  Without the plus sign, SIDs are not mapped;
1347  *                  rather they are simply converted to a string format.
1348  *
1349  * @param value     The value to be assigned to the specified attribute name.
1350  *                  This buffer should contain only the attribute value if the
1351  *                  name was of the "system.nt_sec_desc.<attribute_name>"
1352  *                  form.  If the name was of the "system.nt_sec_desc.*" form
1353  *                  then a complete security descriptor, with name:value pairs
1354  *                  separated by tabs, commas, or newlines (not spaces!),
1355  *                  should be provided in this value buffer.  A complete
1356  *                  security descriptor will contain one or more entries
1357  *                  selected from the following:
1358  *
1359  *                    REVISION:<revision number>
1360  *                    OWNER:<sid or name>
1361  *                    GROUP:<sid or name>
1362  *                    ACL:<sid or name>:<type>/<flags>/<mask>
1363  *
1364  *                  The  revision of the ACL specifies the internal Windows NT
1365  *                  ACL revision for the security descriptor. If not specified
1366  *                  it defaults to  1.  Using values other than 1 may cause
1367  *                  strange behaviour.
1368  *
1369  *                  The owner and group specify the owner and group sids for
1370  *                  the object. If the attribute name (either '*+' with a
1371  *                  complete security descriptor, or individual 'owner+' or
1372  *                  'group+' attribute names) ended with a plus sign, the
1373  *                  specified name is resolved to a SID value, using the
1374  *                  server on which the file or directory resides.  Otherwise,
1375  *                  the value should be provided in SID-printable format as
1376  *                  S-1-x-y-z, and is used directly.  The <sid or name>
1377  *                  associated with the ACL: attribute should be provided
1378  *                  similarly.
1379  *
1380  * @param size      The number of the bytes of data in the value buffer
1381  *
1382  * @param flags     A bit-wise OR of zero or more of the following:
1383  *                    SMBC_XATTR_FLAG_CREATE -
1384  *                      fail if the named attribute already exists
1385  *                    SMBC_XATTR_FLAG_REPLACE -
1386  *                      fail if the attribute does not already exist
1387  *
1388  *                  If neither flag is specified, the specified attributes
1389  *                  will be added or replace existing attributes of the same
1390  *                  name, as necessary.
1391  *
1392  * @return          0 on success, < 0 on error with errno set:
1393  *                  - EINVAL  The client library is not properly initialized
1394  *                            or one of the parameters is not of a correct
1395  *                            form
1396  *                  - ENOMEM No memory was available for internal needs
1397  *                  - EEXIST  If the attribute already exists and the flag
1398  *                            SMBC_XATTR_FLAG_CREAT was specified
1399  *                  - ENOATTR If the attribute does not exist and the flag
1400  *                            SMBC_XATTR_FLAG_REPLACE was specified
1401  *                  - EPERM   Permission was denied.
1402  *                  - ENOTSUP The referenced file system does not support
1403  *                            extended attributes
1404  *
1405  * @note            Attribute names are compared in a case-insensitive
1406  *                  fashion.  All of the following are equivalent, although
1407  *                  the all-lower-case name is the preferred format:
1408  *                    system.nt_sec_desc.owner
1409  *                    SYSTEM.NT_SEC_DESC.OWNER
1410  *                    sYsTeM.nt_sEc_desc.owNER
1411  *
1412  */
1413 int smbc_setxattr(const char *url,
1414                   const char *name,
1415                   const void *value,
1416                   size_t size,
1417                   int flags);
1418
1419
1420 /**@ingroup attribute
1421  * Set extended attributes for a file.  This is used for modifying a file's
1422  * security descriptor (i.e. owner, group, and access control list).  The
1423  * POSIX function which this maps to would act on a symbolic link rather than
1424  * acting on what the symbolic link points to, but with no symbolic links in
1425  * SMB file systems, this function is functionally identical to
1426  * smbc_setxattr().
1427  *
1428  * @param url       The smb url of the file or directory to set extended
1429  *                  attributes for.
1430  *
1431  * @param name      The name of an attribute to be changed.  Names are of
1432  *                  one of the following forms:
1433  *
1434  *                     system.nt_sec_desc.<attribute name>
1435  *                     system.nt_sec_desc.*
1436  *                     system.nt_sec_desc.*+
1437  *
1438  *                  where <attribute name> is one of:
1439  *
1440  *                     revision
1441  *                     owner
1442  *                     owner+
1443  *                     group
1444  *                     group+
1445  *                     acl:<name or sid>
1446  *                     acl+:<name or sid>
1447  *
1448  *                  In the forms "system.nt_sec_desc.*" and
1449  *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
1450  *                  literal, i.e. the string is provided exactly as shown, and
1451  *                  the value parameter should contain a complete security
1452  *                  descriptor with name:value pairs separated by tabs,
1453  *                  commas, or newlines (not spaces!).
1454  *
1455  *                  The plus sign ('+') indicates that SIDs should be mapped
1456  *                  to names.  Without the plus sign, SIDs are not mapped;
1457  *                  rather they are simply converted to a string format.
1458  *
1459  * @param value     The value to be assigned to the specified attribute name.
1460  *                  This buffer should contain only the attribute value if the
1461  *                  name was of the "system.nt_sec_desc.<attribute_name>"
1462  *                  form.  If the name was of the "system.nt_sec_desc.*" form
1463  *                  then a complete security descriptor, with name:value pairs
1464  *                  separated by tabs, commas, or newlines (not spaces!),
1465  *                  should be provided in this value buffer.  A complete
1466  *                  security descriptor will contain one or more entries
1467  *                  selected from the following:
1468  *
1469  *                    REVISION:<revision number>
1470  *                    OWNER:<sid or name>
1471  *                    GROUP:<sid or name>
1472  *                    ACL:<sid or name>:<type>/<flags>/<mask>
1473  *
1474  *                  The  revision of the ACL specifies the internal Windows NT
1475  *                  ACL revision for the security descriptor. If not specified
1476  *                  it defaults to  1.  Using values other than 1 may cause
1477  *                  strange behaviour.
1478  *
1479  *                  The owner and group specify the owner and group sids for
1480  *                  the object. If the attribute name (either '*+' with a
1481  *                  complete security descriptor, or individual 'owner+' or
1482  *                  'group+' attribute names) ended with a plus sign, the
1483  *                  specified name is resolved to a SID value, using the
1484  *                  server on which the file or directory resides.  Otherwise,
1485  *                  the value should be provided in SID-printable format as
1486  *                  S-1-x-y-z, and is used directly.  The <sid or name>
1487  *                  associated with the ACL: attribute should be provided
1488  *                  similarly.
1489  *
1490  * @param size      The number of the bytes of data in the value buffer
1491  *
1492  * @param flags     A bit-wise OR of zero or more of the following:
1493  *                    SMBC_XATTR_FLAG_CREATE -
1494  *                      fail if the named attribute already exists
1495  *                    SMBC_XATTR_FLAG_REPLACE -
1496  *                      fail if the attribute does not already exist
1497  *
1498  *                  If neither flag is specified, the specified attributes
1499  *                  will be added or replace existing attributes of the same
1500  *                  name, as necessary.
1501  *
1502  * @return          0 on success, < 0 on error with errno set:
1503  *                  - EINVAL  The client library is not properly initialized
1504  *                            or one of the parameters is not of a correct
1505  *                            form
1506  *                  - ENOMEM No memory was available for internal needs
1507  *                  - EEXIST  If the attribute already exists and the flag
1508  *                            SMBC_XATTR_FLAG_CREAT was specified
1509  *                  - ENOATTR If the attribute does not exist and the flag
1510  *                            SMBC_XATTR_FLAG_REPLACE was specified
1511  *                  - EPERM   Permission was denied.
1512  *                  - ENOTSUP The referenced file system does not support
1513  *                            extended attributes
1514  *
1515  * @note            Attribute names are compared in a case-insensitive
1516  *                  fashion.  All of the following are equivalent, although
1517  *                  the all-lower-case name is the preferred format:
1518  *                    system.nt_sec_desc.owner
1519  *                    SYSTEM.NT_SEC_DESC.OWNER
1520  *                    sYsTeM.nt_sEc_desc.owNER
1521  *
1522  */
1523 int smbc_lsetxattr(const char *url,
1524                    const char *name,
1525                    const void *value,
1526                    size_t size,
1527                    int flags);
1528
1529
1530 /**@ingroup attribute
1531  * Set extended attributes for a file.  This is used for modifying a file's
1532  * security descriptor (i.e. owner, group, and access control list)
1533  *
1534  * @param fd        A file descriptor associated with an open file (as
1535  *                  previously returned by smbc_open(), to get extended
1536  *                  attributes for.
1537  *
1538  * @param name      The name of an attribute to be changed.  Names are of
1539  *                  one of the following forms:
1540  *
1541  *                     system.nt_sec_desc.<attribute name>
1542  *                     system.nt_sec_desc.*
1543  *                     system.nt_sec_desc.*+
1544  *
1545  *                  where <attribute name> is one of:
1546  *
1547  *                     revision
1548  *                     owner
1549  *                     owner+
1550  *                     group
1551  *                     group+
1552  *                     acl:<name or sid>
1553  *                     acl+:<name or sid>
1554  *
1555  *                  In the forms "system.nt_sec_desc.*" and
1556  *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
1557  *                  literal, i.e. the string is provided exactly as shown, and
1558  *                  the value parameter should contain a complete security
1559  *                  descriptor with name:value pairs separated by tabs,
1560  *                  commas, or newlines (not spaces!).
1561  *
1562  *                  The plus sign ('+') indicates that SIDs should be mapped
1563  *                  to names.  Without the plus sign, SIDs are not mapped;
1564  *                  rather they are simply converted to a string format.
1565  *
1566  * @param value     The value to be assigned to the specified attribute name.
1567  *                  This buffer should contain only the attribute value if the
1568  *                  name was of the "system.nt_sec_desc.<attribute_name>"
1569  *                  form.  If the name was of the "system.nt_sec_desc.*" form
1570  *                  then a complete security descriptor, with name:value pairs
1571  *                  separated by tabs, commas, or newlines (not spaces!),
1572  *                  should be provided in this value buffer.  A complete
1573  *                  security descriptor will contain one or more entries
1574  *                  selected from the following:
1575  *
1576  *                    REVISION:<revision number>
1577  *                    OWNER:<sid or name>
1578  *                    GROUP:<sid or name>
1579  *                    ACL:<sid or name>:<type>/<flags>/<mask>
1580  *
1581  *                  The  revision of the ACL specifies the internal Windows NT
1582  *                  ACL revision for the security descriptor. If not specified
1583  *                  it defaults to  1.  Using values other than 1 may cause
1584  *                  strange behaviour.
1585  *
1586  *                  The owner and group specify the owner and group sids for
1587  *                  the object. If the attribute name (either '*+' with a
1588  *                  complete security descriptor, or individual 'owner+' or
1589  *                  'group+' attribute names) ended with a plus sign, the
1590  *                  specified name is resolved to a SID value, using the
1591  *                  server on which the file or directory resides.  Otherwise,
1592  *                  the value should be provided in SID-printable format as
1593  *                  S-1-x-y-z, and is used directly.  The <sid or name>
1594  *                  associated with the ACL: attribute should be provided
1595  *                  similarly.
1596  *
1597  * @param size      The number of the bytes of data in the value buffer
1598  *
1599  * @param flags     A bit-wise OR of zero or more of the following:
1600  *                    SMBC_XATTR_FLAG_CREATE -
1601  *                      fail if the named attribute already exists
1602  *                    SMBC_XATTR_FLAG_REPLACE -
1603  *                      fail if the attribute does not already exist
1604  *
1605  *                  If neither flag is specified, the specified attributes
1606  *                  will be added or replace existing attributes of the same
1607  *                  name, as necessary.
1608  *
1609  * @return          0 on success, < 0 on error with errno set:
1610  *                  - EINVAL  The client library is not properly initialized
1611  *                            or one of the parameters is not of a correct
1612  *                            form
1613  *                  - ENOMEM No memory was available for internal needs
1614  *                  - EEXIST  If the attribute already exists and the flag
1615  *                            SMBC_XATTR_FLAG_CREAT was specified
1616  *                  - ENOATTR If the attribute does not exist and the flag
1617  *                            SMBC_XATTR_FLAG_REPLACE was specified
1618  *                  - EPERM   Permission was denied.
1619  *                  - ENOTSUP The referenced file system does not support
1620  *                            extended attributes
1621  *
1622  * @note            Attribute names are compared in a case-insensitive
1623  *                  fashion.  All of the following are equivalent, although
1624  *                  the all-lower-case name is the preferred format:
1625  *                    system.nt_sec_desc.owner
1626  *                    SYSTEM.NT_SEC_DESC.OWNER
1627  *                    sYsTeM.nt_sEc_desc.owNER
1628  *
1629  */
1630 int smbc_fsetxattr(int fd,
1631                    const char *name,
1632                    const void *value,
1633                    size_t size,
1634                    int flags);
1635
1636
1637 /**@ingroup attribute
1638  * Get extended attributes for a file.
1639  *
1640  * @param url       The smb url of the file or directory to get extended
1641  *                  attributes for.
1642  *
1643  * @param name      The name of an attribute to be retrieved.  Names are of
1644  *                  one of the following forms:
1645  *
1646  *                     system.nt_sec_desc.<attribute name>
1647  *                     system.nt_sec_desc.*
1648  *                     system.nt_sec_desc.*+
1649  *
1650  *                  where <attribute name> is one of:
1651  *
1652  *                     revision
1653  *                     owner
1654  *                     owner+
1655  *                     group
1656  *                     group+
1657  *                     acl:<name or sid>
1658  *                     acl+:<name or sid>
1659  *
1660  *                  In the forms "system.nt_sec_desc.*" and
1661  *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
1662  *                  literal, i.e. the string is provided exactly as shown, and
1663  *                  the value parameter will return a complete security
1664  *                  descriptor with name:value pairs separated by tabs,
1665  *                  commas, or newlines (not spaces!).
1666  *
1667  *                  The plus sign ('+') indicates that SIDs should be mapped
1668  *                  to names.  Without the plus sign, SIDs are not mapped;
1669  *                  rather they are simply converted to a string format.
1670  *
1671  * @param value     A pointer to a buffer in which the value of the specified
1672  *                  attribute will be placed (unless size is zero).
1673  *
1674  * @param size      The size of the buffer pointed to by value.  This parameter
1675  *                  may also be zero, in which case the size of the buffer
1676  *                  required to hold the attribute value will be returned,
1677  *                  but nothing will be placed into the value buffer.
1678  *
1679  * @return          0 on success, < 0 on error with errno set:
1680  *                  - EINVAL  The client library is not properly initialized
1681  *                            or one of the parameters is not of a correct
1682  *                            form
1683  *                  - ENOMEM No memory was available for internal needs
1684  *                  - EEXIST  If the attribute already exists and the flag
1685  *                            SMBC_XATTR_FLAG_CREAT was specified
1686  *                  - ENOATTR If the attribute does not exist and the flag
1687  *                            SMBC_XATTR_FLAG_REPLACE was specified
1688  *                  - EPERM   Permission was denied.
1689  *                  - ENOTSUP The referenced file system does not support
1690  *                            extended attributes
1691  *
1692  */
1693 int smbc_getxattr(const char *url,
1694                   const char *name,
1695                   const void *value,
1696                   size_t size);
1697
1698
1699 /**@ingroup attribute
1700  * Get extended attributes for a file.  The POSIX function which this maps to
1701  * would act on a symbolic link rather than acting on what the symbolic link
1702  * points to, but with no symbolic links in SMB file systems, this function
1703  * is functionally identical to smbc_getxattr().
1704  *
1705  * @param url       The smb url of the file or directory to get extended
1706  *                  attributes for.
1707  *
1708  * @param name      The name of an attribute to be retrieved.  Names are of
1709  *                  one of the following forms:
1710  *
1711  *                     system.nt_sec_desc.<attribute name>
1712  *                     system.nt_sec_desc.*
1713  *                     system.nt_sec_desc.*+
1714  *
1715  *                  where <attribute name> is one of:
1716  *
1717  *                     revision
1718  *                     owner
1719  *                     owner+
1720  *                     group
1721  *                     group+
1722  *                     acl:<name or sid>
1723  *                     acl+:<name or sid>
1724  *
1725  *                  In the forms "system.nt_sec_desc.*" and
1726  *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
1727  *                  literal, i.e. the string is provided exactly as shown, and
1728  *                  the value parameter will return a complete security
1729  *                  descriptor with name:value pairs separated by tabs,
1730  *                  commas, or newlines (not spaces!).
1731  *
1732  *                  The plus sign ('+') indicates that SIDs should be mapped
1733  *                  to names.  Without the plus sign, SIDs are not mapped;
1734  *                  rather they are simply converted to a string format.
1735  *
1736  * @param value     A pointer to a buffer in which the value of the specified
1737  *                  attribute will be placed (unless size is zero).
1738  *
1739  * @param size      The size of the buffer pointed to by value.  This parameter
1740  *                  may also be zero, in which case the size of the buffer
1741  *                  required to hold the attribute value will be returned,
1742  *                  but nothing will be placed into the value buffer.
1743  *
1744  * @return          0 on success, < 0 on error with errno set:
1745  *                  - EINVAL  The client library is not properly initialized
1746  *                            or one of the parameters is not of a correct
1747  *                            form
1748  *                  - ENOMEM No memory was available for internal needs
1749  *                  - EEXIST  If the attribute already exists and the flag
1750  *                            SMBC_XATTR_FLAG_CREAT was specified
1751  *                  - ENOATTR If the attribute does not exist and the flag
1752  *                            SMBC_XATTR_FLAG_REPLACE was specified
1753  *                  - EPERM   Permission was denied.
1754  *                  - ENOTSUP The referenced file system does not support
1755  *                            extended attributes
1756  *
1757  */
1758 int smbc_lgetxattr(const char *url,
1759                    const char *name,
1760                    const void *value,
1761                    size_t size);
1762
1763
1764 /**@ingroup attribute
1765  * Get extended attributes for a file.
1766  *
1767  * @param fd        A file descriptor associated with an open file (as
1768  *                  previously returned by smbc_open(), to get extended
1769  *                  attributes for.
1770  *
1771  * @param name      The name of an attribute to be retrieved.  Names are of
1772  *                  one of the following forms:
1773  *
1774  *                     system.nt_sec_desc.<attribute name>
1775  *                     system.nt_sec_desc.*
1776  *                     system.nt_sec_desc.*+
1777  *
1778  *                  where <attribute name> is one of:
1779  *
1780  *                     revision
1781  *                     owner
1782  *                     owner+
1783  *                     group
1784  *                     group+
1785  *                     acl:<name or sid>
1786  *                     acl+:<name or sid>
1787  *
1788  *                  In the forms "system.nt_sec_desc.*" and
1789  *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
1790  *                  literal, i.e. the string is provided exactly as shown, and
1791  *                  the value parameter will return a complete security
1792  *                  descriptor with name:value pairs separated by tabs,
1793  *                  commas, or newlines (not spaces!).
1794  *
1795  *                  The plus sign ('+') indicates that SIDs should be mapped
1796  *                  to names.  Without the plus sign, SIDs are not mapped;
1797  *                  rather they are simply converted to a string format.
1798  *
1799  * @param value     A pointer to a buffer in which the value of the specified
1800  *                  attribute will be placed (unless size is zero).
1801  *
1802  * @param size      The size of the buffer pointed to by value.  This parameter
1803  *                  may also be zero, in which case the size of the buffer
1804  *                  required to hold the attribute value will be returned,
1805  *                  but nothing will be placed into the value buffer.
1806  *
1807  * @return          0 on success, < 0 on error with errno set:
1808  *                  - EINVAL  The client library is not properly initialized
1809  *                            or one of the parameters is not of a correct
1810  *                            form
1811  *                  - ENOMEM No memory was available for internal needs
1812  *                  - EEXIST  If the attribute already exists and the flag
1813  *                            SMBC_XATTR_FLAG_CREAT was specified
1814  *                  - ENOATTR If the attribute does not exist and the flag
1815  *                            SMBC_XATTR_FLAG_REPLACE was specified
1816  *                  - EPERM   Permission was denied.
1817  *                  - ENOTSUP The referenced file system does not support
1818  *                            extended attributes
1819  *
1820  */
1821 int smbc_fgetxattr(int fd,
1822                    const char *name,
1823                    const void *value,
1824                    size_t size);
1825
1826
1827 /**@ingroup attribute
1828  * Remove extended attributes for a file.  This is used for modifying a file's
1829  * security descriptor (i.e. owner, group, and access control list)
1830  *
1831  * @param url       The smb url of the file or directory to remove the extended
1832  *                  attributes for.
1833  *
1834  * @param name      The name of an attribute to be removed.  Names are of
1835  *                  one of the following forms:
1836  *
1837  *                     system.nt_sec_desc.<attribute name>
1838  *                     system.nt_sec_desc.*
1839  *                     system.nt_sec_desc.*+
1840  *
1841  *                  where <attribute name> is one of:
1842  *
1843  *                     revision
1844  *                     owner
1845  *                     owner+
1846  *                     group
1847  *                     group+
1848  *                     acl:<name or sid>
1849  *                     acl+:<name or sid>
1850  *
1851  *                  In the forms "system.nt_sec_desc.*" and
1852  *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
1853  *                  literal, i.e. the string is provided exactly as shown, and
1854  *                  the value parameter will return a complete security
1855  *                  descriptor with name:value pairs separated by tabs,
1856  *                  commas, or newlines (not spaces!).
1857  *
1858  *                  The plus sign ('+') indicates that SIDs should be mapped
1859  *                  to names.  Without the plus sign, SIDs are not mapped;
1860  *                  rather they are simply converted to a string format.
1861  *
1862  * @return          0 on success, < 0 on error with errno set:
1863  *                  - EINVAL The client library is not properly initialized
1864  *                  - ENOMEM No memory was available for internal needs
1865  *                  - EPERM  Permission was denied.
1866  *                  - ENOTSUP The referenced file system does not support
1867  *                            extended attributes
1868  *
1869  */
1870 int smbc_removexattr(const char *url,
1871                      const char *name);
1872
1873
1874 /**@ingroup attribute
1875  * Remove extended attributes for a file.  This is used for modifying a file's
1876  * security descriptor (i.e. owner, group, and access control list) The POSIX
1877  * function which this maps to would act on a symbolic link rather than acting
1878  * on what the symbolic link points to, but with no symbolic links in SMB file
1879  * systems, this function is functionally identical to smbc_removexattr().
1880  *
1881  * @param url       The smb url of the file or directory to remove the extended
1882  *                  attributes for.
1883  *
1884  * @param name      The name of an attribute to be removed.  Names are of
1885  *                  one of the following forms:
1886  *
1887  *                     system.nt_sec_desc.<attribute name>
1888  *                     system.nt_sec_desc.*
1889  *                     system.nt_sec_desc.*+
1890  *
1891  *                  where <attribute name> is one of:
1892  *
1893  *                     revision
1894  *                     owner
1895  *                     owner+
1896  *                     group
1897  *                     group+
1898  *                     acl:<name or sid>
1899  *                     acl+:<name or sid>
1900  *
1901  *                  In the forms "system.nt_sec_desc.*" and
1902  *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
1903  *                  literal, i.e. the string is provided exactly as shown, and
1904  *                  the value parameter will return a complete security
1905  *                  descriptor with name:value pairs separated by tabs,
1906  *                  commas, or newlines (not spaces!).
1907  *
1908  *                  The plus sign ('+') indicates that SIDs should be mapped
1909  *                  to names.  Without the plus sign, SIDs are not mapped;
1910  *                  rather they are simply converted to a string format.
1911  *
1912  * @return          0 on success, < 0 on error with errno set:
1913  *                  - EINVAL The client library is not properly initialized
1914  *                  - ENOMEM No memory was available for internal needs
1915  *                  - EPERM  Permission was denied.
1916  *                  - ENOTSUP The referenced file system does not support
1917  *                            extended attributes
1918  *
1919  */
1920 int smbc_lremovexattr(const char *url,
1921                       const char *name);
1922
1923
1924 /**@ingroup attribute
1925  * Remove extended attributes for a file.  This is used for modifying a file's
1926  * security descriptor (i.e. owner, group, and access control list)
1927  *
1928  * @param fd        A file descriptor associated with an open file (as
1929  *                  previously returned by smbc_open(), to get extended
1930  *                  attributes for.
1931  *
1932  * @param name      The name of an attribute to be removed.  Names are of
1933  *                  one of the following forms:
1934  *
1935  *                     system.nt_sec_desc.<attribute name>
1936  *                     system.nt_sec_desc.*
1937  *                     system.nt_sec_desc.*+
1938  *
1939  *                  where <attribute name> is one of:
1940  *
1941  *                     revision
1942  *                     owner
1943  *                     owner+
1944  *                     group
1945  *                     group+
1946  *                     acl:<name or sid>
1947  *                     acl+:<name or sid>
1948  *
1949  *                  In the forms "system.nt_sec_desc.*" and
1950  *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
1951  *                  literal, i.e. the string is provided exactly as shown, and
1952  *                  the value parameter will return a complete security
1953  *                  descriptor with name:value pairs separated by tabs,
1954  *                  commas, or newlines (not spaces!).
1955  *
1956  *                  The plus sign ('+') indicates that SIDs should be mapped
1957  *                  to names.  Without the plus sign, SIDs are not mapped;
1958  *                  rather they are simply converted to a string format.
1959  *
1960  * @return          0 on success, < 0 on error with errno set:
1961  *                  - EINVAL The client library is not properly initialized
1962  *                  - ENOMEM No memory was available for internal needs
1963  *                  - EPERM  Permission was denied.
1964  *                  - ENOTSUP The referenced file system does not support
1965  *                            extended attributes
1966  *
1967  */
1968 int smbc_fremovexattr(int fd,
1969                       const char *name);
1970
1971
1972 /**@ingroup attribute
1973  * List the supported extended attribute names associated with a file
1974  *
1975  * @param url       The smb url of the file or directory to list the extended
1976  *                  attributes for.
1977  *
1978  * @param list      A pointer to a buffer in which the list of attributes for
1979  *                  the specified file or directory will be placed (unless
1980  *                  size is zero).
1981  *
1982  * @param size      The size of the buffer pointed to by list.  This parameter
1983  *                  may also be zero, in which case the size of the buffer
1984  *                  required to hold all of the attribute names will be
1985  *                  returned, but nothing will be placed into the list buffer.
1986  *
1987  * @return          0 on success, < 0 on error with errno set:
1988  *                  - EINVAL The client library is not properly initialized
1989  *                  - ENOMEM No memory was available for internal needs
1990  *                  - EPERM  Permission was denied.
1991  *                  - ENOTSUP The referenced file system does not support
1992  *                            extended attributes
1993  *
1994  * @note            This function always returns all attribute names supported
1995  *                  by NT file systems, regardless of whether the referenced
1996  *                  file system supports extended attributes (e.g. a Windows
1997  *                  2000 machine supports extended attributes if NTFS is used,
1998  *                  but not if FAT is used, and Windows 98 doesn't support
1999  *                  extended attributes at all.  Whether this is a feature or
2000  *                  a bug is yet to be decided.
2001  */
2002 int smbc_listxattr(const char *url,
2003                    char *list,
2004                    size_t size);
2005
2006 /**@ingroup attribute
2007  * List the supported extended attribute names associated with a file The
2008  * POSIX function which this maps to would act on a symbolic link rather than
2009  * acting on what the symbolic link points to, but with no symbolic links in
2010  * SMB file systems, this function is functionally identical to
2011  * smbc_listxattr().
2012  *
2013  * @param url       The smb url of the file or directory to list the extended
2014  *                  attributes for.
2015  *
2016  * @param list      A pointer to a buffer in which the list of attributes for
2017  *                  the specified file or directory will be placed (unless
2018  *                  size is zero).
2019  *
2020  * @param size      The size of the buffer pointed to by list.  This parameter
2021  *                  may also be zero, in which case the size of the buffer
2022  *                  required to hold all of the attribute names will be
2023  *                  returned, but nothing will be placed into the list buffer.
2024  *
2025  * @return          0 on success, < 0 on error with errno set:
2026  *                  - EINVAL The client library is not properly initialized
2027  *                  - ENOMEM No memory was available for internal needs
2028  *                  - EPERM  Permission was denied.
2029  *                  - ENOTSUP The referenced file system does not support
2030  *                            extended attributes
2031  *
2032  * @note            This function always returns all attribute names supported
2033  *                  by NT file systems, regardless of wether the referenced
2034  *                  file system supports extended attributes (e.g. a Windows
2035  *                  2000 machine supports extended attributes if NTFS is used,
2036  *                  but not if FAT is used, and Windows 98 doesn't support
2037  *                  extended attributes at all.  Whether this is a feature or
2038  *                  a bug is yet to be decided.
2039  */
2040 int smbc_llistxattr(const char *url,
2041                     char *list,
2042                     size_t size);
2043
2044 /**@ingroup attribute
2045  * List the supported extended attribute names associated with a file
2046  *
2047  * @param fd        A file descriptor associated with an open file (as
2048  *                  previously returned by smbc_open(), to get extended
2049  *                  attributes for.
2050  *
2051  * @param list      A pointer to a buffer in which the list of attributes for
2052  *                  the specified file or directory will be placed (unless
2053  *                  size is zero).
2054  *
2055  * @param size      The size of the buffer pointed to by list.  This parameter
2056  *                  may also be zero, in which case the size of the buffer
2057  *                  required to hold all of the attribute names will be
2058  *                  returned, but nothing will be placed into the list buffer.
2059  *
2060  * @return          0 on success, < 0 on error with errno set:
2061  *                  - EINVAL The client library is not properly initialized
2062  *                  - ENOMEM No memory was available for internal needs
2063  *                  - EPERM  Permission was denied.
2064  *                  - ENOTSUP The referenced file system does not support
2065  *                            extended attributes
2066  *
2067  * @note            This function always returns all attribute names supported
2068  *                  by NT file systems, regardless of wether the referenced
2069  *                  file system supports extended attributes (e.g. a Windows
2070  *                  2000 machine supports extended attributes if NTFS is used,
2071  *                  but not if FAT is used, and Windows 98 doesn't support
2072  *                  extended attributes at all.  Whether this is a feature or
2073  *                  a bug is yet to be decided.
2074  */
2075 int smbc_flistxattr(int fd,
2076                     char *list,
2077                     size_t size);
2078
2079 /**@ingroup print
2080  * Print a file given the name in fname. It would be a URL ...
2081  *
2082  * @param fname     The URL of a file on a remote SMB server that the
2083  *                  caller wants printed
2084  *
2085  * @param printq    The URL of the print share to print the file to.
2086  *
2087  * @return          0 on success, < 0 on error with errno set:
2088  *
2089  *                  - EINVAL fname or printq was NULL or smbc_init not
2090  *                    not called.
2091  *                  and errors returned by smbc_open
2092  *
2093  */
2094 int smbc_print_file(const char *fname, const char *printq);
2095
2096 /**@ingroup print
2097  * Open a print file that can be written to by other calls. This simply
2098  * does an smbc_open call after checking if there is a file name on the
2099  * URI. If not, a temporary name is added ...
2100  *
2101  * @param fname     The URL of the print share to print to?
2102  *
2103  * @returns         A file handle for the print file if successful.
2104  *                  Returns -1 if an error ocurred and errno has the values
2105  *                  - EINVAL fname was NULL or smbc_init not called.
2106  *                  - all errors returned by smbc_open
2107  *
2108  */
2109 int smbc_open_print_job(const char *fname);
2110
2111 /**@ingroup print
2112  * List the print jobs on a print share, for the moment, pass a callback
2113  *
2114  * @param purl      The url of the print share to list the jobs of
2115  *
2116  * @param fn        Callback function the receives printjob info
2117  *
2118  * @return          0 on success, < 0 on error with errno set:
2119  *                  - EINVAL fname was NULL or smbc_init not called
2120  *                  - EACCES ???
2121  */
2122 int smbc_list_print_jobs(const char *purl, smbc_list_print_job_fn fn);
2123
2124 /**@ingroup print
2125  * Delete a print job
2126  *
2127  * @param purl      Url of the print share
2128  *
2129  * @param id        The id of the job to delete
2130  *
2131  * @return          0 on success, < 0 on error with errno set:
2132  *                  - EINVAL fname was NULL or smbc_init not called
2133  *
2134  * @todo    what errno values are possible here?
2135  */
2136 int smbc_unlink_print_job(const char *purl, int id);
2137
2138 /**@ingroup callback
2139  * Remove a server from the cached server list it's unused.
2140  *
2141  * @param context    pointer to smb context
2142  *
2143  * @param srv        pointer to server to remove
2144  *
2145  * @return On success, 0 is returned. 1 is returned if the server could not
2146  *         be removed. Also useable outside libsmbclient.
2147  */
2148 int smbc_remove_unused_server(SMBCCTX * context, SMBCSRV * srv);
2149
2150 #ifdef __cplusplus
2151 }
2152 #endif
2153
2154 /**@ingroup directory
2155  * Convert strings of %xx to their single character equivalent.
2156  *
2157  * @param dest      A pointer to a buffer in which the resulting decoded
2158  *                  string should be placed.  This may be a pointer to the
2159  *                  same buffer as src_segment.
2160  *
2161  * @param src       A pointer to the buffer containing the URL to be decoded.
2162  *                  Any %xx sequences herein are converted to their single
2163  *                  character equivalent.  Each 'x' must be a valid hexadecimal
2164  *                  digit, or that % sequence is left undecoded.
2165  *
2166  * @param max_dest_len
2167  *                  The size of the buffer pointed to by dest_segment.
2168  *
2169  * @return          The number of % sequences which could not be converted
2170  *                  due to lack of two following hexadecimal digits.
2171  */
2172 #ifdef __cplusplus
2173 extern "C" {
2174 #endif
2175 int
2176 smbc_urldecode(char *dest, char * src, size_t max_dest_len);
2177 #ifdef __cplusplus
2178 }
2179 #endif
2180
2181
2182 /*
2183  * Convert any characters not specifically allowed in a URL into their %xx
2184  * equivalent.
2185  *
2186  * @param dest      A pointer to a buffer in which the resulting encoded
2187  *                  string should be placed.  Unlike smbc_urldecode(), this
2188  *                  must be a buffer unique from src.
2189  *
2190  * @param src       A pointer to the buffer containing the string to be encoded.
2191  *                  Any character not specifically allowed in a URL is converted
2192  *                  into its hexadecimal value and encoded as %xx.
2193  *
2194  * @param max_dest_len
2195  *                  The size of the buffer pointed to by dest_segment.
2196  *
2197  * @returns         The remaining buffer length.
2198  */
2199 #ifdef __cplusplus
2200 extern "C" {
2201 #endif
2202 int
2203 smbc_urlencode(char * dest, char * src, int max_dest_len);
2204 #ifdef __cplusplus
2205 }
2206 #endif
2207
2208
2209 /**@ingroup directory
2210  * Return the version of the linked Samba code, and thus the version of the
2211  * libsmbclient code.
2212  *
2213  * @return          The version string.
2214  */
2215 #ifdef __cplusplus
2216 extern "C" {
2217 #endif
2218 const char *
2219 smbc_version(void);
2220 #ifdef __cplusplus
2221 }
2222 #endif
2223
2224
2225 #endif /* SMBCLIENT_H_INCLUDED */