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