source/include/libsmbclient.h

   1 /*=====================================================================
   2   Unix SMB/CIFS 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
   8   This program is free software; you can redistribute it and/or modify
   9   it under the terms of the GNU General Public License as published by
  10   the Free Software Foundation; either version 2 of the License, or
  11   (at your option) any later version.
  12
  13   This program is distributed in the hope that it will be useful,
  14   but WITHOUT ANY WARRANTY; without even the implied warranty of
  15   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16   GNU General Public License for more details.
  17
  18   You should have received a copy of the GNU General Public License
  19   along with this program; if not, write to the Free Software
  20   Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  21   =====================================================================*/
  22
  23 #ifndef SMBCLIENT_H_INCLUDED
  24 #define SMBCLIENT_H_INCLUDED
  25
  26 /*-------------------------------------------------------------------*/
  27 /* The following are special comments to instruct DOXYGEN (automated
  28  * documentation tool:
  29 */
  30 /** \defgroup libsmbclient
  31 */
  32 /** \defgroup structure Data Structures Type and Constants
  33 *   \ingroup libsmbclient
  34 *   Data structures, types, and constants
  35 */
  36 /** \defgroup file File Functions
  37 *   \ingroup libsmbclient
  38 *   Functions used to access individual file contents
  39 */
  40 /** \defgroup directory Directory Functions
  41 *   \ingroup libsmbclient
  42 *   Functions used to access directory entries
  43 */
  44 /** \defgroup attribute Attributes Functions
  45 *   \ingroup libsmbclient
  46 *   Functions used to view or change file and directory attributes
  47 */
  48 /** \defgroup print Print Functions
  49 *   \ingroup libsmbclient
  50 *   Functions used to access printing functionality
  51 */
  52 /** \defgroup attribute Miscellaneous Functions
  53 *   \ingroup libsmbclient
  54 *   Functions that don't fit in to other categories
  55 */
  56 /*-------------------------------------------------------------------*/
  57
  58 /* Make sure we have the following includes for now ... */
  59 #include <sys/types.h>
  60 #include <sys/stat.h>
  61 #include <fcntl.h>
  62
  63 #define SMBC_MAX_NAME       1023
  64 #define SMBC_WORKGROUP      1
  65 #define SMBC_SERVER         2
  66 #define SMBC_FILE_SHARE     3
  67 #define SMBC_PRINTER_SHARE  4
  68 #define SMBC_COMMS_SHARE    5
  69 #define SMBC_IPC_SHARE      6
  70 #define SMBC_DIR            7
  71 #define SMBC_FILE           8
  72 #define SMBC_LINK           9
  73
  74 #define SMBC_FILE_MODE (S_IFREG | 0444)
  75 #define SMBC_DIR_MODE  (S_IFDIR | 0555)
  76
  77 #define SMBC_MAX_FD         10000
  78
  79
  80 /**@ingroup structure
  81  * Structure that represents a directory entry.
  82  *
  83  */
  84 struct smbc_dirent
  85 {
  86         /** Type of entity.
  87             SMBC_WORKGROUP=1,
  88             SMBC_SERVER=2,
  89             SMBC_FILE_SHARE=3,
  90             SMBC_PRINTER_SHARE=4,
  91             SMBC_COMMS_SHARE=5,
  92             SMBC_IPC_SHARE=6,
  93             SMBC_DIR=7,
  94             SMBC_FILE=8,
  95             SMBC_LINK=9,*/
  96         uint smbc_type;
  97
  98         /** Length of this smbc_dirent in bytes
  99          */
 100         uint dirlen;
 101         /** The length of the comment string in bytes (includes null
 102          *  terminator)
 103          */
 104         uint commentlen;
 105         /** Points to the null terminated comment string
 106          */
 107         char *comment;
 108         /** The length of the name string in bytes (includes null
 109          *  terminator)
 110          */
 111         uint namelen;
 112         /** Points to the null terminated name string
 113          */
 114         char name[1];
 115 };
 116
 117
 118 #ifndef _CLIENT_H
 119 typedef unsigned short uint16;
 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         uint16 id;
 130
 131         /** represents print job priority (lower numbers mean higher priority)
 132          */
 133         uint16 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
 153
 154
 155 /**@ingroup structure
 156  * Authentication callback function type.
 157  *
 158  * Type for the the authentication function called by the library to
 159  * obtain authentication credentals
 160  *
 161  * @param srv       Server being authenticated to
 162  *
 163  * @param shr       Share being authenticated to
 164  *
 165  * @param wg        Pointer to buffer containing a "hint" for the
 166  *                  workgroup to be authenticated.  Should be filled in
 167  *                  with the correct workgroup if the hint is wrong.
 168  *
 169  * @param wglen     The size of the workgroup buffer in bytes
 170  *
 171  * @param un        Pointer to buffer containing a "hint" for the
 172  *                  user name to be use for authentication. Should be
 173  *                  filled in with the correct workgroup if the hint is
 174  *                  wrong.
 175  *
 176  * @param unlen     The size of the username buffer in bytes
 177  *
 178  * @param pw        Pointer to buffer containing to which password
 179  *                  copied
 180  *
 181  * @param pwlen     The size of the password buffer in bytes
 182  *
 183  */
 184 typedef void (*smbc_get_auth_data_fn)(const char *srv,
 185                                       const char *shr,
 186                                       char *wg, int wglen,
 187                                       char *un, int unlen,
 188                                       char *pw, int pwlen);
 189
 190
 191 /**@ingroup structure
 192  * Print job info callback function type.
 193  *
 194  * @param i         pointer to print job information structure
 195  *
 196  */
 197 typedef void (*smbc_get_print_job_info)(struct print_job_info *i);
 198
 199
 200 /**@ingroup misc
 201  * Initialize the samba client library.
 202  *
 203  * Must be called before using any of the smbclient API function
 204  *
 205  * @param fn        The function that will be called to obtaion
 206  *                  authentication credentials.
 207  *
 208  * @param debug     Allows caller to set the debug level. Can be
 209  *                  changed in smb.conf file. Allows caller to set
 210  *                  debugging if no smb.conf.
 211  *
 212  * @return          0 on success, < 0 on error with errno set:
 213  *                  - ENOMEM Out of memory
 214  *                  - ENOENT The smb.conf file would not load
 215  *
 216  */
 217 int smbc_init(smbc_get_auth_data_fn fn, int debug);
 218
 219
 220 /**@ingroup file
 221  * Open a file on an SMB server.
 222  *
 223  * @param furl      The smb url of the file to be opened.
 224  *
 225  * @param flags     Is one of O_RDONLY, O_WRONLY or O_RDWR which
 226  *                  request opening  the  file  read-only,write-only
 227  *                  or read/write. flags may also be bitwise-or'd with
 228  *                  one or  more of  the following:
 229  *                  O_CREAT - If the file does not exist it will be
 230  *                  created.
 231  *                  O_EXCL - When  used with O_CREAT, if the file
 232  *                  already exists it is an error and the open will
 233  *                  fail.
 234  *                  O_TRUNC - If the file already exists it will be
 235  *                  truncated.
 236  *                  O_APPEND The  file  is  opened  in  append mode
 237  *
 238  * @param mode      mode specifies the permissions to use if a new
 239  *                  file is created.  It  is  modified  by  the
 240  *                  process's umask in the usual way: the permissions
 241  *                  of the created file are (mode & ~umask)
 242  *
 243  *                  Not currently use, but there for future use.
 244  *                  We will map this to SYSTEM, HIDDEN, etc bits
 245  *                  that reverses the mapping that smbc_fstat does.
 246  *
 247  * @return          Valid file handle, < 0 on error with errno set:
 248  *                  - ENOMEM  Out of memory
 249  *                  - EINVAL if an invalid parameter passed, like no
 250  *                  file, or smbc_init not called.
 251  *                  - EEXIST  pathname already exists and O_CREAT and
 252  *                  O_EXCL were used.
 253  *                  - EISDIR  pathname  refers  to  a  directory  and
 254  *                  the access requested involved writing.
 255  *                  - EACCES  The requested access to the file is not
 256  *                  allowed
 257  *                  - ENODEV The requested share does not exist
 258  *                  - ENOTDIR A file on the path is not a directory
 259  *                  - ENOENT  A directory component in pathname does
 260  *                  not exist.
 261  *
 262  * @see             smbc_creat()
 263  *
 264  * @note            This call uses an underlying routine that may create
 265  *                  a new connection to the server specified in the URL.
 266  *                  If the credentials supplied in the URL, or via the
 267  *                  auth_fn in the smbc_init call, fail, this call will
 268  *                  try again with an empty username and password. This
 269  *                  often gets mapped to the guest account on some machines.
 270  */
 271 int smbc_open(const char *furl, int flags, mode_t mode);
 272
 273
 274 /**@ingroup file
 275  * Create a file on an SMB server.
 276  *
 277  * Same as calling smbc_open() with flags = O_CREAT|O_WRONLY|O_TRUNC
 278  *
 279  * @param furl      The smb url of the file to be created
 280  *
 281  * @param mode      mode specifies the permissions to use if  a  new
 282  *                  file is created.  It  is  modified  by  the
 283  *                  process's umask in the usual way: the permissions
 284  *                  of the created file are (mode & ~umask)
 285  *
 286  *                  NOTE, the above is not true. We are dealing with
 287  *                  an SMB server, which has no concept of a umask!
 288  *
 289  * @return          Valid file handle, < 0 on error with errno set:
 290  *                  - ENOMEM  Out of memory
 291  *                  - EINVAL if an invalid parameter passed, like no
 292  *                  file, or smbc_init not called.
 293  *                  - EEXIST  pathname already exists and O_CREAT and
 294  *                  O_EXCL were used.
 295  *                  - EISDIR  pathname  refers  to  a  directory  and
 296  *                  the access requested involved writing.
 297  *                  - EACCES  The requested access to the file is not
 298  *                  allowed
 299  *                  - ENOENT  A directory component in pathname does
 300  *                  not exist.
 301  *                  - ENODEV The requested share does not exist.
 302  * @see             smbc_open()
 303  *
 304  */
 305 int smbc_creat(const char *furl, mode_t mode);
 306
 307
 308 /**@ingroup file
 309  * Read from a file using an opened file handle.
 310  *
 311  * @param fd        Open file handle from smbc_open() or smbc_creat()
 312  *
 313  * @param buf       Pointer to buffer to recieve read data
 314  *
 315  * @param bufsize   Size of buf in bytes
 316  *
 317  * @return          Number of bytes read, < 0 on error with errno set:
 318  *                  - EISDIR fd refers to a directory
 319  *                  - EBADF  fd  is  not  a valid file descriptor or
 320  *                  is not open for reading.
 321  *                  - EINVAL fd is attached to an object which is
 322  *                  unsuitable for reading, or no buffer passed or
 323  *                  smbc_init not called.
 324  *
 325  * @see             smbc_open(), smbc_write()
 326  *
 327  */
 328 ssize_t smbc_read(int fd, void *buf, size_t bufsize);
 329
 330
 331 /**@ingroup file
 332  * Write to a file using an opened file handle.
 333  *
 334  * @param fd        Open file handle from smbc_open() or smbc_creat()
 335  *
 336  * @param buf       Pointer to buffer to recieve read data
 337  *
 338  * @param bufsize   Size of buf in bytes
 339  *
 340  * @return          Number of bytes written, < 0 on error with errno set:
 341  *                  - EISDIR fd refers to a directory.
 342  *                  - EBADF  fd  is  not  a valid file descriptor or
 343  *                  is not open for reading.
 344  *                  - EINVAL fd is attached to an object which is
 345  *                  unsuitable for reading, or no buffer passed or
 346  *                  smbc_init not called.
 347  *
 348  * @see             smbc_open(), smbc_read()
 349  *
 350  */
 351 ssize_t smbc_write(int fd, void *buf, size_t bufsize);
 352
 353
 354 /**@ingroup file
 355  * Seek to a specific location in a file.
 356  *
 357  * @param fd        Open file handle from smbc_open() or smbc_creat()
 358  *
 359  * @param offset    Offset in bytes from whence
 360  *
 361  * @param whence    A location in the file:
 362  *                  - SEEK_SET The offset is set to offset bytes from
 363  *                  the beginning of the file
 364  *                  - SEEK_CUR The offset is set to current location
 365  *                  plus offset bytes.
 366  *                  - SEEK_END The offset is set to the size of the
 367  *                  file plus offset bytes.
 368  *
 369  * @return          Upon successful completion, lseek returns the
 370  *                  resulting offset location as measured in bytes
 371  *                  from the beginning  of the file. Otherwise, a value
 372  *                  of (off_t)-1 is returned and errno is set to
 373  *                  indicate the error:
 374  *                  - EBADF  Fildes is not an open file descriptor.
 375  *                  - EINVAL Whence is not a proper value or smbc_init
 376  *                    not called.
 377  *
 378  * @todo Are all the whence values really supported?
 379  *
 380  * @todo Are errno values complete and correct?
 381  */
 382 off_t smbc_lseek(int fd, off_t offset, int whence);
 383
 384
 385 /**@ingroup file
 386  * Close an open file handle.
 387  *
 388  * @param fd        The file handle to close
 389  *
 390  * @return          0 on success, < 0 on error with errno set:
 391  *                  - EBADF  fd isn't a valid open file descriptor
 392  *                  - EINVAL smbc_init() failed or has not been called
 393  *
 394  * @see             smbc_open(), smbc_creat()
 395  */
 396 int smbc_close(int fd);
 397
 398
 399 /**@ingroup directory
 400  * Unlink (delete) a file or directory.
 401  *
 402  * @param furl      The smb url of the file to delete
 403  *
 404  * @return          0 on success, < 0 on error with errno set:
 405  *                  - EACCES or EPERM Write  access  to the directory
 406  *                  containing pathname is not allowed or one
 407  *                  of  the  directories in pathname did not allow
 408  *                  search (execute) permission
 409  *                  - ENOENT A directory component in pathname does
 410  *                  not exist
 411  *                  - EINVAL NULL was passed in the file param or
 412  *                    smbc_init not called.
 413  *                  - EACCES You do not have access to the file
 414  *                  - ENOMEM Insufficient kernel memory was available
 415  *
 416  * @see             smbc_rmdir()s
 417  *
 418  * @todo Are errno values complete and correct?
 419  */
 420 int smbc_unlink(const char *furl);
 421
 422
 423 /**@ingroup directory
 424  * Rename or move a file or directory.
 425  *
 426  * @param ourl      The original smb url (source url) of file or
 427  *                  directory to be moved
 428  *
 429  * @param nurl      The new smb url (destination url) of the file
 430  *                  or directory after the move.  Currently nurl must
 431  *                  be on the same share as ourl.
 432  *
 433  * @return          0 on success, < 0 on error with errno set:
 434  *                  - EISDIR nurl is an existing directory, but ourl is
 435  *                  not a directory.
 436  *                  - EEXIST nurl is  a  non-empty directory,
 437  *                  i.e., contains entries other than "." and ".."
 438  *                  - EINVAL The  new  url  contained  a path prefix
 439  *                  of the old, or, more generally, an  attempt was
 440  *                  made  to make a directory a subdirectory of itself
 441  *                  or smbc_init not called.
 442  *                  - ENOTDIR A component used as a directory in ourl
 443  *                  or nurl path is not, in fact, a directory.  Or,
 444  *                  ourl  is a directory, and newpath exists but is not
 445  *                  a directory.
 446  *                  - EACCES or EPERM Write access to the directory
 447  *                  containing ourl or nurl is not allowed for the
 448  *                  process's effective uid,  or  one of the
 449  *                  directories in ourl or nurl did not allow search
 450  *                  (execute) permission,  or ourl  was  a  directory
 451  *                  and did not allow write permission.
 452  *                  - ENOENT A  directory component in ourl or nurl
 453  *                  does not exist.
 454  *                  - EXDEV Rename across shares not supported.
 455  *                  - ENOMEM Insufficient kernel memory was available.
 456  *                  - EEXIST The target file, nurl, already exists.
 457  *
 458  *
 459  * @todo Are we going to support copying when urls are not on the same
 460  *       share?  I say no... NOTE. I agree for the moment.
 461  *
 462  */
 463 int smbc_rename(const char *ourl, const char *nurl);
 464
 465
 466 /**@ingroup directory
 467  * Open a directory used to obtain directory entries.
 468  *
 469  * @param durl      The smb url of the directory to open
 470  *
 471  * @return          Valid directory handle. < 0 on error with errno set:
 472  *                  - EACCES Permission denied.
 473  *                  - EINVAL A NULL file/URL was passed, or the URL would
 474  *                  not parse, or was of incorrect form or smbc_init not
 475  *                  called.
 476  *                  - ENOENT durl does not exist, or name is an
 477  *                  - ENOMEM Insufficient memory to complete the
 478  *                  operation.
 479  *                  - ENOTDIR name is not a directory.
 480  *                  - EPERM the workgroup could not be found.
 481  *                  - ENODEV the workgroup or server could not be found.
 482  *
 483  * @see             smbc_getdents(), smbc_readdir(), smbc_closedir()
 484  *
 485  */
 486 int smbc_opendir(const char *durl);
 487
 488
 489 /**@ingroup directory
 490  * Close a directory handle opened by smbc_opendir().
 491  *
 492  * @param dh        Directory handle to close
 493  *
 494  * @return          0 on success, < 0 on error with errno set:
 495  *                  - EBADF dh is an invalid directory handle
 496  *
 497  * @see             smbc_opendir()
 498  */
 499 int smbc_closedir(int dh);
 500
 501
 502 /**@ingroup directory
 503  * Get multiple directory entries.
 504  *
 505  * smbc_getdents() reads as many dirent structures from the an open
 506  * directory handle into a specified memory area as will fit.
 507  *
 508  * @param dh        Valid directory as returned by smbc_opendir()
 509  *
 510  * @param dirp      pointer to buffer that will receive the directory
 511  *                  entries.
 512  *
 513  * @param count     The size of the dirp buffer in bytes
 514  *
 515  * @returns         If any dirents returned, return will indicate the
 516  *                  total size. If there were no more dirents available,
 517  *                  0 is returned. < 0 indicates an error.
 518  *                  - EBADF  Invalid directory handle
 519  *                  - EINVAL Result buffer is too small or smbc_init
 520  *                  not called.
 521  *                  - ENOENT No such directory.
 522  * @see             , smbc_dirent, smbc_readdir(), smbc_open()
 523  *
 524  * @todo Are errno values complete and correct?
 525  *
 526  * @todo Add example code so people know how to parse buffers.
 527  */
 528 int smbc_getdents(unsigned int dh, struct smbc_dirent *dirp, int count);
 529
 530
 531 /**@ingroup directory
 532  * Get a single directory entry.
 533  *
 534  * @param dh        Valid directory as returned by smbc_opendir()
 535  *
 536  * @return          A pointer to a smbc_dirent structure, or NULL if an
 537  *                  error occurs or end-of-directory is reached:
 538  *                  - EBADF Invalid directory handle
 539  *                  - EINVAL smbc_init() failed or has not been called
 540  *
 541  * @see             smbc_dirent, smbc_getdents(), smbc_open()
 542  */
 543 struct smbc_dirent* smbc_readdir(unsigned int dh);
 544
 545
 546 /**@ingroup directory
 547  * Get the current directory offset.
 548  *
 549  * smbc_telldir() may be used in conjunction with smbc_readdir() and
 550  * smbc_lseekdir().
 551  *
 552  * @param dh        Valid directory as returned by smbc_opendir()
 553  *
 554  * @return          The current location in the directory stream or -1
 555  *                  if an error occur.  The current location is not
 556  *                  an offset. Becuase of the implementation, it is a
 557  *                  handle that allows the library to find the entry
 558  *                  later.
 559  *                  - EBADF dh is not a valid directory handle
 560  *                  - EINVAL smbc_init() failed or has not been called
 561  *                  - ENOTDIR if dh is not a directory
 562  *
 563  * @see             smbc_readdir()
 564  *
 565  */
 566 off_t smbc_telldir(int dh);
 567
 568
 569 /**@ingroup directory
 570  * lseek on directories.
 571  *
 572  * smbc_lseekdir() may be used in conjunction with smbc_readdir() and
 573  * smbc_telldir(). (rewind by smbc_lseekdir(fd, NULL))
 574  *
 575  * @param fd        Valid directory as returned by smbc_opendir()
 576  *
 577  * @param offset    The offset (as returned by smbc_telldir). Can be
 578  *                  NULL, in which case we will rewind
 579  *
 580  * @return          0 on success, -1 on failure
 581  *                  - EBADF dh is not a valid directory handle
 582  *                  - ENOTDIR if dh is not a directory
 583  *                  - EINVAL offset did not refer to a valid dirent or
 584  *                    smbc_init not called.
 585  *
 586  * @see             smbc_telldir()
 587  *
 588  *
 589  * @todo In what does the reture and errno values mean?
 590  */
 591 int smbc_lseekdir(int fd, off_t offset);
 592
 593 /**@ingroup directory
 594  * Create a directory.
 595  *
 596  * @param durl      The url of the directory to create
 597  *
 598  * @param mode      Specifies  the  permissions to use. It is modified
 599  *                  by the process's umask in the usual way: the
 600  *                  permissions of the created file are (mode & ~umask).
 601  *
 602  * @return          0 on success, < 0 on error with errno set:
 603  *                  - EEXIST directory url already exists
 604  *                  - EACCES The parent directory does not allow write
 605  *                  permission to the process, or one of the directories
 606  *                  - ENOENT A directory component in pathname does not
 607  *                  exist.
 608  *                  - EINVAL NULL durl passed or smbc_init not called.
 609  *                  - ENOMEM Insufficient memory was available.
 610  *
 611  * @see             smbc_rmdir()
 612  *
 613  */
 614 int smbc_mkdir(const char *durl, mode_t mode);
 615
 616
 617 /**@ingroup directory
 618  * Remove a directory.
 619  *
 620  * @param durl      The smb url of the directory to remove
 621  *
 622  * @return          0 on success, < 0 on error with errno set:
 623  *                  - EACCES or EPERM Write access to the directory
 624  *                  containing pathname was not allowed.
 625  *                  - EINVAL durl is NULL or smbc_init not called.
 626  *                  - ENOENT A directory component in pathname does not
 627  *                  exist.
 628  *                  - ENOTEMPTY directory contains entries.
 629  *                  - ENOMEM Insufficient kernel memory was available.
 630  *
 631  * @see             smbc_mkdir(), smbc_unlink()
 632  *
 633  * @todo Are errno values complete and correct?
 634  */
 635 int smbc_rmdir(const char *durl);
 636
 637
 638 /**@ingroup attribute
 639  * Get information about a file or directory.
 640  *
 641  * @param url       The smb url to get information for
 642  *
 643  * @param st        pointer to a buffer that will be filled with
 644  *                  standard Unix struct stat information.
 645  *
 646  * @return          0 on success, < 0 on error with errno set:
 647  *                  - ENOENT A component of the path file_name does not
 648  *                  exist.
 649  *                  - EINVAL a NULL url was passed or smbc_init not called.
 650  *                  - EACCES Permission denied.
 651  *                  - ENOMEM Out of memory
 652  *                  - ENOTDIR The target dir, url, is not a directory.
 653  *
 654  * @see             Unix stat()
 655  *
 656  */
 657 int smbc_stat(const char *url, struct stat *st);
 658
 659
 660 /**@ingroup attribute
 661  * Get file information via an file descriptor.
 662  *
 663  * @param fd        Open file handle from smbc_open() or smbc_creat()
 664  *
 665  * @param st        pointer to a buffer that will be filled with
 666  *                  standard Unix struct stat information.
 667  *
 668  * @return          EBADF  filedes is bad.
 669  *                  - EACCES Permission denied.
 670  *                  - EBADF fd is not a valid file descriptor
 671  *                  - EINVAL Problems occurred in the underlying routines
 672  *                    or smbc_init not called.
 673  *                  - ENOMEM Out of memory
 674  *
 675  * @see             smbc_stat(), Unix stat()
 676  *
 677  */
 678 int smbc_fstat(int fd, struct stat *st);
 679
 680
 681 /**@ingroup attribue
 682  * Change the ownership of a file or directory.
 683  *
 684  * @param url       The smb url of the file or directory to change
 685  *                  ownership of.
 686  *
 687  * @param owner     I have no idea?
 688  *
 689  * @param group     I have not idea?
 690  *
 691  * @return          0 on success, < 0 on error with errno set:
 692  *                  - EPERM  The effective UID does not match the owner
 693  *                  of the file, and is not zero; or the owner or group
 694  *                  were specified incorrectly.
 695  *                  - ENOENT The file does not exist.
 696  *                  - ENOMEM Insufficient was available.
 697  *                  - ENOENT file or directory does not exist
 698  *
 699  * @todo Are we actually going to be able to implement this function
 700  *
 701  * @todo How do we abstract owner and group uid and gid?
 702  *
 703  */
 704 int smbc_chown(const char *url, uid_t owner, gid_t group);
 705
 706
 707 /**@ingroup attribute
 708  * Change the permissions of a file.
 709  *
 710  * @param url       The smb url of the file or directory to change
 711  *                  permissions of
 712  *
 713  * @param mode      The permissions to set:
 714  *                  - Put good explaination of permissions here!
 715  *
 716  * @return          0 on success, < 0 on error with errno set:
 717  *                  - EPERM  The effective UID does not match the owner
 718  *                  of the file, and is not zero
 719  *                  - ENOENT The file does not exist.
 720  *                  - ENOMEM Insufficient was available.
 721  *                  - ENOENT file or directory does not exist
 722  *
 723  * @todo Actually implement this fuction?
 724  *
 725  * @todo Are errno values complete and correct?
 726  */
 727 int smbc_chmod(const char *url, mode_t mode);
 728
 729
 730 /**@ingroup print
 731  * Print a file given the name in fname. It would be a URL ...
 732  *
 733  * @param fname     The URL of a file on a remote SMB server that the
 734  *                  caller wants printed
 735  *
 736  * @param printq    The URL of the print share to print the file to.
 737  *
 738  * @return          0 on success, < 0 on error with errno set:
 739  *
 740  *                  - EINVAL fname or printq was NULL or smbc_init not
 741  *                    not called.
 742  *                  and errors returned by smbc_open
 743  *
 744  */
 745 int smbc_print_file(const char *fname, const char *printq);
 746
 747 /**@ingroup print
 748  * Open a print file that can be written to by other calls. This simply
 749  * does an smbc_open call after checking if there is a file name on the
 750  * URI. If not, a temporary name is added ...
 751  *
 752  * @param fname     The URL of the print share to print to?
 753  *
 754  * @returns         A file handle for the print file if successful.
 755  *                  Returns -1 if an error ocurred and errno has the values
 756  *                  - EINVAL fname was NULL or smbc_init not called.
 757  *                  - all errors returned by smbc_open
 758  *
 759  */
 760 int smbc_open_print_job(const char *fname);
 761
 762 /**@ingroup print
 763  * List the print jobs on a print share, for the moment, pass a callback
 764  *
 765  * @param purl      The url of the print share to list the jobs of
 766  *
 767  * @param fn        Callback function the receives printjob info
 768  *
 769  * @return          0 on success, < 0 on error with errno set:
 770  *                  - EINVAL fname was NULL or smbc_init not called
 771  *                  - EACCES ???
 772  */
 773 int smbc_list_print_jobs(const char *purl, smbc_get_print_job_info fn);
 774
 775 /**@ingroup print
 776  * Delete a print job
 777  *
 778  * @param purl      Url of the print share
 779  *
 780  * @param id        The id of the job to delete
 781  *
 782  * @return          0 on success, < 0 on error with errno set:
 783  *                  - EINVAL fname was NULL or smbc_init not called
 784  *
 785  * @todo    what errno values are possible here?
 786  */
 787 int smbc_unlink_print_job(const char *purl, int id);
 788
 789
 790 #endif /* SMBCLIENT_H_INCLUDED */