1 /*=====================================================================
2 Unix SMB/Netbios implementation.
4 SMB client library API definitions
5 Copyright (C) Andrew Tridgell 1998
6 Copyright (C) Richard Sharpe 2000
7 Copyright (C) John Terpsra 2000
9 This program is free software; you can redistribute it and/or modify
10 it under the terms of the GNU General Public License as published by
11 the Free Software Foundation; either version 2 of the License, or
12 (at your option) any later version.
14 This program is distributed in the hope that it will be useful,
15 but WITHOUT ANY WARRANTY; without even the implied warranty of
16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 GNU General Public License for more details.
19 You should have received a copy of the GNU General Public License
20 along with this program; if not, write to the Free Software
21 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
22 =====================================================================*/
24 #ifndef SMBCLIENT_H_INCLUDED
25 #define SMBCLIENT_H_INCLUDED
27 /*-------------------------------------------------------------------*/
28 /* The following are special comments to instruct DOXYGEN (automated
31 /** \defgroup structure Data Structures Type and Constants
32 * Data structures, types, and constants
34 /** \defgroup file File Functions
35 * Functions used to access individual file contents
37 /** \defgroup directory Directory Functions
38 * Functions used to access directory entries
40 /** \defgroup attribute Attributes Functions
41 * Functions used to view or change file and directory attributes
43 /** \defgroup print Print Functions
44 * Functions used to access printing functionality
46 /** \defgroup attribute Miscellaneous Functions
47 * Functions that don't fit in to other categories
49 /*-------------------------------------------------------------------*/
51 /* Make sure we have the following includes for now ... */
52 #include <sys/types.h>
56 #define SMBC_MAX_NAME 1023
57 #define SMBC_WORKGROUP 1
59 #define SMBC_FILE_SHARE 3
60 #define SMBC_PRINTER_SHARE 4
61 #define SMBC_COMMS_SHARE 5
62 #define SMBC_IPC_SHARE 6
67 #define SMBC_FILE_MODE (S_IFREG | 0444)
68 #define SMBC_DIR_MODE (S_IFDIR | 0555)
71 * Structure that represents a directory entry.
88 /** Length of this smbc_dirent in bytes
91 /** The length of the comment string in bytes (includes null
95 /** Points to the null terminated comment string
98 /** The length of the name string in bytes (includes null
102 /** Points to the null terminated name string
109 typedef unsigned short uint16;
111 /**@ingroup structure
112 * Structure that represents a print job.
115 struct print_job_info
117 /** numeric ID of the print job
121 /** represents print job priority (lower numbers mean higher priority)
125 /** Size of the print job
129 /** Name of the user that owns the print job
133 /** Name of the print job. This will have no name if an anonymous print
134 * file was opened. Ie smb://server/printer
138 /** Time the print job was spooled
145 /**@ingroup structure
146 * Authentication callback function type.
148 * Type for the the authentication function called by the library to
149 * obtain authentication credentals
151 * @param srv Server being authenticated to
153 * @param shr Share being authenticated to
155 * @param wg Pointer to buffer containing a "hint" for the
156 * workgroup to be authenticated. Should be filled in
157 * with the correct workgroup if the hint is wrong.
159 * @param wglen The size of the workgroup buffer in bytes
161 * @param un Pointer to buffer containing a "hint" for the
162 * user name to be use for authentication. Should be
163 * filled in with the correct workgroup if the hint is
166 * @param unlen The size of the username buffer in bytes
168 * @param pw Pointer to buffer containing to which password
171 * @param pwlen The size of the password buffer in bytes
174 typedef void (*smbc_get_auth_data_fn)(const char *srv,
178 char *pw, int pwlen);
181 /**@ingroup structure
182 * Print job info callback function type.
184 * @param i pointer to print job information structure
187 typedef void (*smbc_get_print_job_info)(struct print_job_info *i);
191 * Initialize the samba client library.
193 * Must be called before using any of the smbclient API function
195 * @param fn The function that will be called to obtaion
196 * authentication credentials.
198 * @param debug Allows caller to set the debug level. Can be
199 * changed in smb.conf file. Allows caller to set
200 * debugging if no smb.conf.
202 * @return 0 on success, < 0 on error with errno set:
203 * - ENOMEM Out of memory
204 * - ENOENT The smb.conf file would not load
207 int smbc_init(smbc_get_auth_data_fn fn, int debug);
211 * Open a file on an SMB server.
213 * @param furl The smb url of the file to be opened.
215 * @param flags Is one of O_RDONLY, O_WRONLY or O_RDWR which
216 * request opening the file read-only,write-only
217 * or read/write. flags may also be bitwise-or'd with
218 * one or more of the following:
219 * O_CREAT - If the file does not exist it will be
221 * O_EXCL - When used with O_CREAT, if the file
222 * already exists it is an error and the open will
224 * O_TRUNC - If the file already exists it will be
226 * O_APPEND The file is opened in append mode
228 * @param mode mode specifies the permissions to use if a new
229 * file is created. It is modified by the
230 * process's umask in the usual way: the permissions
231 * of the created file are (mode & ~umask)
233 * Not currently use, but there for future use.
234 * We will map this to SYSTEM, HIDDEN, etc bits
235 * that reverses the mapping that smbc_fstat does.
237 * @return Valid file handle, < 0 on error with errno set:
238 * - ENOMEM Out of memory
239 * - EINVAL if an invalid parameter passed, like no
240 * file, or smbc_init not called.
241 * - EEXIST pathname already exists and O_CREAT and
243 * - EISDIR pathname refers to a directory and
244 * the access requested involved writing.
245 * - EACCES The requested access to the file is not
247 * - ENODEV The requested share does not exist
248 * - ENOTDIR A file on the path is not a directory
249 * - ENOENT A directory component in pathname does
254 * @note This call uses an underlying routine that may create
255 * a new connection to the server specified in the URL.
256 * If the credentials supplied in the URL, or via the
257 * auth_fn in the smbc_init call, fail, this call will
258 * try again with an empty username and password. This
259 * often gets mapped to the guest account on some machines.
261 int smbc_open(const char *furl, int flags, mode_t mode);
265 * Create a file on an SMB server.
267 * Same as calling smbc_open() with flags = O_CREAT|O_WRONLY|O_TRUNC
269 * @param furl The smb url of the file to be created
271 * @param mode mode specifies the permissions to use if a new
272 * file is created. It is modified by the
273 * process's umask in the usual way: the permissions
274 * of the created file are (mode & ~umask)
276 * NOTE, the above is not true. We are dealing with
277 * an SMB server, which has no concept of a umask!
279 * @return Valid file handle, < 0 on error with errno set:
280 * - ENOMEM Out of memory
281 * - EINVAL if an invalid parameter passed, like no
282 * file, or smbc_init not called.
283 * - EEXIST pathname already exists and O_CREAT and
285 * - EISDIR pathname refers to a directory and
286 * the access requested involved writing.
287 * - EACCES The requested access to the file is not
289 * - ENOENT A directory component in pathname does
291 * - ENODEV The requested share does not exist.
295 int smbc_creat(const char *furl, mode_t mode);
299 * Read from a file using an opened file handle.
301 * @param fd Open file handle from smbc_open() or smbc_creat()
303 * @param buf Pointer to buffer to recieve read data
305 * @param bufsize Size of buf in bytes
307 * @return Number of bytes read, < 0 on error with errno set:
308 * - EISDIR fd refers to a directory
309 * - EBADF fd is not a valid file descriptor or
310 * is not open for reading.
311 * - EINVAL fd is attached to an object which is
312 * unsuitable for reading, or no buffer passed or
313 * smbc_init not called.
315 * @see smbc_open(), smbc_write()
318 ssize_t smbc_read(int fd, void *buf, size_t bufsize);
322 * Write to a file using an opened file handle.
324 * @param fd Open file handle from smbc_open() or smbc_creat()
326 * @param buf Pointer to buffer to recieve read data
328 * @param bufsize Size of buf in bytes
330 * @return Number of bytes written, < 0 on error with errno set:
331 * - EISDIR fd refers to a directory.
332 * - EBADF fd is not a valid file descriptor or
333 * is not open for reading.
334 * - EINVAL fd is attached to an object which is
335 * unsuitable for reading, or no buffer passed or
336 * smbc_init not called.
338 * @see smbc_open(), smbc_read()
341 ssize_t smbc_write(int fd, void *buf, size_t bufsize);
345 * Seek to a specific location in a file.
347 * @param fd Open file handle from smbc_open() or smbc_creat()
349 * @param offset Offset in bytes from whence
351 * @param whence A location in the file:
352 * - SEEK_SET The offset is set to offset bytes from
353 * the beginning of the file
354 * - SEEK_CUR The offset is set to current location
356 * - SEEK_END The offset is set to the size of the
357 * file plus offset bytes.
359 * @return Upon successful completion, lseek returns the
360 * resulting offset location as measured in bytes
361 * from the beginning of the file. Otherwise, a value
362 * of (off_t)-1 is returned and errno is set to
363 * indicate the error:
364 * - EBADF Fildes is not an open file descriptor.
365 * - EINVAL Whence is not a proper value or smbc_init
368 * @todo Are all the whence values really supported?
370 * @todo Are errno values complete and correct?
372 off_t smbc_lseek(int fd, off_t offset, int whence);
376 * Close an open file handle.
378 * @param fd The file handle to close
380 * @return 0 on success, < 0 on error with errno set:
381 * - EBADF fd isn't a valid open file descriptor
382 * - EINVAL smbc_init() failed or has not been called
384 * @see smbc_open(), smbc_creat()
386 int smbc_close(int fd);
389 /**@ingroup directory
390 * Unlink (delete) a file or directory.
392 * @param furl The smb url of the file to delete
394 * @return 0 on success, < 0 on error with errno set:
395 * - EACCES or EPERM Write access to the directory
396 * containing pathname is not allowed or one
397 * of the directories in pathname did not allow
398 * search (execute) permission
399 * - ENOENT A directory component in pathname does
401 * - EINVAL NULL was passed in the file param or
402 * smbc_init not called.
403 * - EACCES You do not have access to the file
404 * - ENOMEM Insufficient kernel memory was available
408 * @todo Are errno values complete and correct?
410 int smbc_unlink(const char *furl);
413 /**@ingroup directory
414 * Rename or move a file or directory.
416 * @param ourl The original smb url (source url) of file or
417 * directory to be moved
419 * @param nurl The new smb url (destination url) of the file
420 * or directory after the move. Currently nurl must
421 * be on the same share as ourl.
423 * @return 0 on success, < 0 on error with errno set:
424 * - EISDIR nurl is an existing directory, but ourl is
426 * - EEXIST nurl is a non-empty directory,
427 * i.e., contains entries other than "." and ".."
428 * - EINVAL The new url contained a path prefix
429 * of the old, or, more generally, an attempt was
430 * made to make a directory a subdirectory of itself
431 * or smbc_init not called.
432 * - ENOTDIR A component used as a directory in ourl
433 * or nurl path is not, in fact, a directory. Or,
434 * ourl is a directory, and newpath exists but is not
436 * - EACCES or EPERM Write access to the directory
437 * containing ourl or nurl is not allowed for the
438 * process's effective uid, or one of the
439 * directories in ourl or nurl did not allow search
440 * (execute) permission, or ourl was a directory
441 * and did not allow write permission.
442 * - ENOENT A directory component in ourl or nurl
444 * - EXDEV Rename across shares not supported.
445 * - ENOMEM Insufficient kernel memory was available.
446 * - EEXIST The target file, nurl, already exists.
449 * @todo Are we going to support copying when urls are not on the same
450 * share? I say no... NOTE. I agree for the moment.
453 int smbc_rename(const char *ourl, const char *nurl);
456 /**@ingroup directory
457 * Open a directory used to obtain directory entries.
459 * @param durl The smb url of the directory to open
461 * @return Valid directory handle. < 0 on error with errno set:
462 * - EACCES Permission denied.
463 * - EINVAL A NULL file/URL was passed, or the URL would
464 * not parse, or was of incorrect form or smbc_init not
466 * - ENOENT durl does not exist, or name is an
467 * - ENOMEM Insufficient memory to complete the
469 * - ENOTDIR name is not a directory.
470 * - EPERM the workgroup could not be found.
471 * - ENODEV the workgroup or server could not be found.
473 * @see smbc_getdents(), smbc_readdir(), smbc_closedir()
476 int smbc_opendir(const char *durl);
479 /**@ingroup directory
480 * Close a directory handle opened by smbc_opendir().
482 * @param dh Directory handle to close
484 * @return 0 on success, < 0 on error with errno set:
485 * - EBADF dh is an invalid directory handle
487 * @see smbc_opendir()
489 int smbc_closedir(int dh);
492 /**@ingroup directory
493 * Get multiple directory entries.
495 * smbc_getdents() reads as many dirent structures from the an open
496 * directory handle into a specified memory area as will fit.
498 * @param dh Valid directory as returned by smbc_opendir()
500 * @param dirp pointer to buffer that will receive the directory
503 * @param count The size of the dirp buffer in bytes
505 * @returns If any dirents returned, return will indicate the
506 * total size. If there were no more dirents available,
507 * 0 is returned. < 0 indicates an error.
508 * - EBADF Invalid directory handle
509 * - EINVAL Result buffer is too small or smbc_init
511 * - ENOENT No such directory.
512 * @see , smbc_dirent, smbc_readdir(), smbc_open()
514 * @todo Are errno values complete and correct?
516 * @todo Add example code so people know how to parse buffers.
518 int smbc_getdents(unsigned int dh, struct smbc_dirent *dirp, int count);
521 /**@ingroup directory
522 * Get a single directory entry.
524 * @param dh Valid directory as returned by smbc_opendir()
526 * @return A pointer to a smbc_dirent structure, or NULL if an
527 * error occurs or end-of-directory is reached:
528 * - EBADF Invalid directory handle
529 * - EINVAL smbc_init() failed or has not been called
531 * @see smbc_dirent, smbc_getdents(), smbc_open()
533 struct smbc_dirent* smbc_readdir(unsigned int dh);
536 /**@ingroup directory
537 * Get the current directory offset.
539 * smbc_telldir() may be used in conjunction with smbc_readdir() and
542 * @param dh Valid directory as returned by smbc_opendir()
544 * @return The current location in the directory stream or -1
545 * if an error occur. The current location is not
546 * an offset. Becuase of the implementation, it is a
547 * handle that allows the library to find the entry
549 * - EBADF dh is not a valid directory handle
550 * - EINVAL smbc_init() failed or has not been called
551 * - ENOTDIR if dh is not a directory
553 * @see smbc_readdir()
556 off_t smbc_telldir(int dh);
559 /**@ingroup directory
560 * lseek on directories.
562 * smbc_lseekdir() may be used in conjunction with smbc_readdir() and
563 * smbc_telldir(). (rewind by smbc_lseekdir(fd, NULL))
565 * @param fd Valid directory as returned by smbc_opendir()
567 * @param offset The offset (as returned by smbc_telldir). Can be
568 * NULL, in which case we will rewind
570 * @return 0 on success, -1 on failure
571 * - EBADF dh is not a valid directory handle
572 * - ENOTDIR if dh is not a directory
573 * - EINVAL offset did not refer to a valid dirent or
574 * smbc_init not called.
576 * @see smbc_telldir()
579 * @todo In what does the reture and errno values mean?
581 int smbc_lseekdir(int fd, off_t offset);
583 /**@ingroup directory
584 * Create a directory.
586 * @param durl The url of the directory to create
588 * @param mode Specifies the permissions to use. It is modified
589 * by the process's umask in the usual way: the
590 * permissions of the created file are (mode & ~umask).
592 * @return 0 on success, < 0 on error with errno set:
593 * - EEXIST directory url already exists
594 * - EACCES The parent directory does not allow write
595 * permission to the process, or one of the directories
596 * - ENOENT A directory component in pathname does not
598 * - EINVAL NULL durl passed or smbc_init not called.
599 * - ENOMEM Insufficient memory was available.
604 int smbc_mkdir(const char *durl, mode_t mode);
607 /**@ingroup directory
608 * Remove a directory.
610 * @param durl The smb url of the directory to remove
612 * @return 0 on success, < 0 on error with errno set:
613 * - EACCES or EPERM Write access to the directory
614 * containing pathname was not allowed.
615 * - EINVAL durl is NULL or smbc_init not called.
616 * - ENOENT A directory component in pathname does not
618 * - ENOTEMPTY directory contains entries.
619 * - ENOMEM Insufficient kernel memory was available.
621 * @see smbc_mkdir(), smbc_unlink()
623 * @todo Are errno values complete and correct?
625 int smbc_rmdir(const char *durl);
628 /**@ingroup attribute
629 * Get information about a file or directory.
631 * @param url The smb url to get information for
633 * @param st pointer to a buffer that will be filled with
634 * standard Unix struct stat information.
636 * @return 0 on success, < 0 on error with errno set:
637 * - ENOENT A component of the path file_name does not
639 * - EINVAL a NULL url was passed or smbc_init not called.
640 * - EACCES Permission denied.
641 * - ENOMEM Out of memory
642 * - ENOTDIR The target dir, url, is not a directory.
647 int smbc_stat(const char *url, struct stat *st);
650 /**@ingroup attribute
651 * Get file information via an file descriptor.
653 * @param fd Open file handle from smbc_open() or smbc_creat()
655 * @param st pointer to a buffer that will be filled with
656 * standard Unix struct stat information.
658 * @return EBADF filedes is bad.
659 * - EACCES Permission denied.
660 * - EBADF fd is not a valid file descriptor
661 * - EINVAL Problems occurred in the underlying routines
662 * or smbc_init not called.
663 * - ENOMEM Out of memory
665 * @see smbc_stat(), Unix stat()
668 int smbc_fstat(int fd, struct stat *st);
672 * Change the ownership of a file or directory.
674 * @param url The smb url of the file or directory to change
677 * @param owner I have no idea?
679 * @param group I have not idea?
681 * @return 0 on success, < 0 on error with errno set:
682 * - EPERM The effective UID does not match the owner
683 * of the file, and is not zero; or the owner or group
684 * were specified incorrectly.
685 * - ENOENT The file does not exist.
686 * - ENOMEM Insufficient was available.
687 * - ENOENT file or directory does not exist
689 * @todo Are we actually going to be able to implement this function
691 * @todo How do we abstract owner and group uid and gid?
694 int smbc_chown(const char *url, uid_t owner, gid_t group);
697 /**@ingroup attribute
698 * Change the permissions of a file.
700 * @param url The smb url of the file or directory to change
703 * @param mode The permissions to set:
704 * - Put good explaination of permissions here!
706 * @return 0 on success, < 0 on error with errno set:
707 * - EPERM The effective UID does not match the owner
708 * of the file, and is not zero
709 * - ENOENT The file does not exist.
710 * - ENOMEM Insufficient was available.
711 * - ENOENT file or directory does not exist
713 * @todo Actually implement this fuction?
715 * @todo Are errno values complete and correct?
717 int smbc_chmod(const char *url, mode_t mode);
721 * Print a file given the name in fname. It would be a URL ...
723 * @param fname The URL of a file on a remote SMB server that the
724 * caller wants printed
726 * @param printq The URL of the print share to print the file to.
728 * @return 0 on success, < 0 on error with errno set:
730 * - EINVAL fname or printq was NULL or smbc_init not
732 * and errors returned by smbc_open
735 int smbc_print_file(const char *fname, const char *printq);
738 * Open a print file that can be written to by other calls. This simply
739 * does an smbc_open call after checking if there is a file name on the
740 * URI. If not, a temporary name is added ...
742 * @param fname The URL of the print share to print to?
744 * @returns A file handle for the print file if successful.
745 * Returns -1 if an error ocurred and errno has the values
746 * - EINVAL fname was NULL or smbc_init not called.
747 * - all errors returned by smbc_open
750 int smbc_open_print_job(const char *fname);
753 * List the print jobs on a print share, for the moment, pass a callback
755 * @param purl The url of the print share to list the jobs of
757 * @param fn Callback function the receives printjob info
759 * @return 0 on success, < 0 on error with errno set:
760 * - EINVAL fname was NULL or smbc_init not called
763 int smbc_list_print_jobs(const char *purl, smbc_get_print_job_info fn);
768 * @param purl Url of the print share
770 * @param id The id of the job to delete
772 * @return 0 on success, < 0 on error with errno set:
773 * - EINVAL fname was NULL or smbc_init not called
775 * @todo what errno values are possible here?
777 int smbc_unlink_print_job(const char *purl, int id);
780 #endif /* SMBCLIENT_H_INCLUDED */