source/include/libsmbclient.h

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