source3/include/libsmbclient.h

   1 /*=====================================================================
   2   Unix SMB/Netbios implementation.
   3   SMB client library API definitions
   4   Copyright (C) Andrew Tridgell 1998
   5   Copyright (C) Richard Sharpe 2000
   6   Copyright (C) John Terpsra 2000
   7   Copyright (C) Tom Jansen (Ninja ISD) 2002
   8
   9
  10   This program is free software; you can redistribute it and/or modify
  11   it under the terms of the GNU General Public License as published by
  12   the Free Software Foundation; either version 2 of the License, or
  13   (at your option) any later version.
  14
  15   This program is distributed in the hope that it will be useful,
  16   but WITHOUT ANY WARRANTY; without even the implied warranty of
  17   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18   GNU General Public License for more details.
  19
  20   You should have received a copy of the GNU General Public License
  21   along with this program; if not, write to the Free Software
  22   Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  23   =====================================================================*/
  24
  25 #ifndef SMBCLIENT_H_INCLUDED
  26 #define SMBCLIENT_H_INCLUDED
  27
  28 /*-------------------------------------------------------------------*/
  29 /* The following are special comments to instruct DOXYGEN (automated
  30  * documentation tool:
  31 */
  32 /** \defgroup libsmbclient
  33 */
  34 /** \defgroup structure Data Structures Type and Constants
  35 *   \ingroup libsmbclient
  36 *   Data structures, types, and constants
  37 */
  38 /** \defgroup callback Callback function types
  39 *   \ingroup libsmbclient
  40 *   Callback functions
  41 */
  42 /** \defgroup file File Functions
  43 *   \ingroup libsmbclient
  44 *   Functions used to access individual file contents
  45 */
  46 /** \defgroup directory Directory Functions
  47 *   \ingroup libsmbclient
  48 *   Functions used to access directory entries
  49 */
  50 /** \defgroup attribute Attributes Functions
  51 *   \ingroup libsmbclient
  52 *   Functions used to view or change file and directory attributes
  53 */
  54 /** \defgroup print Print Functions
  55 *   \ingroup libsmbclient
  56 *   Functions used to access printing functionality
  57 */
  58 /** \defgroup misc Miscellaneous Functions
  59 *   \ingroup libsmbclient
  60 *   Functions that don't fit in to other categories
  61 */
  62 /*-------------------------------------------------------------------*/
  63
  64 /* Make sure we have the following includes for now ... */
  65 #include <sys/types.h>
  66 #include <sys/stat.h>
  67 #include <fcntl.h>
  68
  69 #define SMBC_WORKGROUP      1
  70 #define SMBC_SERVER         2
  71 #define SMBC_FILE_SHARE     3
  72 #define SMBC_PRINTER_SHARE  4
  73 #define SMBC_COMMS_SHARE    5
  74 #define SMBC_IPC_SHARE      6
  75 #define SMBC_DIR            7
  76 #define SMBC_FILE           8
  77 #define SMBC_LINK           9
  78
  79 /**@ingroup structure
  80  * Structure that represents a directory entry.
  81  *
  82  */
  83 struct smbc_dirent
  84 {
  85         /** Type of entity.
  86             SMBC_WORKGROUP=1,
  87             SMBC_SERVER=2,
  88             SMBC_FILE_SHARE=3,
  89             SMBC_PRINTER_SHARE=4,
  90             SMBC_COMMS_SHARE=5,
  91             SMBC_IPC_SHARE=6,
  92             SMBC_DIR=7,
  93             SMBC_FILE=8,
  94             SMBC_LINK=9,*/
  95         unsigned int smbc_type;
  96
  97         /** Length of this smbc_dirent in bytes
  98          */
  99         unsigned int dirlen;
 100         /** The length of the comment string in bytes (includes null
 101          *  terminator)
 102          */
 103         unsigned int commentlen;
 104         /** Points to the null terminated comment string
 105          */
 106         char *comment;
 107         /** The length of the name string in bytes (includes null
 108          *  terminator)
 109          */
 110         unsigned int namelen;
 111         /** Points to the null terminated name string
 112          */
 113         char name[1];
 114 };
 115
 116
 117 /**@ingroup structure
 118  * Structure that represents a print job.
 119  *
 120  */
 121 #ifndef _CLIENT_H
 122 struct print_job_info
 123 {
 124         /** numeric ID of the print job
 125          */
 126         unsigned short id;
 127
 128         /** represents print job priority (lower numbers mean higher priority)
 129          */
 130         unsigned short priority;
 131
 132         /** Size of the print job
 133          */
 134         size_t size;
 135
 136         /** Name of the user that owns the print job
 137          */
 138         char user[128];
 139
 140         /** Name of the print job. This will have no name if an anonymous print
 141          *  file was opened. Ie smb://server/printer
 142          */
 143         char name[128];
 144
 145         /** Time the print job was spooled
 146          */
 147         time_t t;
 148 };
 149 #endif /* _CLIENT_H */
 150
 151
 152 /**@ingroup structure
 153  * Server handle
 154  */
 155 typedef struct _SMBCSRV  SMBCSRV;
 156
 157 /**@ingroup structure
 158  * File or directory handle
 159  */
 160 typedef struct _SMBCFILE SMBCFILE;
 161
 162 /**@ingroup structure
 163  * File or directory handle
 164  */
 165 typedef struct _SMBCCTX SMBCCTX;
 166
 167
 168
 169
 170
 171 /**@ingroup callback
 172  * Authentication callback function type.
 173  *
 174  * Type for the the authentication function called by the library to
 175  * obtain authentication credentals
 176  *
 177  * @param srv       Server being authenticated to
 178  *
 179  * @param shr       Share being authenticated to
 180  *
 181  * @param wg        Pointer to buffer containing a "hint" for the
 182  *                  workgroup to be authenticated.  Should be filled in
 183  *                  with the correct workgroup if the hint is wrong.
 184  *
 185  * @param wglen     The size of the workgroup buffer in bytes
 186  *
 187  * @param un        Pointer to buffer containing a "hint" for the
 188  *                  user name to be use for authentication. Should be
 189  *                  filled in with the correct workgroup if the hint is
 190  *                  wrong.
 191  *
 192  * @param unlen     The size of the username buffer in bytes
 193  *
 194  * @param pw        Pointer to buffer containing to which password
 195  *                  copied
 196  *
 197  * @param pwlen     The size of the password buffer in bytes
 198  *
 199  */
 200 typedef void (*smbc_get_auth_data_fn)(const char *srv,
 201                                       const char *shr,
 202                                       char *wg, int wglen,
 203                                       char *un, int unlen,
 204                                       char *pw, int pwlen);
 205
 206
 207 /**@ingroup callback
 208  * Print job info callback function type.
 209  *
 210  * @param i         pointer to print job information structure
 211  *
 212  */
 213 typedef void (*smbc_list_print_job_fn)(struct print_job_info *i);
 214
 215
 216 /**@ingroup callback
 217  * Check if a server is still good
 218  *
 219  * @param c         pointer to smb context
 220  *
 221  * @param srv       pointer to server to check
 222  *
 223  * @return          0 when connection is good. 1 on error.
 224  *
 225  */
 226 typedef int (*smbc_check_server_fn)(SMBCCTX * c, SMBCSRV *srv);
 227
 228 /**@ingroup callback
 229  * Remove a server if unused
 230  *
 231  * @param c         pointer to smb context
 232  *
 233  * @param srv       pointer to server to remove
 234  *
 235  * @return          0 on success. 1 on failure.
 236  *
 237  */
 238 typedef int (*smbc_remove_unused_server_fn)(SMBCCTX * c, SMBCSRV *srv);
 239
 240
 241 /**@ingroup callback
 242  * Add a server to the cache system
 243  *
 244  * @param c         pointer to smb context
 245  *
 246  * @param srv       pointer to server to add
 247  *
 248  * @param server    server name
 249  *
 250  * @param share     share name
 251  *
 252  * @param workgroup workgroup used to connect
 253  *
 254  * @param username  username used to connect
 255  *
 256  * @return          0 on success. 1 on failure.
 257  *
 258  */
 259 typedef int (*smbc_add_cached_srv_fn)   (SMBCCTX * c, SMBCSRV *srv,
 260                                     const char * server, const char * share,
 261                                     const char * workgroup, const char * username);
 262
 263
 264 /**@ingroup callback
 265  * Look up a server in the cache system
 266  *
 267  * @param c         pointer to smb context
 268  *
 269  * @param server    server name to match
 270  *
 271  * @param share     share name to match
 272  *
 273  * @param workgroup workgroup to match
 274  *
 275  * @param username  username to match
 276  *
 277  * @return          pointer to SMBCSRV on success. NULL on failure.
 278  *
 279  */
 280 typedef SMBCSRV * (*smbc_get_cached_srv_fn)  (SMBCCTX * c, const char * server,
 281                                                const char * share, const char * workgroup,
 282                                                    const char * username);
 283
 284
 285 /**@ingroup callback
 286  * Check if a server is still good
 287  *
 288  * @param c         pointer to smb context
 289  *
 290  * @param srv       pointer to server to remove
 291  *
 292  * @return          0 when found and removed. 1 on failure.
 293  *
 294  */
 295 typedef int (*smbc_remove_cached_srv_fn)(SMBCCTX * c, SMBCSRV *srv);
 296
 297
 298 /**@ingroup callback
 299  * Try to remove all servers from the cache system and disconnect
 300  *
 301  * @param c         pointer to smb context
 302  *
 303  * @return          0 when found and removed. 1 on failure.
 304  *
 305  */
 306 typedef int (*smbc_purge_cached_fn)     (SMBCCTX * c);
 307
 308
 309
 310
 311 /**@ingroup structure
 312  * Structure that contains a client context information
 313  * This structure is know as SMBCCTX
 314  */
 315 struct _SMBCCTX {
 316         /** debug level
 317          */
 318         int     debug;
 319
 320         /** netbios name used for making connections
 321          */
 322         char * netbios_name;
 323
 324         /** workgroup name used for making connections
 325          */
 326         char * workgroup;
 327
 328         /** username used for making connections
 329          */
 330         char * user;
 331
 332         /** timeout used for waiting on connections / response data (in milliseconds)
 333          */
 334         int timeout;
 335
 336         /** callable functions for files:
 337          * For usage and return values see the smbc_* functions
 338          */
 339         SMBCFILE * (*open)    (SMBCCTX *c, const char *fname, int flags, mode_t mode);
 340         SMBCFILE * (*creat)   (SMBCCTX *c, const char *path, mode_t mode);
 341         ssize_t    (*read)    (SMBCCTX *c, SMBCFILE *file, void *buf, size_t count);
 342         ssize_t    (*write)   (SMBCCTX *c, SMBCFILE *file, void *buf, size_t count);
 343         int        (*unlink)  (SMBCCTX *c, const char *fname);
 344         int        (*rename)  (SMBCCTX *ocontext, const char *oname,
 345                                SMBCCTX *ncontext, const char *nname);
 346         off_t      (*lseek)   (SMBCCTX *c, SMBCFILE * file, off_t offset, int whence);
 347         int        (*stat)    (SMBCCTX *c, const char *fname, struct stat *st);
 348         int        (*fstat)   (SMBCCTX *c, SMBCFILE *file, struct stat *st);
 349         int        (*close)   (SMBCCTX *c, SMBCFILE *file);
 350
 351         /** callable functions for dirs
 352          */
 353         SMBCFILE * (*opendir) (SMBCCTX *c, const char *fname);
 354         int        (*closedir)(SMBCCTX *c, SMBCFILE *dir);
 355         struct smbc_dirent * (*readdir)(SMBCCTX *c, SMBCFILE *dir);
 356         int        (*getdents)(SMBCCTX *c, SMBCFILE *dir,
 357                                struct smbc_dirent *dirp, int count);
 358         int        (*mkdir)   (SMBCCTX *c, const char *fname, mode_t mode);
 359         int        (*rmdir)   (SMBCCTX *c, const char *fname);
 360         off_t      (*telldir) (SMBCCTX *c, SMBCFILE *dir);
 361         int        (*lseekdir)(SMBCCTX *c, SMBCFILE *dir, off_t offset);
 362         int        (*fstatdir)(SMBCCTX *c, SMBCFILE *dir, struct stat *st);
 363
 364         /** callable functions for printing
 365          */
 366         int        (*print_file)(SMBCCTX *c_file, const char *fname,
 367                                  SMBCCTX *c_print, const char *printq);
 368         SMBCFILE * (*open_print_job)(SMBCCTX *c, const char *fname);
 369         int        (*list_print_jobs)(SMBCCTX *c, const char *fname, smbc_list_print_job_fn fn);
 370         int        (*unlink_print_job)(SMBCCTX *c, const char *fname, int id);
 371
 372
 373         /** Callbacks
 374          * These callbacks _always_ have to be initialized because they will not be checked
 375          * at dereference for increased speed.
 376          */
 377         struct _smbc_callbacks {
 378                 /** authentication function callback: called upon auth requests
 379                  */
 380                 smbc_get_auth_data_fn auth_fn;
 381
 382                 /** check if a server is still good
 383                  */
 384                 smbc_check_server_fn check_server_fn;
 385
 386                 /** remove a server if unused
 387                  */
 388                 smbc_remove_unused_server_fn remove_unused_server_fn;
 389
 390                 /** Cache subsystem
 391                  * For an example cache system see samba/source/libsmb/libsmb_cache.c
 392                  * Cache subsystem functions follow.
 393                  */
 394
 395                 /** server cache addition
 396                  */
 397                 smbc_add_cached_srv_fn add_cached_srv_fn;
 398
 399                 /** server cache lookup
 400                  */
 401                 smbc_get_cached_srv_fn get_cached_srv_fn;
 402
 403                 /** server cache removal
 404                  */
 405                 smbc_remove_cached_srv_fn remove_cached_srv_fn;
 406
 407                 /** server cache purging, try to remove all cached servers (disconnect)
 408                  */
 409                 smbc_purge_cached_fn purge_cached_fn;
 410         } callbacks;
 411
 412
 413         /** Space to store private data of the server cache.
 414          */
 415         struct smbc_server_cache * server_cache;
 416
 417         /** INTERNAL DATA
 418          * do _NOT_ touch this from your program !
 419          */
 420         struct smbc_internal_data * internal;
 421
 422 };
 423
 424
 425 /**@ingroup misc
 426  * Create a new SBMCCTX (a context).
 427  *
 428  * Must be called before the context is passed to smbc_context_init()
 429  *
 430  * @return          The given SMBCCTX pointer on success, NULL on error with errno set:
 431  *                  - ENOMEM Out of memory
 432  *
 433  * @see             smbc_free_context(), smbc_init_context()
 434  *
 435  * @note            Do not forget to smbc_init_context() the returned SMBCCTX pointer !
 436  */
 437 SMBCCTX * smbc_new_context(void);
 438
 439 /**@ingroup misc
 440  * Delete a SBMCCTX (a context) acquired from smbc_new_context().
 441  *
 442  * The context will be deleted if possible.
 443  *
 444  * @param context   A pointer to a SMBCCTX obtained from smbc_new_context()
 445  *
 446  * @param shutdown_ctx   If 1, all connections and files will be closed even if they are busy.
 447  *
 448  *
 449  * @return          Returns 0 on succes. Returns 1 on failure with errno set:
 450  *                  - EBUSY Server connections are still used, Files are open or cache
 451  *                          could not be purged
 452  *                  - EBADF context == NULL
 453  *
 454  * @see             smbc_new_context()
 455  *
 456  * @note            It is advised to clean up all the contexts with shutdown_ctx set to 1
 457  *                  just before exit()'ing. When shutdown_ctx is 0, this function can be
 458  *                  use in periodical cleanup functions for example.
 459  */
 460 int smbc_free_context(SMBCCTX * context, int shutdown_ctx);
 461
 462
 463 /**@ingroup misc
 464  * Initialize a SBMCCTX (a context).
 465  *
 466  * Must be called before using any SMBCCTX API function
 467  *
 468  * @param context   A pointer to a SMBCCTX obtained from smbc_new_context()
 469  *
 470  * @return          A pointer to the given SMBCCTX on success, NULL on error with errno set:
 471  *                  - EBADF  NULL context given
 472  *                  - ENOMEM Out of memory
 473  *                  - ENOENT The smb.conf file would not load
 474  *
 475  * @see             smbc_new_context()
 476  *
 477  * @note            my_context = smbc_init_context(smbc_new_context()) is perfectly safe,
 478  *                  but it might leak memory on smbc_context_init() failure. Avoid this.
 479  *                  You'll have to call smbc_free_context() yourself on failure.
 480  */
 481
 482 SMBCCTX * smbc_init_context(SMBCCTX * context);
 483
 484 /**@ingroup misc
 485  * Initialize the samba client library.
 486  *
 487  * Must be called before using any of the smbclient API function
 488  *
 489  * @param fn        The function that will be called to obtaion
 490  *                  authentication credentials.
 491  *
 492  * @param debug     Allows caller to set the debug level. Can be
 493  *                  changed in smb.conf file. Allows caller to set
 494  *                  debugging if no smb.conf.
 495  *
 496  * @return          0 on success, < 0 on error with errno set:
 497  *                  - ENOMEM Out of memory
 498  *                  - ENOENT The smb.conf file would not load
 499  *
 500  */
 501
 502 int smbc_init(smbc_get_auth_data_fn fn, int debug);
 503
 504 /**@ingroup file
 505  * Open a file on an SMB server.
 506  *
 507  * @param furl      The smb url of the file to be opened.
 508  *
 509  * @param flags     Is one of O_RDONLY, O_WRONLY or O_RDWR which
 510  *                  request opening  the  file  read-only,write-only
 511  *                  or read/write. flags may also be bitwise-or'd with
 512  *                  one or  more of  the following:
 513  *                  O_CREAT - If the file does not exist it will be
 514  *                  created.
 515  *                  O_EXCL - When  used with O_CREAT, if the file
 516  *                  already exists it is an error and the open will
 517  *                  fail.
 518  *                  O_TRUNC - If the file already exists it will be
 519  *                  truncated.
 520  *                  O_APPEND The  file  is  opened  in  append mode
 521  *
 522  * @param mode      mode specifies the permissions to use if a new
 523  *                  file is created.  It  is  modified  by  the
 524  *                  process's umask in the usual way: the permissions
 525  *                  of the created file are (mode & ~umask)
 526  *
 527  *                  Not currently use, but there for future use.
 528  *                  We will map this to SYSTEM, HIDDEN, etc bits
 529  *                  that reverses the mapping that smbc_fstat does.
 530  *
 531  * @return          Valid file handle, < 0 on error with errno set:
 532  *                  - ENOMEM  Out of memory
 533  *                  - EINVAL if an invalid parameter passed, like no
 534  *                  file, or smbc_init not called.
 535  *                  - EEXIST  pathname already exists and O_CREAT and
 536  *                  O_EXCL were used.
 537  *                  - EISDIR  pathname  refers  to  a  directory  and
 538  *                  the access requested involved writing.
 539  *                  - EACCES  The requested access to the file is not
 540  *                  allowed
 541  *                  - ENODEV The requested share does not exist
 542  *                  - ENOTDIR A file on the path is not a directory
 543  *                  - ENOENT  A directory component in pathname does
 544  *                  not exist.
 545  *
 546  * @see             smbc_creat()
 547  *
 548  * @note            This call uses an underlying routine that may create
 549  *                  a new connection to the server specified in the URL.
 550  *                  If the credentials supplied in the URL, or via the
 551  *                  auth_fn in the smbc_init call, fail, this call will
 552  *                  try again with an empty username and password. This
 553  *                  often gets mapped to the guest account on some machines.
 554  */
 555
 556 int smbc_open(const char *furl, int flags, mode_t mode);
 557
 558 /**@ingroup file
 559  * Create a file on an SMB server.
 560  *
 561  * Same as calling smbc_open() with flags = O_CREAT|O_WRONLY|O_TRUNC
 562  *
 563  * @param furl      The smb url of the file to be created
 564  *
 565  * @param mode      mode specifies the permissions to use if  a  new
 566  *                  file is created.  It  is  modified  by  the
 567  *                  process's umask in the usual way: the permissions
 568  *                  of the created file are (mode & ~umask)
 569  *
 570  *                  NOTE, the above is not true. We are dealing with
 571  *                  an SMB server, which has no concept of a umask!
 572  *
 573  * @return          Valid file handle, < 0 on error with errno set:
 574  *                  - ENOMEM  Out of memory
 575  *                  - EINVAL if an invalid parameter passed, like no
 576  *                  file, or smbc_init not called.
 577  *                  - EEXIST  pathname already exists and O_CREAT and
 578  *                  O_EXCL were used.
 579  *                  - EISDIR  pathname  refers  to  a  directory  and
 580  *                  the access requested involved writing.
 581  *                  - EACCES  The requested access to the file is not
 582  *                  allowed
 583  *                  - ENOENT  A directory component in pathname does
 584  *                  not exist.
 585  *                  - ENODEV The requested share does not exist.
 586  * @see             smbc_open()
 587  *
 588  */
 589
 590 int smbc_creat(const char *furl, mode_t mode);
 591
 592 /**@ingroup file
 593  * Read from a file using an opened file handle.
 594  *
 595  * @param fd        Open file handle from smbc_open() or smbc_creat()
 596  *
 597  * @param buf       Pointer to buffer to recieve read data
 598  *
 599  * @param bufsize   Size of buf in bytes
 600  *
 601  * @return          Number of bytes read, < 0 on error with errno set:
 602  *                  - EISDIR fd refers to a directory
 603  *                  - EBADF  fd  is  not  a valid file descriptor or
 604  *                  is not open for reading.
 605  *                  - EINVAL fd is attached to an object which is
 606  *                  unsuitable for reading, or no buffer passed or
 607  *                  smbc_init not called.
 608  *
 609  * @see             smbc_open(), smbc_write()
 610  *
 611  */
 612 ssize_t smbc_read(int fd, void *buf, size_t bufsize);
 613
 614
 615 /**@ingroup file
 616  * Write to a file using an opened file handle.
 617  *
 618  * @param fd        Open file handle from smbc_open() or smbc_creat()
 619  *
 620  * @param buf       Pointer to buffer to recieve read data
 621  *
 622  * @param bufsize   Size of buf in bytes
 623  *
 624  * @return          Number of bytes written, < 0 on error with errno set:
 625  *                  - EISDIR fd refers to a directory.
 626  *                  - EBADF  fd  is  not  a valid file descriptor or
 627  *                  is not open for reading.
 628  *                  - EINVAL fd is attached to an object which is
 629  *                  unsuitable for reading, or no buffer passed or
 630  *                  smbc_init not called.
 631  *
 632  * @see             smbc_open(), smbc_read()
 633  *
 634  */
 635 ssize_t smbc_write(int fd, void *buf, size_t bufsize);
 636
 637
 638 /**@ingroup file
 639  * Seek to a specific location in a file.
 640  *
 641  * @param fd        Open file handle from smbc_open() or smbc_creat()
 642  *
 643  * @param offset    Offset in bytes from whence
 644  *
 645  * @param whence    A location in the file:
 646  *                  - SEEK_SET The offset is set to offset bytes from
 647  *                  the beginning of the file
 648  *                  - SEEK_CUR The offset is set to current location
 649  *                  plus offset bytes.
 650  *                  - SEEK_END The offset is set to the size of the
 651  *                  file plus offset bytes.
 652  *
 653  * @return          Upon successful completion, lseek returns the
 654  *                  resulting offset location as measured in bytes
 655  *                  from the beginning  of the file. Otherwise, a value
 656  *                  of (off_t)-1 is returned and errno is set to
 657  *                  indicate the error:
 658  *                  - EBADF  Fildes is not an open file descriptor.
 659  *                  - EINVAL Whence is not a proper value or smbc_init
 660  *                    not called.
 661  *
 662  * @todo Are all the whence values really supported?
 663  *
 664  * @todo Are errno values complete and correct?
 665  */
 666 off_t smbc_lseek(int fd, off_t offset, int whence);
 667
 668
 669 /**@ingroup file
 670  * Close an open file handle.
 671  *
 672  * @param fd        The file handle to close
 673  *
 674  * @return          0 on success, < 0 on error with errno set:
 675  *                  - EBADF  fd isn't a valid open file descriptor
 676  *                  - EINVAL smbc_init() failed or has not been called
 677  *
 678  * @see             smbc_open(), smbc_creat()
 679  */
 680 int smbc_close(int fd);
 681
 682
 683 /**@ingroup directory
 684  * Unlink (delete) a file or directory.
 685  *
 686  * @param furl      The smb url of the file to delete
 687  *
 688  * @return          0 on success, < 0 on error with errno set:
 689  *                  - EACCES or EPERM Write  access  to the directory
 690  *                  containing pathname is not allowed or one
 691  *                  of  the  directories in pathname did not allow
 692  *                  search (execute) permission
 693  *                  - ENOENT A directory component in pathname does
 694  *                  not exist
 695  *                  - EINVAL NULL was passed in the file param or
 696  *                    smbc_init not called.
 697  *                  - EACCES You do not have access to the file
 698  *                  - ENOMEM Insufficient kernel memory was available
 699  *
 700  * @see             smbc_rmdir()s
 701  *
 702  * @todo Are errno values complete and correct?
 703  */
 704 int smbc_unlink(const char *furl);
 705
 706
 707 /**@ingroup directory
 708  * Rename or move a file or directory.
 709  *
 710  * @param ourl      The original smb url (source url) of file or
 711  *                  directory to be moved
 712  *
 713  * @param nurl      The new smb url (destination url) of the file
 714  *                  or directory after the move.  Currently nurl must
 715  *                  be on the same share as ourl.
 716  *
 717  * @return          0 on success, < 0 on error with errno set:
 718  *                  - EISDIR nurl is an existing directory, but ourl is
 719  *                  not a directory.
 720  *                  - EEXIST nurl is  a  non-empty directory,
 721  *                  i.e., contains entries other than "." and ".."
 722  *                  - EINVAL The  new  url  contained  a path prefix
 723  *                  of the old, or, more generally, an  attempt was
 724  *                  made  to make a directory a subdirectory of itself
 725  *                  or smbc_init not called.
 726  *                  - ENOTDIR A component used as a directory in ourl
 727  *                  or nurl path is not, in fact, a directory.  Or,
 728  *                  ourl  is a directory, and newpath exists but is not
 729  *                  a directory.
 730  *                  - EACCES or EPERM Write access to the directory
 731  *                  containing ourl or nurl is not allowed for the
 732  *                  process's effective uid,  or  one of the
 733  *                  directories in ourl or nurl did not allow search
 734  *                  (execute) permission,  or ourl  was  a  directory
 735  *                  and did not allow write permission.
 736  *                  - ENOENT A  directory component in ourl or nurl
 737  *                  does not exist.
 738  *                  - EXDEV Rename across shares not supported.
 739  *                  - ENOMEM Insufficient kernel memory was available.
 740  *                  - EEXIST The target file, nurl, already exists.
 741  *
 742  *
 743  * @todo Are we going to support copying when urls are not on the same
 744  *       share?  I say no... NOTE. I agree for the moment.
 745  *
 746  */
 747 int smbc_rename(const char *ourl, const char *nurl);
 748
 749
 750 /**@ingroup directory
 751  * Open a directory used to obtain directory entries.
 752  *
 753  * @param durl      The smb url of the directory to open
 754  *
 755  * @return          Valid directory handle. < 0 on error with errno set:
 756  *                  - EACCES Permission denied.
 757  *                  - EINVAL A NULL file/URL was passed, or the URL would
 758  *                  not parse, or was of incorrect form or smbc_init not
 759  *                  called.
 760  *                  - ENOENT durl does not exist, or name is an
 761  *                  - ENOMEM Insufficient memory to complete the
 762  *                  operation.
 763  *                  - ENOTDIR name is not a directory.
 764  *                  - EPERM the workgroup could not be found.
 765  *                  - ENODEV the workgroup or server could not be found.
 766  *
 767  * @see             smbc_getdents(), smbc_readdir(), smbc_closedir()
 768  *
 769  */
 770 int smbc_opendir(const char *durl);
 771
 772
 773 /**@ingroup directory
 774  * Close a directory handle opened by smbc_opendir().
 775  *
 776  * @param dh        Directory handle to close
 777  *
 778  * @return          0 on success, < 0 on error with errno set:
 779  *                  - EBADF dh is an invalid directory handle
 780  *
 781  * @see             smbc_opendir()
 782  */
 783 int smbc_closedir(int dh);
 784
 785
 786 /**@ingroup directory
 787  * Get multiple directory entries.
 788  *
 789  * smbc_getdents() reads as many dirent structures from the an open
 790  * directory handle into a specified memory area as will fit.
 791  *
 792  * @param dh        Valid directory as returned by smbc_opendir()
 793  *
 794  * @param dirp      pointer to buffer that will receive the directory
 795  *                  entries.
 796  *
 797  * @param count     The size of the dirp buffer in bytes
 798  *
 799  * @returns         If any dirents returned, return will indicate the
 800  *                  total size. If there were no more dirents available,
 801  *                  0 is returned. < 0 indicates an error.
 802  *                  - EBADF  Invalid directory handle
 803  *                  - EINVAL Result buffer is too small or smbc_init
 804  *                  not called.
 805  *                  - ENOENT No such directory.
 806  * @see             , smbc_dirent, smbc_readdir(), smbc_open()
 807  *
 808  * @todo Are errno values complete and correct?
 809  *
 810  * @todo Add example code so people know how to parse buffers.
 811  */
 812 int smbc_getdents(unsigned int dh, struct smbc_dirent *dirp, int count);
 813
 814
 815 /**@ingroup directory
 816  * Get a single directory entry.
 817  *
 818  * @param dh        Valid directory as returned by smbc_opendir()
 819  *
 820  * @return          A pointer to a smbc_dirent structure, or NULL if an
 821  *                  error occurs or end-of-directory is reached:
 822  *                  - EBADF Invalid directory handle
 823  *                  - EINVAL smbc_init() failed or has not been called
 824  *
 825  * @see             smbc_dirent, smbc_getdents(), smbc_open()
 826  */
 827 struct smbc_dirent* smbc_readdir(unsigned int dh);
 828
 829
 830 /**@ingroup directory
 831  * Get the current directory offset.
 832  *
 833  * smbc_telldir() may be used in conjunction with smbc_readdir() and
 834  * smbc_lseekdir().
 835  *
 836  * @param dh        Valid directory as returned by smbc_opendir()
 837  *
 838  * @return          The current location in the directory stream or -1
 839  *                  if an error occur.  The current location is not
 840  *                  an offset. Becuase of the implementation, it is a
 841  *                  handle that allows the library to find the entry
 842  *                  later.
 843  *                  - EBADF dh is not a valid directory handle
 844  *                  - EINVAL smbc_init() failed or has not been called
 845  *                  - ENOTDIR if dh is not a directory
 846  *
 847  * @see             smbc_readdir()
 848  *
 849  */
 850 off_t smbc_telldir(int dh);
 851
 852
 853 /**@ingroup directory
 854  * lseek on directories.
 855  *
 856  * smbc_lseekdir() may be used in conjunction with smbc_readdir() and
 857  * smbc_telldir(). (rewind by smbc_lseekdir(fd, NULL))
 858  *
 859  * @param fd        Valid directory as returned by smbc_opendir()
 860  *
 861  * @param offset    The offset (as returned by smbc_telldir). Can be
 862  *                  NULL, in which case we will rewind
 863  *
 864  * @return          0 on success, -1 on failure
 865  *                  - EBADF dh is not a valid directory handle
 866  *                  - ENOTDIR if dh is not a directory
 867  *                  - EINVAL offset did not refer to a valid dirent or
 868  *                    smbc_init not called.
 869  *
 870  * @see             smbc_telldir()
 871  *
 872  *
 873  * @todo In what does the reture and errno values mean?
 874  */
 875 int smbc_lseekdir(int fd, off_t offset);
 876
 877 /**@ingroup directory
 878  * Create a directory.
 879  *
 880  * @param durl      The url of the directory to create
 881  *
 882  * @param mode      Specifies  the  permissions to use. It is modified
 883  *                  by the process's umask in the usual way: the
 884  *                  permissions of the created file are (mode & ~umask).
 885  *
 886  * @return          0 on success, < 0 on error with errno set:
 887  *                  - EEXIST directory url already exists
 888  *                  - EACCES The parent directory does not allow write
 889  *                  permission to the process, or one of the directories
 890  *                  - ENOENT A directory component in pathname does not
 891  *                  exist.
 892  *                  - EINVAL NULL durl passed or smbc_init not called.
 893  *                  - ENOMEM Insufficient memory was available.
 894  *
 895  * @see             smbc_rmdir()
 896  *
 897  */
 898 int smbc_mkdir(const char *durl, mode_t mode);
 899
 900
 901 /**@ingroup directory
 902  * Remove a directory.
 903  *
 904  * @param durl      The smb url of the directory to remove
 905  *
 906  * @return          0 on success, < 0 on error with errno set:
 907  *                  - EACCES or EPERM Write access to the directory
 908  *                  containing pathname was not allowed.
 909  *                  - EINVAL durl is NULL or smbc_init not called.
 910  *                  - ENOENT A directory component in pathname does not
 911  *                  exist.
 912  *                  - ENOTEMPTY directory contains entries.
 913  *                  - ENOMEM Insufficient kernel memory was available.
 914  *
 915  * @see             smbc_mkdir(), smbc_unlink()
 916  *
 917  * @todo Are errno values complete and correct?
 918  */
 919 int smbc_rmdir(const char *durl);
 920
 921
 922 /**@ingroup attribute
 923  * Get information about a file or directory.
 924  *
 925  * @param url       The smb url to get information for
 926  *
 927  * @param st        pointer to a buffer that will be filled with
 928  *                  standard Unix struct stat information.
 929  *
 930  * @return          0 on success, < 0 on error with errno set:
 931  *                  - ENOENT A component of the path file_name does not
 932  *                  exist.
 933  *                  - EINVAL a NULL url was passed or smbc_init not called.
 934  *                  - EACCES Permission denied.
 935  *                  - ENOMEM Out of memory
 936  *                  - ENOTDIR The target dir, url, is not a directory.
 937  *
 938  * @see             Unix stat()
 939  *
 940  */
 941 int smbc_stat(const char *url, struct stat *st);
 942
 943
 944 /**@ingroup attribute
 945  * Get file information via an file descriptor.
 946  *
 947  * @param fd        Open file handle from smbc_open() or smbc_creat()
 948  *
 949  * @param st        pointer to a buffer that will be filled with
 950  *                  standard Unix struct stat information.
 951  *
 952  * @return          EBADF  filedes is bad.
 953  *                  - EACCES Permission denied.
 954  *                  - EBADF fd is not a valid file descriptor
 955  *                  - EINVAL Problems occurred in the underlying routines
 956  *                    or smbc_init not called.
 957  *                  - ENOMEM Out of memory
 958  *
 959  * @see             smbc_stat(), Unix stat()
 960  *
 961  */
 962 int smbc_fstat(int fd, struct stat *st);
 963
 964
 965 /**@ingroup attribue
 966  * Change the ownership of a file or directory.
 967  *
 968  * @param url       The smb url of the file or directory to change
 969  *                  ownership of.
 970  *
 971  * @param owner     I have no idea?
 972  *
 973  * @param group     I have not idea?
 974  *
 975  * @return          0 on success, < 0 on error with errno set:
 976  *                  - EPERM  The effective UID does not match the owner
 977  *                  of the file, and is not zero; or the owner or group
 978  *                  were specified incorrectly.
 979  *                  - ENOENT The file does not exist.
 980  *                  - ENOMEM Insufficient was available.
 981  *                  - ENOENT file or directory does not exist
 982  *
 983  * @todo Are we actually going to be able to implement this function
 984  *
 985  * @todo How do we abstract owner and group uid and gid?
 986  *
 987  */
 988 int smbc_chown(const char *url, uid_t owner, gid_t group);
 989
 990
 991 /**@ingroup attribute
 992  * Change the permissions of a file.
 993  *
 994  * @param url       The smb url of the file or directory to change
 995  *                  permissions of
 996  *
 997  * @param mode      The permissions to set:
 998  *                  - Put good explaination of permissions here!
 999  *
1000  * @return          0 on success, < 0 on error with errno set:
1001  *                  - EPERM  The effective UID does not match the owner
1002  *                  of the file, and is not zero
1003  *                  - ENOENT The file does not exist.
1004  *                  - ENOMEM Insufficient was available.
1005  *                  - ENOENT file or directory does not exist
1006  *
1007  * @todo Actually implement this fuction?
1008  *
1009  * @todo Are errno values complete and correct?
1010  */
1011 int smbc_chmod(const char *url, mode_t mode);
1012
1013
1014 /**@ingroup print
1015  * Print a file given the name in fname. It would be a URL ...
1016  *
1017  * @param fname     The URL of a file on a remote SMB server that the
1018  *                  caller wants printed
1019  *
1020  * @param printq    The URL of the print share to print the file to.
1021  *
1022  * @return          0 on success, < 0 on error with errno set:
1023  *
1024  *                  - EINVAL fname or printq was NULL or smbc_init not
1025  *                    not called.
1026  *                  and errors returned by smbc_open
1027  *
1028  */
1029 int smbc_print_file(const char *fname, const char *printq);
1030
1031 /**@ingroup print
1032  * Open a print file that can be written to by other calls. This simply
1033  * does an smbc_open call after checking if there is a file name on the
1034  * URI. If not, a temporary name is added ...
1035  *
1036  * @param fname     The URL of the print share to print to?
1037  *
1038  * @returns         A file handle for the print file if successful.
1039  *                  Returns -1 if an error ocurred and errno has the values
1040  *                  - EINVAL fname was NULL or smbc_init not called.
1041  *                  - all errors returned by smbc_open
1042  *
1043  */
1044 int smbc_open_print_job(const char *fname);
1045
1046 /**@ingroup print
1047  * List the print jobs on a print share, for the moment, pass a callback
1048  *
1049  * @param purl      The url of the print share to list the jobs of
1050  *
1051  * @param fn        Callback function the receives printjob info
1052  *
1053  * @return          0 on success, < 0 on error with errno set:
1054  *                  - EINVAL fname was NULL or smbc_init not called
1055  *                  - EACCES ???
1056  */
1057 int smbc_list_print_jobs(const char *purl, smbc_list_print_job_fn fn);
1058
1059 /**@ingroup print
1060  * Delete a print job
1061  *
1062  * @param purl      Url of the print share
1063  *
1064  * @param id        The id of the job to delete
1065  *
1066  * @return          0 on success, < 0 on error with errno set:
1067  *                  - EINVAL fname was NULL or smbc_init not called
1068  *
1069  * @todo    what errno values are possible here?
1070  */
1071 int smbc_unlink_print_job(const char *purl, int id);
1072
1073
1074 #endif /* SMBCLIENT_H_INCLUDED */