00001 /*===================================================================== 00002 Unix SMB/Netbios implementation. 00003 SMB client library API definitions 00004 Copyright (C) Andrew Tridgell 1998 00005 Copyright (C) Richard Sharpe 2000 00006 Copyright (C) John Terpsra 2000 00007 Copyright (C) Tom Jansen (Ninja ISD) 2002 00008 Copyright (C) Derrell Lipman 2003 00009 00010 00011 This program is free software; you can redistribute it and/or modify 00012 it under the terms of the GNU General Public License as published by 00013 the Free Software Foundation; either version 2 of the License, or 00014 (at your option) any later version. 00015 00016 This program is distributed in the hope that it will be useful, 00017 but WITHOUT ANY WARRANTY; without even the implied warranty of 00018 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 00019 GNU General Public License for more details. 00020 00021 You should have received a copy of the GNU General Public License 00022 along with this program; if not, write to the Free Software 00023 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. 00024 =====================================================================*/ 00025 00026 #ifndef SMBCLIENT_H_INCLUDED 00027 #define SMBCLIENT_H_INCLUDED 00028 00029 #ifdef __cplusplus 00030 extern "C" { 00031 #endif 00032 00033 /*-------------------------------------------------------------------*/ 00034 /* The following are special comments to instruct DOXYGEN (automated 00035 * documentation tool: 00036 */ 00037 /** \defgroup libsmbclient 00038 */ 00039 /** \defgroup structure Data Structures Type and Constants 00040 * \ingroup libsmbclient 00041 * Data structures, types, and constants 00042 */ 00043 /** \defgroup callback Callback function types 00044 * \ingroup libsmbclient 00045 * Callback functions 00046 */ 00047 /** \defgroup file File Functions 00048 * \ingroup libsmbclient 00049 * Functions used to access individual file contents 00050 */ 00051 /** \defgroup directory Directory Functions 00052 * \ingroup libsmbclient 00053 * Functions used to access directory entries 00054 */ 00055 /** \defgroup attribute Attributes Functions 00056 * \ingroup libsmbclient 00057 * Functions used to view or change file and directory attributes 00058 */ 00059 /** \defgroup print Print Functions 00060 * \ingroup libsmbclient 00061 * Functions used to access printing functionality 00062 */ 00063 /** \defgroup misc Miscellaneous Functions 00064 * \ingroup libsmbclient 00065 * Functions that don't fit in to other categories 00066 */ 00067 /*-------------------------------------------------------------------*/ 00068 00069 /* Make sure we have the following includes for now ... */ 00070 #include <sys/types.h> 00071 #include <sys/stat.h> 00072 #include <fcntl.h> 00073 #include <utime.h> 00074 00075 #define SMBC_BASE_FD 10000 /* smallest file descriptor returned */ 00076 00077 #define SMBC_WORKGROUP 1 00078 #define SMBC_SERVER 2 00079 #define SMBC_FILE_SHARE 3 00080 #define SMBC_PRINTER_SHARE 4 00081 #define SMBC_COMMS_SHARE 5 00082 #define SMBC_IPC_SHARE 6 00083 #define SMBC_DIR 7 00084 #define SMBC_FILE 8 00085 #define SMBC_LINK 9 00086 00087 /**@ingroup structure 00088 * Structure that represents a directory entry. 00089 * 00090 */ 00091 struct smbc_dirent 00092 { 00093 /** Type of entity. 00094 SMBC_WORKGROUP=1, 00095 SMBC_SERVER=2, 00096 SMBC_FILE_SHARE=3, 00097 SMBC_PRINTER_SHARE=4, 00098 SMBC_COMMS_SHARE=5, 00099 SMBC_IPC_SHARE=6, 00100 SMBC_DIR=7, 00101 SMBC_FILE=8, 00102 SMBC_LINK=9,*/ 00103 unsigned int smbc_type; 00104 00105 /** Length of this smbc_dirent in bytes 00106 */ 00107 unsigned int dirlen; 00108 /** The length of the comment string in bytes (does not include 00109 * null terminator) 00110 */ 00111 unsigned int commentlen; 00112 /** Points to the null terminated comment string 00113 */ 00114 char *comment; 00115 /** The length of the name string in bytes (does not include 00116 * null terminator) 00117 */ 00118 unsigned int namelen; 00119 /** Points to the null terminated name string 00120 */ 00121 char name[1]; 00122 }; 00123 00124 /* 00125 * Flags for smbc_setxattr() 00126 * Specify a bitwise OR of these, or 0 to add or replace as necessary 00127 */ 00128 #define SMBC_XATTR_FLAG_CREATE 0x1 /* fail if attr already exists */ 00129 #define SMBC_XATTR_FLAG_REPLACE 0x2 /* fail if attr does not exist */ 00130 00131 00132 /* 00133 * Mappings of the DOS mode bits, as returned by smbc_getxattr() when the 00134 * attribute name "system.dos_attr.mode" (or "system.dos_attr.*" or 00135 * "system.*") is specified. 00136 */ 00137 #define SMBC_DOS_MODE_READONLY 0x01 00138 #define SMBC_DOS_MODE_HIDDEN 0x02 00139 #define SMBC_DOS_MODE_SYSTEM 0x04 00140 #define SMBC_DOS_MODE_VOLUME_ID 0x08 00141 #define SMBC_DOS_MODE_DIRECTORY 0x10 00142 #define SMBC_DOS_MODE_ARCHIVE 0x20 00143 00144 /* 00145 * Valid values for the option "open_share_mode", when calling 00146 * smbc_option_set() 00147 */ 00148 typedef enum smbc_share_mode 00149 { 00150 SMBC_SHAREMODE_DENY_DOS = 0, 00151 SMBC_SHAREMODE_DENY_ALL = 1, 00152 SMBC_SHAREMODE_DENY_WRITE = 2, 00153 SMBC_SHAREMODE_DENY_READ = 3, 00154 SMBC_SHAREMODE_DENY_NONE = 4, 00155 SMBC_SHAREMODE_DENY_FCB = 7 00156 } smbc_share_mode; 00157 00158 00159 #ifndef ENOATTR 00160 # define ENOATTR ENOENT /* No such attribute */ 00161 #endif 00162 00163 00164 00165 00166 /**@ingroup structure 00167 * Structure that represents a print job. 00168 * 00169 */ 00170 #ifndef _CLIENT_H 00171 struct print_job_info 00172 { 00173 /** numeric ID of the print job 00174 */ 00175 unsigned short id; 00176 00177 /** represents print job priority (lower numbers mean higher priority) 00178 */ 00179 unsigned short priority; 00180 00181 /** Size of the print job 00182 */ 00183 size_t size; 00184 00185 /** Name of the user that owns the print job 00186 */ 00187 char user[128]; 00188 00189 /** Name of the print job. This will have no name if an anonymous print 00190 * file was opened. Ie smb://server/printer 00191 */ 00192 char name[128]; 00193 00194 /** Time the print job was spooled 00195 */ 00196 time_t t; 00197 }; 00198 #endif /* _CLIENT_H */ 00199 00200 00201 /**@ingroup structure 00202 * Server handle 00203 */ 00204 typedef struct _SMBCSRV SMBCSRV; 00205 00206 /**@ingroup structure 00207 * File or directory handle 00208 */ 00209 typedef struct _SMBCFILE SMBCFILE; 00210 00211 /**@ingroup structure 00212 * File or directory handle 00213 */ 00214 typedef struct _SMBCCTX SMBCCTX; 00215 00216 00217 00218 00219 00220 /**@ingroup callback 00221 * Authentication callback function type (traditional method) 00222 * 00223 * Type for the the authentication function called by the library to 00224 * obtain authentication credentals 00225 * 00226 * @param srv Server being authenticated to 00227 * 00228 * @param shr Share being authenticated to 00229 * 00230 * @param wg Pointer to buffer containing a "hint" for the 00231 * workgroup to be authenticated. Should be filled in 00232 * with the correct workgroup if the hint is wrong. 00233 * 00234 * @param wglen The size of the workgroup buffer in bytes 00235 * 00236 * @param un Pointer to buffer containing a "hint" for the 00237 * user name to be use for authentication. Should be 00238 * filled in with the correct workgroup if the hint is 00239 * wrong. 00240 * 00241 * @param unlen The size of the username buffer in bytes 00242 * 00243 * @param pw Pointer to buffer containing to which password 00244 * copied 00245 * 00246 * @param pwlen The size of the password buffer in bytes 00247 * 00248 */ 00249 typedef void (*smbc_get_auth_data_fn)(const char *srv, 00250 const char *shr, 00251 char *wg, int wglen, 00252 char *un, int unlen, 00253 char *pw, int pwlen); 00254 /**@ingroup callback 00255 * Authentication callback function type (method that includes context) 00256 * 00257 * Type for the the authentication function called by the library to 00258 * obtain authentication credentals 00259 * 00260 * @param c Pointer to the smb context 00261 * 00262 * @param srv Server being authenticated to 00263 * 00264 * @param shr Share being authenticated to 00265 * 00266 * @param wg Pointer to buffer containing a "hint" for the 00267 * workgroup to be authenticated. Should be filled in 00268 * with the correct workgroup if the hint is wrong. 00269 * 00270 * @param wglen The size of the workgroup buffer in bytes 00271 * 00272 * @param un Pointer to buffer containing a "hint" for the 00273 * user name to be use for authentication. Should be 00274 * filled in with the correct workgroup if the hint is 00275 * wrong. 00276 * 00277 * @param unlen The size of the username buffer in bytes 00278 * 00279 * @param pw Pointer to buffer containing to which password 00280 * copied 00281 * 00282 * @param pwlen The size of the password buffer in bytes 00283 * 00284 */ 00285 typedef void (*smbc_get_auth_data_with_context_fn)(SMBCCTX *c, 00286 const char *srv, 00287 const char *shr, 00288 char *wg, int wglen, 00289 char *un, int unlen, 00290 char *pw, int pwlen); 00291 00292 00293 /**@ingroup callback 00294 * Print job info callback function type. 00295 * 00296 * @param i pointer to print job information structure 00297 * 00298 */ 00299 typedef void (*smbc_list_print_job_fn)(struct print_job_info *i); 00300 00301 00302 /**@ingroup callback 00303 * Check if a server is still good 00304 * 00305 * @param c pointer to smb context 00306 * 00307 * @param srv pointer to server to check 00308 * 00309 * @return 0 when connection is good. 1 on error. 00310 * 00311 */ 00312 typedef int (*smbc_check_server_fn)(SMBCCTX * c, SMBCSRV *srv); 00313 00314 /**@ingroup callback 00315 * Remove a server if unused 00316 * 00317 * @param c pointer to smb context 00318 * 00319 * @param srv pointer to server to remove 00320 * 00321 * @return 0 on success. 1 on failure. 00322 * 00323 */ 00324 typedef int (*smbc_remove_unused_server_fn)(SMBCCTX * c, SMBCSRV *srv); 00325 00326 00327 /**@ingroup callback 00328 * Add a server to the cache system 00329 * 00330 * @param c pointer to smb context 00331 * 00332 * @param srv pointer to server to add 00333 * 00334 * @param server server name 00335 * 00336 * @param share share name 00337 * 00338 * @param workgroup workgroup used to connect 00339 * 00340 * @param username username used to connect 00341 * 00342 * @return 0 on success. 1 on failure. 00343 * 00344 */ 00345 typedef int (*smbc_add_cached_srv_fn) (SMBCCTX * c, SMBCSRV *srv, 00346 const char * server, const char * share, 00347 const char * workgroup, const char * username); 00348 00349 /**@ingroup callback 00350 * Look up a server in the cache system 00351 * 00352 * @param c pointer to smb context 00353 * 00354 * @param server server name to match 00355 * 00356 * @param share share name to match 00357 * 00358 * @param workgroup workgroup to match 00359 * 00360 * @param username username to match 00361 * 00362 * @return pointer to SMBCSRV on success. NULL on failure. 00363 * 00364 */ 00365 typedef SMBCSRV * (*smbc_get_cached_srv_fn) (SMBCCTX * c, const char * server, 00366 const char * share, const char * workgroup, 00367 const char * username); 00368 00369 /**@ingroup callback 00370 * Check if a server is still good 00371 * 00372 * @param c pointer to smb context 00373 * 00374 * @param srv pointer to server to remove 00375 * 00376 * @return 0 when found and removed. 1 on failure. 00377 * 00378 */ 00379 typedef int (*smbc_remove_cached_srv_fn)(SMBCCTX * c, SMBCSRV *srv); 00380 00381 00382 /**@ingroup callback 00383 * Try to remove all servers from the cache system and disconnect 00384 * 00385 * @param c pointer to smb context 00386 * 00387 * @return 0 when found and removed. 1 on failure. 00388 * 00389 */ 00390 typedef int (*smbc_purge_cached_fn) (SMBCCTX * c); 00391 00392 00393 /**@ingroup structure 00394 * Structure that contains a client context information 00395 * This structure is know as SMBCCTX 00396 */ 00397 struct _SMBCCTX { 00398 /** debug level 00399 */ 00400 int debug; 00401 00402 /** netbios name used for making connections 00403 */ 00404 char * netbios_name; 00405 00406 /** workgroup name used for making connections 00407 */ 00408 char * workgroup; 00409 00410 /** username used for making connections 00411 */ 00412 char * user; 00413 00414 /** timeout used for waiting on connections / response data (in milliseconds) 00415 */ 00416 int timeout; 00417 00418 /** callable functions for files: 00419 * For usage and return values see the smbc_* functions 00420 */ 00421 SMBCFILE * (*open) (SMBCCTX *c, const char *fname, int flags, mode_t mode); 00422 SMBCFILE * (*creat) (SMBCCTX *c, const char *path, mode_t mode); 00423 ssize_t (*read) (SMBCCTX *c, SMBCFILE *file, void *buf, size_t count); 00424 ssize_t (*write) (SMBCCTX *c, SMBCFILE *file, void *buf, size_t count); 00425 int (*unlink) (SMBCCTX *c, const char *fname); 00426 int (*rename) (SMBCCTX *ocontext, const char *oname, 00427 SMBCCTX *ncontext, const char *nname); 00428 off_t (*lseek) (SMBCCTX *c, SMBCFILE * file, off_t offset, int whence); 00429 int (*stat) (SMBCCTX *c, const char *fname, struct stat *st); 00430 int (*fstat) (SMBCCTX *c, SMBCFILE *file, struct stat *st); 00431 int (*close_fn) (SMBCCTX *c, SMBCFILE *file); 00432 00433 /** callable functions for dirs 00434 */ 00435 SMBCFILE * (*opendir) (SMBCCTX *c, const char *fname); 00436 int (*closedir)(SMBCCTX *c, SMBCFILE *dir); 00437 struct smbc_dirent * (*readdir)(SMBCCTX *c, SMBCFILE *dir); 00438 int (*getdents)(SMBCCTX *c, SMBCFILE *dir, 00439 struct smbc_dirent *dirp, int count); 00440 int (*mkdir) (SMBCCTX *c, const char *fname, mode_t mode); 00441 int (*rmdir) (SMBCCTX *c, const char *fname); 00442 off_t (*telldir) (SMBCCTX *c, SMBCFILE *dir); 00443 int (*lseekdir)(SMBCCTX *c, SMBCFILE *dir, off_t offset); 00444 int (*fstatdir)(SMBCCTX *c, SMBCFILE *dir, struct stat *st); 00445 int (*chmod)(SMBCCTX *c, const char *fname, mode_t mode); 00446 int (*utimes)(SMBCCTX *c, 00447 const char *fname, struct timeval *tbuf); 00448 int (*setxattr)(SMBCCTX *context, 00449 const char *fname, 00450 const char *name, 00451 const void *value, 00452 size_t size, 00453 int flags); 00454 int (*getxattr)(SMBCCTX *context, 00455 const char *fname, 00456 const char *name, 00457 const void *value, 00458 size_t size); 00459 int (*removexattr)(SMBCCTX *context, 00460 const char *fname, 00461 const char *name); 00462 int (*listxattr)(SMBCCTX *context, 00463 const char *fname, 00464 char *list, 00465 size_t size); 00466 00467 /** callable functions for printing 00468 */ 00469 int (*print_file)(SMBCCTX *c_file, const char *fname, 00470 SMBCCTX *c_print, const char *printq); 00471 SMBCFILE * (*open_print_job)(SMBCCTX *c, const char *fname); 00472 int (*list_print_jobs)(SMBCCTX *c, const char *fname, smbc_list_print_job_fn fn); 00473 int (*unlink_print_job)(SMBCCTX *c, const char *fname, int id); 00474 00475 00476 /* 00477 ** Callbacks 00478 * These callbacks _always_ have to be initialized because they will 00479 * not be checked at dereference for increased speed. 00480 */ 00481 struct _smbc_callbacks { 00482 /** authentication function callback: called upon auth requests 00483 */ 00484 smbc_get_auth_data_fn auth_fn; 00485 00486 /** check if a server is still good 00487 */ 00488 smbc_check_server_fn check_server_fn; 00489 00490 /** remove a server if unused 00491 */ 00492 smbc_remove_unused_server_fn remove_unused_server_fn; 00493 00494 /** Cache subsystem 00495 * For an example cache system see samba/source/libsmb/libsmb_cache.c 00496 * Cache subsystem functions follow. 00497 */ 00498 00499 /** server cache addition 00500 */ 00501 smbc_add_cached_srv_fn add_cached_srv_fn; 00502 00503 /** server cache lookup 00504 */ 00505 smbc_get_cached_srv_fn get_cached_srv_fn; 00506 00507 /** server cache removal 00508 */ 00509 smbc_remove_cached_srv_fn remove_cached_srv_fn; 00510 00511 /** server cache purging, try to remove all cached servers (disconnect) 00512 */ 00513 smbc_purge_cached_fn purge_cached_fn; 00514 } callbacks; 00515 00516 00517 /** Space to store private data of the server cache. 00518 */ 00519 struct smbc_server_cache * server_cache; 00520 00521 int flags; 00522 00523 /** user options selections that apply to this session 00524 */ 00525 struct _smbc_options { 00526 00527 /* 00528 * From how many local master browsers should the list of 00529 * workgroups be retrieved? It can take up to 12 minutes or 00530 * longer after a server becomes a local master browser, for 00531 * it to have the entire browse list (the list of 00532 * workgroups/domains) from an entire network. Since a client 00533 * never knows which local master browser will be found first, 00534 * the one which is found first and used to retrieve a browse 00535 * list may have an incomplete or empty browse list. By 00536 * requesting the browse list from multiple local master 00537 * browsers, a more complete list can be generated. For small 00538 * networks (few workgroups), it is recommended that this 00539 * value be set to 0, causing the browse lists from all found 00540 * local master browsers to be retrieved and merged. For 00541 * networks with many workgroups, a suitable value for this 00542 * variable is probably somewhere around 3. (Default: 3). 00543 */ 00544 int browse_max_lmb_count; 00545 00546 /* 00547 * There is a difference in the desired return strings from 00548 * smbc_readdir() depending upon whether the filenames are to 00549 * be displayed to the user, or whether they are to be 00550 * appended to the path name passed to smbc_opendir() to call 00551 * a further smbc_ function (e.g. open the file with 00552 * smbc_open()). In the former case, the filename should be 00553 * in "human readable" form. In the latter case, the smbc_ 00554 * functions expect a URL which must be url-encoded. Those 00555 * functions decode the URL. If, for example, smbc_readdir() 00556 * returned a file name of "abc%20def.txt", passing a path 00557 * with this file name attached to smbc_open() would cause 00558 * smbc_open to attempt to open the file "abc def.txt" since 00559 * the %20 is decoded into a space. 00560 * 00561 * Set this option to True if the names returned by 00562 * smbc_readdir() should be url-encoded such that they can be 00563 * passed back to another smbc_ call. Set it to False if the 00564 * names returned by smbc_readdir() are to be presented to the 00565 * user. 00566 * 00567 * For backwards compatibility, this option defaults to False. 00568 */ 00569 int urlencode_readdir_entries; 00570 00571 /* 00572 * Some Windows versions appear to have a limit to the number 00573 * of concurrent SESSIONs and/or TREE CONNECTions. In 00574 * one-shot programs (i.e. the program runs and then quickly 00575 * ends, thereby shutting down all connections), it is 00576 * probably reasonable to establish a new connection for each 00577 * share. In long-running applications, the limitation can be 00578 * avoided by using only a single connection to each server, 00579 * and issuing a new TREE CONNECT when the share is accessed. 00580 */ 00581 int one_share_per_server; 00582 } options; 00583 00584 /** INTERNAL DATA 00585 * do _NOT_ touch this from your program ! 00586 */ 00587 struct smbc_internal_data * internal; 00588 }; 00589 00590 /* Flags for SMBCCTX->flags */ 00591 #define SMB_CTX_FLAG_USE_KERBEROS (1 << 0) 00592 #define SMB_CTX_FLAG_FALLBACK_AFTER_KERBEROS (1 << 1) 00593 #define SMBCCTX_FLAG_NO_AUTO_ANONYMOUS_LOGON (1 << 2) /* don't try to do automatic anon login */ 00594 00595 /**@ingroup misc 00596 * Create a new SBMCCTX (a context). 00597 * 00598 * Must be called before the context is passed to smbc_context_init() 00599 * 00600 * @return The given SMBCCTX pointer on success, NULL on error with errno set: 00601 * - ENOMEM Out of memory 00602 * 00603 * @see smbc_free_context(), smbc_init_context() 00604 * 00605 * @note Do not forget to smbc_init_context() the returned SMBCCTX pointer ! 00606 */ 00607 SMBCCTX * smbc_new_context(void); 00608 00609 /**@ingroup misc 00610 * Delete a SBMCCTX (a context) acquired from smbc_new_context(). 00611 * 00612 * The context will be deleted if possible. 00613 * 00614 * @param context A pointer to a SMBCCTX obtained from smbc_new_context() 00615 * 00616 * @param shutdown_ctx If 1, all connections and files will be closed even if they are busy. 00617 * 00618 * 00619 * @return Returns 0 on succes. Returns 1 on failure with errno set: 00620 * - EBUSY Server connections are still used, Files are open or cache 00621 * could not be purged 00622 * - EBADF context == NULL 00623 * 00624 * @see smbc_new_context() 00625 * 00626 * @note It is advised to clean up all the contexts with shutdown_ctx set to 1 00627 * just before exit()'ing. When shutdown_ctx is 0, this function can be 00628 * use in periodical cleanup functions for example. 00629 */ 00630 int smbc_free_context(SMBCCTX * context, int shutdown_ctx); 00631 00632 00633 /**@ingroup misc 00634 * Each time the context structure is changed, we have binary backward 00635 * compatibility issues. Instead of modifying the public portions of the 00636 * context structure to add new options, instead, we put them in the internal 00637 * portion of the context structure and provide a set function for these new 00638 * options. 00639 * 00640 * @param context A pointer to a SMBCCTX obtained from smbc_new_context() 00641 * 00642 * @param option_name 00643 * The name of the option for which the value is to be set 00644 * 00645 * @param option_value 00646 * The new value of the option being set 00647 * 00648 */ 00649 void 00650 smbc_option_set(SMBCCTX *context, 00651 char *option_name, 00652 ... /* option_value */); 00653 /* 00654 * Retrieve the current value of an option 00655 * 00656 * @param context A pointer to a SMBCCTX obtained from smbc_new_context() 00657 * 00658 * @param option_name 00659 * The name of the option for which the value is to be 00660 * retrieved 00661 * 00662 * @return The value of the specified option. 00663 */ 00664 void * 00665 smbc_option_get(SMBCCTX *context, 00666 char *option_name); 00667 00668 /**@ingroup misc 00669 * Initialize a SBMCCTX (a context). 00670 * 00671 * Must be called before using any SMBCCTX API function 00672 * 00673 * @param context A pointer to a SMBCCTX obtained from smbc_new_context() 00674 * 00675 * @return A pointer to the given SMBCCTX on success, 00676 * NULL on error with errno set: 00677 * - EBADF NULL context given 00678 * - ENOMEM Out of memory 00679 * - ENOENT The smb.conf file would not load 00680 * 00681 * @see smbc_new_context() 00682 * 00683 * @note my_context = smbc_init_context(smbc_new_context()) 00684 * is perfectly safe, but it might leak memory on 00685 * smbc_context_init() failure. Avoid this. 00686 * You'll have to call smbc_free_context() yourself 00687 * on failure. 00688 */ 00689 00690 SMBCCTX * smbc_init_context(SMBCCTX * context); 00691 00692 /**@ingroup misc 00693 * Initialize the samba client library. 00694 * 00695 * Must be called before using any of the smbclient API function 00696 * 00697 * @param fn The function that will be called to obtaion 00698 * authentication credentials. 00699 * 00700 * @param debug Allows caller to set the debug level. Can be 00701 * changed in smb.conf file. Allows caller to set 00702 * debugging if no smb.conf. 00703 * 00704 * @return 0 on success, < 0 on error with errno set: 00705 * - ENOMEM Out of memory 00706 * - ENOENT The smb.conf file would not load 00707 * 00708 */ 00709 00710 int smbc_init(smbc_get_auth_data_fn fn, int debug); 00711 00712 /**@ingroup misc 00713 * Set or retrieve the compatibility library's context pointer 00714 * 00715 * @param context New context to use, or NULL. If a new context is provided, 00716 * it must have allocated with smbc_new_context() and 00717 * initialized with smbc_init_context(), followed, optionally, 00718 * by some manual changes to some of the non-internal fields. 00719 * 00720 * @return The old context. 00721 * 00722 * @see smbc_new_context(), smbc_init_context(), smbc_init() 00723 * 00724 * @note This function may be called prior to smbc_init() to force 00725 * use of the next context without any internal calls to 00726 * smbc_new_context() or smbc_init_context(). It may also 00727 * be called after smbc_init() has already called those two 00728 * functions, to replace the existing context with a new one. 00729 * Care should be taken, in this latter case, to ensure that 00730 * the server cache and any data allocated by the 00731 * authentication functions have been freed, if necessary. 00732 */ 00733 00734 SMBCCTX * smbc_set_context(SMBCCTX * new_context); 00735 00736 /**@ingroup file 00737 * Open a file on an SMB server. 00738 * 00739 * @param furl The smb url of the file to be opened. 00740 * 00741 * @param flags Is one of O_RDONLY, O_WRONLY or O_RDWR which 00742 * request opening the file read-only,write-only 00743 * or read/write. flags may also be bitwise-or'd with 00744 * one or more of the following: 00745 * O_CREAT - If the file does not exist it will be 00746 * created. 00747 * O_EXCL - When used with O_CREAT, if the file 00748 * already exists it is an error and the open will 00749 * fail. 00750 * O_TRUNC - If the file already exists it will be 00751 * truncated. 00752 * O_APPEND The file is opened in append mode 00753 * 00754 * @param mode mode specifies the permissions to use if a new 00755 * file is created. It is modified by the 00756 * process's umask in the usual way: the permissions 00757 * of the created file are (mode & ~umask) 00758 * 00759 * Not currently use, but there for future use. 00760 * We will map this to SYSTEM, HIDDEN, etc bits 00761 * that reverses the mapping that smbc_fstat does. 00762 * 00763 * @return Valid file handle, < 0 on error with errno set: 00764 * - ENOMEM Out of memory 00765 * - EINVAL if an invalid parameter passed, like no 00766 * file, or smbc_init not called. 00767 * - EEXIST pathname already exists and O_CREAT and 00768 * O_EXCL were used. 00769 * - EISDIR pathname refers to a directory and 00770 * the access requested involved writing. 00771 * - EACCES The requested access to the file is not 00772 * allowed 00773 * - ENODEV The requested share does not exist 00774 * - ENOTDIR A file on the path is not a directory 00775 * - ENOENT A directory component in pathname does 00776 * not exist. 00777 * 00778 * @see smbc_creat() 00779 * 00780 * @note This call uses an underlying routine that may create 00781 * a new connection to the server specified in the URL. 00782 * If the credentials supplied in the URL, or via the 00783 * auth_fn in the smbc_init call, fail, this call will 00784 * try again with an empty username and password. This 00785 * often gets mapped to the guest account on some machines. 00786 */ 00787 00788 int smbc_open(const char *furl, int flags, mode_t mode); 00789 00790 /**@ingroup file 00791 * Create a file on an SMB server. 00792 * 00793 * Same as calling smbc_open() with flags = O_CREAT|O_WRONLY|O_TRUNC 00794 * 00795 * @param furl The smb url of the file to be created 00796 * 00797 * @param mode mode specifies the permissions to use if a new 00798 * file is created. It is modified by the 00799 * process's umask in the usual way: the permissions 00800 * of the created file are (mode & ~umask) 00801 * 00802 * NOTE, the above is not true. We are dealing with 00803 * an SMB server, which has no concept of a umask! 00804 * 00805 * @return Valid file handle, < 0 on error with errno set: 00806 * - ENOMEM Out of memory 00807 * - EINVAL if an invalid parameter passed, like no 00808 * file, or smbc_init not called. 00809 * - EEXIST pathname already exists and O_CREAT and 00810 * O_EXCL were used. 00811 * - EISDIR pathname refers to a directory and 00812 * the access requested involved writing. 00813 * - EACCES The requested access to the file is not 00814 * allowed 00815 * - ENOENT A directory component in pathname does 00816 * not exist. 00817 * - ENODEV The requested share does not exist. 00818 * @see smbc_open() 00819 * 00820 */ 00821 00822 int smbc_creat(const char *furl, mode_t mode); 00823 00824 /**@ingroup file 00825 * Read from a file using an opened file handle. 00826 * 00827 * @param fd Open file handle from smbc_open() or smbc_creat() 00828 * 00829 * @param buf Pointer to buffer to recieve read data 00830 * 00831 * @param bufsize Size of buf in bytes 00832 * 00833 * @return Number of bytes read, < 0 on error with errno set: 00834 * - EISDIR fd refers to a directory 00835 * - EBADF fd is not a valid file descriptor or 00836 * is not open for reading. 00837 * - EINVAL fd is attached to an object which is 00838 * unsuitable for reading, or no buffer passed or 00839 * smbc_init not called. 00840 * 00841 * @see smbc_open(), smbc_write() 00842 * 00843 */ 00844 ssize_t smbc_read(int fd, void *buf, size_t bufsize); 00845 00846 00847 /**@ingroup file 00848 * Write to a file using an opened file handle. 00849 * 00850 * @param fd Open file handle from smbc_open() or smbc_creat() 00851 * 00852 * @param buf Pointer to buffer to recieve read data 00853 * 00854 * @param bufsize Size of buf in bytes 00855 * 00856 * @return Number of bytes written, < 0 on error with errno set: 00857 * - EISDIR fd refers to a directory. 00858 * - EBADF fd is not a valid file descriptor or 00859 * is not open for reading. 00860 * - EINVAL fd is attached to an object which is 00861 * unsuitable for reading, or no buffer passed or 00862 * smbc_init not called. 00863 * 00864 * @see smbc_open(), smbc_read() 00865 * 00866 */ 00867 ssize_t smbc_write(int fd, void *buf, size_t bufsize); 00868 00869 00870 /**@ingroup file 00871 * Seek to a specific location in a file. 00872 * 00873 * @param fd Open file handle from smbc_open() or smbc_creat() 00874 * 00875 * @param offset Offset in bytes from whence 00876 * 00877 * @param whence A location in the file: 00878 * - SEEK_SET The offset is set to offset bytes from 00879 * the beginning of the file 00880 * - SEEK_CUR The offset is set to current location 00881 * plus offset bytes. 00882 * - SEEK_END The offset is set to the size of the 00883 * file plus offset bytes. 00884 * 00885 * @return Upon successful completion, lseek returns the 00886 * resulting offset location as measured in bytes 00887 * from the beginning of the file. Otherwise, a value 00888 * of (off_t)-1 is returned and errno is set to 00889 * indicate the error: 00890 * - EBADF Fildes is not an open file descriptor. 00891 * - EINVAL Whence is not a proper value or smbc_init 00892 * not called. 00893 * 00894 * @todo Are all the whence values really supported? 00895 * 00896 * @todo Are errno values complete and correct? 00897 */ 00898 off_t smbc_lseek(int fd, off_t offset, int whence); 00899 00900 00901 /**@ingroup file 00902 * Close an open file handle. 00903 * 00904 * @param fd The file handle to close 00905 * 00906 * @return 0 on success, < 0 on error with errno set: 00907 * - EBADF fd isn't a valid open file descriptor 00908 * - EINVAL smbc_init() failed or has not been called 00909 * 00910 * @see smbc_open(), smbc_creat() 00911 */ 00912 int smbc_close(int fd); 00913 00914 00915 /**@ingroup directory 00916 * Unlink (delete) a file or directory. 00917 * 00918 * @param furl The smb url of the file to delete 00919 * 00920 * @return 0 on success, < 0 on error with errno set: 00921 * - EACCES or EPERM Write access to the directory 00922 * containing pathname is not allowed or one 00923 * of the directories in pathname did not allow 00924 * search (execute) permission 00925 * - ENOENT A directory component in pathname does 00926 * not exist 00927 * - EINVAL NULL was passed in the file param or 00928 * smbc_init not called. 00929 * - EACCES You do not have access to the file 00930 * - ENOMEM Insufficient kernel memory was available 00931 * 00932 * @see smbc_rmdir()s 00933 * 00934 * @todo Are errno values complete and correct? 00935 */ 00936 int smbc_unlink(const char *furl); 00937 00938 00939 /**@ingroup directory 00940 * Rename or move a file or directory. 00941 * 00942 * @param ourl The original smb url (source url) of file or 00943 * directory to be moved 00944 * 00945 * @param nurl The new smb url (destination url) of the file 00946 * or directory after the move. Currently nurl must 00947 * be on the same share as ourl. 00948 * 00949 * @return 0 on success, < 0 on error with errno set: 00950 * - EISDIR nurl is an existing directory, but ourl is 00951 * not a directory. 00952 * - EEXIST nurl is a non-empty directory, 00953 * i.e., contains entries other than "." and ".." 00954 * - EINVAL The new url contained a path prefix 00955 * of the old, or, more generally, an attempt was 00956 * made to make a directory a subdirectory of itself 00957 * or smbc_init not called. 00958 * - ENOTDIR A component used as a directory in ourl 00959 * or nurl path is not, in fact, a directory. Or, 00960 * ourl is a directory, and newpath exists but is not 00961 * a directory. 00962 * - EACCES or EPERM Write access to the directory 00963 * containing ourl or nurl is not allowed for the 00964 * process's effective uid, or one of the 00965 * directories in ourl or nurl did not allow search 00966 * (execute) permission, or ourl was a directory 00967 * and did not allow write permission. 00968 * - ENOENT A directory component in ourl or nurl 00969 * does not exist. 00970 * - EXDEV Rename across shares not supported. 00971 * - ENOMEM Insufficient kernel memory was available. 00972 * - EEXIST The target file, nurl, already exists. 00973 * 00974 * 00975 * @todo Are we going to support copying when urls are not on the same 00976 * share? I say no... NOTE. I agree for the moment. 00977 * 00978 */ 00979 int smbc_rename(const char *ourl, const char *nurl); 00980 00981 00982 /**@ingroup directory 00983 * Open a directory used to obtain directory entries. 00984 * 00985 * @param durl The smb url of the directory to open 00986 * 00987 * @return Valid directory handle. < 0 on error with errno set: 00988 * - EACCES Permission denied. 00989 * - EINVAL A NULL file/URL was passed, or the URL would 00990 * not parse, or was of incorrect form or smbc_init not 00991 * called. 00992 * - ENOENT durl does not exist, or name is an 00993 * - ENOMEM Insufficient memory to complete the 00994 * operation. 00995 * - ENOTDIR name is not a directory. 00996 * - EPERM the workgroup could not be found. 00997 * - ENODEV the workgroup or server could not be found. 00998 * 00999 * @see smbc_getdents(), smbc_readdir(), smbc_closedir() 01000 * 01001 */ 01002 int smbc_opendir(const char *durl); 01003 01004 01005 /**@ingroup directory 01006 * Close a directory handle opened by smbc_opendir(). 01007 * 01008 * @param dh Directory handle to close 01009 * 01010 * @return 0 on success, < 0 on error with errno set: 01011 * - EBADF dh is an invalid directory handle 01012 * 01013 * @see smbc_opendir() 01014 */ 01015 int smbc_closedir(int dh); 01016 01017 01018 /**@ingroup directory 01019 * Get multiple directory entries. 01020 * 01021 * smbc_getdents() reads as many dirent structures from the an open 01022 * directory handle into a specified memory area as will fit. 01023 * 01024 * @param dh Valid directory as returned by smbc_opendir() 01025 * 01026 * @param dirp pointer to buffer that will receive the directory 01027 * entries. 01028 * 01029 * @param count The size of the dirp buffer in bytes 01030 * 01031 * @returns If any dirents returned, return will indicate the 01032 * total size. If there were no more dirents available, 01033 * 0 is returned. < 0 indicates an error. 01034 * - EBADF Invalid directory handle 01035 * - EINVAL Result buffer is too small or smbc_init 01036 * not called. 01037 * - ENOENT No such directory. 01038 * @see , smbc_dirent, smbc_readdir(), smbc_open() 01039 * 01040 * @todo Are errno values complete and correct? 01041 * 01042 * @todo Add example code so people know how to parse buffers. 01043 */ 01044 int smbc_getdents(unsigned int dh, struct smbc_dirent *dirp, int count); 01045 01046 01047 /**@ingroup directory 01048 * Get a single directory entry. 01049 * 01050 * @param dh Valid directory as returned by smbc_opendir() 01051 * 01052 * @return A pointer to a smbc_dirent structure, or NULL if an 01053 * error occurs or end-of-directory is reached: 01054 * - EBADF Invalid directory handle 01055 * - EINVAL smbc_init() failed or has not been called 01056 * 01057 * @see smbc_dirent, smbc_getdents(), smbc_open() 01058 */ 01059 struct smbc_dirent* smbc_readdir(unsigned int dh); 01060 01061 01062 /**@ingroup directory 01063 * Get the current directory offset. 01064 * 01065 * smbc_telldir() may be used in conjunction with smbc_readdir() and 01066 * smbc_lseekdir(). 01067 * 01068 * @param dh Valid directory as returned by smbc_opendir() 01069 * 01070 * @return The current location in the directory stream or -1 01071 * if an error occur. The current location is not 01072 * an offset. Becuase of the implementation, it is a 01073 * handle that allows the library to find the entry 01074 * later. 01075 * - EBADF dh is not a valid directory handle 01076 * - EINVAL smbc_init() failed or has not been called 01077 * - ENOTDIR if dh is not a directory 01078 * 01079 * @see smbc_readdir() 01080 * 01081 */ 01082 off_t smbc_telldir(int dh); 01083 01084 01085 /**@ingroup directory 01086 * lseek on directories. 01087 * 01088 * smbc_lseekdir() may be used in conjunction with smbc_readdir() and 01089 * smbc_telldir(). (rewind by smbc_lseekdir(fd, NULL)) 01090 * 01091 * @param fd Valid directory as returned by smbc_opendir() 01092 * 01093 * @param offset The offset (as returned by smbc_telldir). Can be 01094 * NULL, in which case we will rewind 01095 * 01096 * @return 0 on success, -1 on failure 01097 * - EBADF dh is not a valid directory handle 01098 * - ENOTDIR if dh is not a directory 01099 * - EINVAL offset did not refer to a valid dirent or 01100 * smbc_init not called. 01101 * 01102 * @see smbc_telldir() 01103 * 01104 * 01105 * @todo In what does the reture and errno values mean? 01106 */ 01107 int smbc_lseekdir(int fd, off_t offset); 01108 01109 /**@ingroup directory 01110 * Create a directory. 01111 * 01112 * @param durl The url of the directory to create 01113 * 01114 * @param mode Specifies the permissions to use. It is modified 01115 * by the process's umask in the usual way: the 01116 * permissions of the created file are (mode & ~umask). 01117 * 01118 * @return 0 on success, < 0 on error with errno set: 01119 * - EEXIST directory url already exists 01120 * - EACCES The parent directory does not allow write 01121 * permission to the process, or one of the directories 01122 * - ENOENT A directory component in pathname does not 01123 * exist. 01124 * - EINVAL NULL durl passed or smbc_init not called. 01125 * - ENOMEM Insufficient memory was available. 01126 * 01127 * @see smbc_rmdir() 01128 * 01129 */ 01130 int smbc_mkdir(const char *durl, mode_t mode); 01131 01132 01133 /**@ingroup directory 01134 * Remove a directory. 01135 * 01136 * @param durl The smb url of the directory to remove 01137 * 01138 * @return 0 on success, < 0 on error with errno set: 01139 * - EACCES or EPERM Write access to the directory 01140 * containing pathname was not allowed. 01141 * - EINVAL durl is NULL or smbc_init not called. 01142 * - ENOENT A directory component in pathname does not 01143 * exist. 01144 * - ENOTEMPTY directory contains entries. 01145 * - ENOMEM Insufficient kernel memory was available. 01146 * 01147 * @see smbc_mkdir(), smbc_unlink() 01148 * 01149 * @todo Are errno values complete and correct? 01150 */ 01151 int smbc_rmdir(const char *durl); 01152 01153 01154 /**@ingroup attribute 01155 * Get information about a file or directory. 01156 * 01157 * @param url The smb url to get information for 01158 * 01159 * @param st pointer to a buffer that will be filled with 01160 * standard Unix struct stat information. 01161 * 01162 * @return 0 on success, < 0 on error with errno set: 01163 * - ENOENT A component of the path file_name does not 01164 * exist. 01165 * - EINVAL a NULL url was passed or smbc_init not called. 01166 * - EACCES Permission denied. 01167 * - ENOMEM Out of memory 01168 * - ENOTDIR The target dir, url, is not a directory. 01169 * 01170 * @see Unix stat() 01171 * 01172 */ 01173 int smbc_stat(const char *url, struct stat *st); 01174 01175 01176 /**@ingroup attribute 01177 * Get file information via an file descriptor. 01178 * 01179 * @param fd Open file handle from smbc_open() or smbc_creat() 01180 * 01181 * @param st pointer to a buffer that will be filled with 01182 * standard Unix struct stat information. 01183 * 01184 * @return EBADF filedes is bad. 01185 * - EACCES Permission denied. 01186 * - EBADF fd is not a valid file descriptor 01187 * - EINVAL Problems occurred in the underlying routines 01188 * or smbc_init not called. 01189 * - ENOMEM Out of memory 01190 * 01191 * @see smbc_stat(), Unix stat() 01192 * 01193 */ 01194 int smbc_fstat(int fd, struct stat *st); 01195 01196 01197 /**@ingroup attribue 01198 * Change the ownership of a file or directory. 01199 * 01200 * @param url The smb url of the file or directory to change 01201 * ownership of. 01202 * 01203 * @param owner I have no idea? 01204 * 01205 * @param group I have not idea? 01206 * 01207 * @return 0 on success, < 0 on error with errno set: 01208 * - EPERM The effective UID does not match the owner 01209 * of the file, and is not zero; or the owner or group 01210 * were specified incorrectly. 01211 * - ENOENT The file does not exist. 01212 * - ENOMEM Insufficient was available. 01213 * - ENOENT file or directory does not exist 01214 * 01215 * @todo Are we actually going to be able to implement this function 01216 * 01217 * @todo How do we abstract owner and group uid and gid? 01218 * 01219 */ 01220 int smbc_chown(const char *url, uid_t owner, gid_t group); 01221 01222 01223 /**@ingroup attribute 01224 * Change the permissions of a file. 01225 * 01226 * @param url The smb url of the file or directory to change 01227 * permissions of 01228 * 01229 * @param mode The permissions to set: 01230 * - Put good explaination of permissions here! 01231 * 01232 * @return 0 on success, < 0 on error with errno set: 01233 * - EPERM The effective UID does not match the owner 01234 * of the file, and is not zero 01235 * - ENOENT The file does not exist. 01236 * - ENOMEM Insufficient was available. 01237 * - ENOENT file or directory does not exist 01238 * 01239 * @todo Actually implement this fuction? 01240 * 01241 * @todo Are errno values complete and correct? 01242 */ 01243 int smbc_chmod(const char *url, mode_t mode); 01244 01245 /**@ingroup attribute 01246 * Change the last modification time on a file 01247 * 01248 * @param url The smb url of the file or directory to change 01249 * the modification time of 01250 * 01251 * @param tbuf A timeval structure which contains the desired 01252 * modification time. NOTE: Only the tv_sec field is 01253 * used. The tv_usec (microseconds) portion is ignored. 01254 * 01255 * @return 0 on success, < 0 on error with errno set: 01256 * - EINVAL The client library is not properly initialized 01257 * - EPERM Permission was denied. 01258 * 01259 */ 01260 int smbc_utimes(const char *url, struct timeval *tbuf); 01261 01262 #ifdef HAVE_UTIME_H 01263 /**@ingroup attribute 01264 * Change the last modification time on a file 01265 * 01266 * @param url The smb url of the file or directory to change 01267 * the modification time of 01268 * 01269 * @param utbuf A utimebuf structure which contains the desired 01270 * modification time. NOTE: Although the structure contains 01271 * an access time as well, the access time value is ignored. 01272 * 01273 * @return 0 on success, < 0 on error with errno set: 01274 * - EINVAL The client library is not properly initialized 01275 * - ENOMEM No memory was available for internal needs 01276 * - EPERM Permission was denied. 01277 * 01278 */ 01279 int smbc_utime(const char *fname, struct utimbuf *utbuf); 01280 #endif 01281 01282 /**@ingroup attribute 01283 * Set extended attributes for a file. This is used for modifying a file's 01284 * security descriptor (i.e. owner, group, and access control list) 01285 * 01286 * @param url The smb url of the file or directory to set extended 01287 * attributes for. 01288 * 01289 * @param name The name of an attribute to be changed. Names are of 01290 * one of the following forms: 01291 * 01292 * system.nt_sec_desc.<attribute name> 01293 * system.nt_sec_desc.* 01294 * system.nt_sec_desc.*+ 01295 * 01296 * where <attribute name> is one of: 01297 * 01298 * revision 01299 * owner 01300 * owner+ 01301 * group 01302 * group+ 01303 * acl:<name or sid> 01304 * acl+:<name or sid> 01305 * 01306 * In the forms "system.nt_sec_desc.*" and 01307 * "system.nt_sec_desc.*+", the asterisk and plus signs are 01308 * literal, i.e. the string is provided exactly as shown, and 01309 * the value parameter should contain a complete security 01310 * descriptor with name:value pairs separated by tabs, 01311 * commas, or newlines (not spaces!). 01312 * 01313 * The plus sign ('+') indicates that SIDs should be mapped 01314 * to names. Without the plus sign, SIDs are not mapped; 01315 * rather they are simply converted to a string format. 01316 * 01317 * @param value The value to be assigned to the specified attribute name. 01318 * This buffer should contain only the attribute value if the 01319 * name was of the "system.nt_sec_desc.<attribute_name>" 01320 * form. If the name was of the "system.nt_sec_desc.*" form 01321 * then a complete security descriptor, with name:value pairs 01322 * separated by tabs, commas, or newlines (not spaces!), 01323 * should be provided in this value buffer. A complete 01324 * security descriptor will contain one or more entries 01325 * selected from the following: 01326 * 01327 * REVISION:<revision number> 01328 * OWNER:<sid or name> 01329 * GROUP:<sid or name> 01330 * ACL:<sid or name>:<type>/<flags>/<mask> 01331 * 01332 * The revision of the ACL specifies the internal Windows NT 01333 * ACL revision for the security descriptor. If not specified 01334 * it defaults to 1. Using values other than 1 may cause 01335 * strange behaviour. 01336 * 01337 * The owner and group specify the owner and group sids for 01338 * the object. If the attribute name (either '*+' with a 01339 * complete security descriptor, or individual 'owner+' or 01340 * 'group+' attribute names) ended with a plus sign, the 01341 * specified name is resolved to a SID value, using the 01342 * server on which the file or directory resides. Otherwise, 01343 * the value should be provided in SID-printable format as 01344 * S-1-x-y-z, and is used directly. The <sid or name> 01345 * associated with the ACL: attribute should be provided 01346 * similarly. 01347 * 01348 * @param size The number of the bytes of data in the value buffer 01349 * 01350 * @param flags A bit-wise OR of zero or more of the following: 01351 * SMBC_XATTR_FLAG_CREATE - 01352 * fail if the named attribute already exists 01353 * SMBC_XATTR_FLAG_REPLACE - 01354 * fail if the attribute does not already exist 01355 * 01356 * If neither flag is specified, the specified attributes 01357 * will be added or replace existing attributes of the same 01358 * name, as necessary. 01359 * 01360 * @return 0 on success, < 0 on error with errno set: 01361 * - EINVAL The client library is not properly initialized 01362 * or one of the parameters is not of a correct 01363 * form 01364 * - ENOMEM No memory was available for internal needs 01365 * - EEXIST If the attribute already exists and the flag 01366 * SMBC_XATTR_FLAG_CREAT was specified 01367 * - ENOATTR If the attribute does not exist and the flag 01368 * SMBC_XATTR_FLAG_REPLACE was specified 01369 * - EPERM Permission was denied. 01370 * - ENOTSUP The referenced file system does not support 01371 * extended attributes 01372 * 01373 * @note Attribute names are compared in a case-insensitive 01374 * fashion. All of the following are equivalent, although 01375 * the all-lower-case name is the preferred format: 01376 * system.nt_sec_desc.owner 01377 * SYSTEM.NT_SEC_DESC.OWNER 01378 * sYsTeM.nt_sEc_desc.owNER 01379 * 01380 */ 01381 int smbc_setxattr(const char *url, 01382 const char *name, 01383 const void *value, 01384 size_t size, 01385 int flags); 01386 01387 01388 /**@ingroup attribute 01389 * Set extended attributes for a file. This is used for modifying a file's 01390 * security descriptor (i.e. owner, group, and access control list). The 01391 * POSIX function which this maps to would act on a symbolic link rather than 01392 * acting on what the symbolic link points to, but with no symbolic links in 01393 * SMB file systems, this function is functionally identical to 01394 * smbc_setxattr(). 01395 * 01396 * @param url The smb url of the file or directory to set extended 01397 * attributes for. 01398 * 01399 * @param name The name of an attribute to be changed. Names are of 01400 * one of the following forms: 01401 * 01402 * system.nt_sec_desc.<attribute name> 01403 * system.nt_sec_desc.* 01404 * system.nt_sec_desc.*+ 01405 * 01406 * where <attribute name> is one of: 01407 * 01408 * revision 01409 * owner 01410 * owner+ 01411 * group 01412 * group+ 01413 * acl:<name or sid> 01414 * acl+:<name or sid> 01415 * 01416 * In the forms "system.nt_sec_desc.*" and 01417 * "system.nt_sec_desc.*+", the asterisk and plus signs are 01418 * literal, i.e. the string is provided exactly as shown, and 01419 * the value parameter should contain a complete security 01420 * descriptor with name:value pairs separated by tabs, 01421 * commas, or newlines (not spaces!). 01422 * 01423 * The plus sign ('+') indicates that SIDs should be mapped 01424 * to names. Without the plus sign, SIDs are not mapped; 01425 * rather they are simply converted to a string format. 01426 * 01427 * @param value The value to be assigned to the specified attribute name. 01428 * This buffer should contain only the attribute value if the 01429 * name was of the "system.nt_sec_desc.<attribute_name>" 01430 * form. If the name was of the "system.nt_sec_desc.*" form 01431 * then a complete security descriptor, with name:value pairs 01432 * separated by tabs, commas, or newlines (not spaces!), 01433 * should be provided in this value buffer. A complete 01434 * security descriptor will contain one or more entries 01435 * selected from the following: 01436 * 01437 * REVISION:<revision number> 01438 * OWNER:<sid or name> 01439 * GROUP:<sid or name> 01440 * ACL:<sid or name>:<type>/<flags>/<mask> 01441 * 01442 * The revision of the ACL specifies the internal Windows NT 01443 * ACL revision for the security descriptor. If not specified 01444 * it defaults to 1. Using values other than 1 may cause 01445 * strange behaviour. 01446 * 01447 * The owner and group specify the owner and group sids for 01448 * the object. If the attribute name (either '*+' with a 01449 * complete security descriptor, or individual 'owner+' or 01450 * 'group+' attribute names) ended with a plus sign, the 01451 * specified name is resolved to a SID value, using the 01452 * server on which the file or directory resides. Otherwise, 01453 * the value should be provided in SID-printable format as 01454 * S-1-x-y-z, and is used directly. The <sid or name> 01455 * associated with the ACL: attribute should be provided 01456 * similarly. 01457 * 01458 * @param size The number of the bytes of data in the value buffer 01459 * 01460 * @param flags A bit-wise OR of zero or more of the following: 01461 * SMBC_XATTR_FLAG_CREATE - 01462 * fail if the named attribute already exists 01463 * SMBC_XATTR_FLAG_REPLACE - 01464 * fail if the attribute does not already exist 01465 * 01466 * If neither flag is specified, the specified attributes 01467 * will be added or replace existing attributes of the same 01468 * name, as necessary. 01469 * 01470 * @return 0 on success, < 0 on error with errno set: 01471 * - EINVAL The client library is not properly initialized 01472 * or one of the parameters is not of a correct 01473 * form 01474 * - ENOMEM No memory was available for internal needs 01475 * - EEXIST If the attribute already exists and the flag 01476 * SMBC_XATTR_FLAG_CREAT was specified 01477 * - ENOATTR If the attribute does not exist and the flag 01478 * SMBC_XATTR_FLAG_REPLACE was specified 01479 * - EPERM Permission was denied. 01480 * - ENOTSUP The referenced file system does not support 01481 * extended attributes 01482 * 01483 * @note Attribute names are compared in a case-insensitive 01484 * fashion. All of the following are equivalent, although 01485 * the all-lower-case name is the preferred format: 01486 * system.nt_sec_desc.owner 01487 * SYSTEM.NT_SEC_DESC.OWNER 01488 * sYsTeM.nt_sEc_desc.owNER 01489 * 01490 */ 01491 int smbc_lsetxattr(const char *url, 01492 const char *name, 01493 const void *value, 01494 size_t size, 01495 int flags); 01496 01497 01498 /**@ingroup attribute 01499 * Set extended attributes for a file. This is used for modifying a file's 01500 * security descriptor (i.e. owner, group, and access control list) 01501 * 01502 * @param fd A file descriptor associated with an open file (as 01503 * previously returned by smbc_open(), to get extended 01504 * attributes for. 01505 * 01506 * @param name The name of an attribute to be changed. Names are of 01507 * one of the following forms: 01508 * 01509 * system.nt_sec_desc.<attribute name> 01510 * system.nt_sec_desc.* 01511 * system.nt_sec_desc.*+ 01512 * 01513 * where <attribute name> is one of: 01514 * 01515 * revision 01516 * owner 01517 * owner+ 01518 * group 01519 * group+ 01520 * acl:<name or sid> 01521 * acl+:<name or sid> 01522 * 01523 * In the forms "system.nt_sec_desc.*" and 01524 * "system.nt_sec_desc.*+", the asterisk and plus signs are 01525 * literal, i.e. the string is provided exactly as shown, and 01526 * the value parameter should contain a complete security 01527 * descriptor with name:value pairs separated by tabs, 01528 * commas, or newlines (not spaces!). 01529 * 01530 * The plus sign ('+') indicates that SIDs should be mapped 01531 * to names. Without the plus sign, SIDs are not mapped; 01532 * rather they are simply converted to a string format. 01533 * 01534 * @param value The value to be assigned to the specified attribute name. 01535 * This buffer should contain only the attribute value if the 01536 * name was of the "system.nt_sec_desc.<attribute_name>" 01537 * form. If the name was of the "system.nt_sec_desc.*" form 01538 * then a complete security descriptor, with name:value pairs 01539 * separated by tabs, commas, or newlines (not spaces!), 01540 * should be provided in this value buffer. A complete 01541 * security descriptor will contain one or more entries 01542 * selected from the following: 01543 * 01544 * REVISION:<revision number> 01545 * OWNER:<sid or name> 01546 * GROUP:<sid or name> 01547 * ACL:<sid or name>:<type>/<flags>/<mask> 01548 * 01549 * The revision of the ACL specifies the internal Windows NT 01550 * ACL revision for the security descriptor. If not specified 01551 * it defaults to 1. Using values other than 1 may cause 01552 * strange behaviour. 01553 * 01554 * The owner and group specify the owner and group sids for 01555 * the object. If the attribute name (either '*+' with a 01556 * complete security descriptor, or individual 'owner+' or 01557 * 'group+' attribute names) ended with a plus sign, the 01558 * specified name is resolved to a SID value, using the 01559 * server on which the file or directory resides. Otherwise, 01560 * the value should be provided in SID-printable format as 01561 * S-1-x-y-z, and is used directly. The <sid or name> 01562 * associated with the ACL: attribute should be provided 01563 * similarly. 01564 * 01565 * @param size The number of the bytes of data in the value buffer 01566 * 01567 * @param flags A bit-wise OR of zero or more of the following: 01568 * SMBC_XATTR_FLAG_CREATE - 01569 * fail if the named attribute already exists 01570 * SMBC_XATTR_FLAG_REPLACE - 01571 * fail if the attribute does not already exist 01572 * 01573 * If neither flag is specified, the specified attributes 01574 * will be added or replace existing attributes of the same 01575 * name, as necessary. 01576 * 01577 * @return 0 on success, < 0 on error with errno set: 01578 * - EINVAL The client library is not properly initialized 01579 * or one of the parameters is not of a correct 01580 * form 01581 * - ENOMEM No memory was available for internal needs 01582 * - EEXIST If the attribute already exists and the flag 01583 * SMBC_XATTR_FLAG_CREAT was specified 01584 * - ENOATTR If the attribute does not exist and the flag 01585 * SMBC_XATTR_FLAG_REPLACE was specified 01586 * - EPERM Permission was denied. 01587 * - ENOTSUP The referenced file system does not support 01588 * extended attributes 01589 * 01590 * @note Attribute names are compared in a case-insensitive 01591 * fashion. All of the following are equivalent, although 01592 * the all-lower-case name is the preferred format: 01593 * system.nt_sec_desc.owner 01594 * SYSTEM.NT_SEC_DESC.OWNER 01595 * sYsTeM.nt_sEc_desc.owNER 01596 * 01597 */ 01598 int smbc_fsetxattr(int fd, 01599 const char *name, 01600 const void *value, 01601 size_t size, 01602 int flags); 01603 01604 01605 /**@ingroup attribute 01606 * Get extended attributes for a file. 01607 * 01608 * @param url The smb url of the file or directory to get extended 01609 * attributes for. 01610 * 01611 * @param name The name of an attribute to be retrieved. Names are of 01612 * one of the following forms: 01613 * 01614 * system.nt_sec_desc.<attribute name> 01615 * system.nt_sec_desc.* 01616 * system.nt_sec_desc.*+ 01617 * 01618 * where <attribute name> is one of: 01619 * 01620 * revision 01621 * owner 01622 * owner+ 01623 * group 01624 * group+ 01625 * acl:<name or sid> 01626 * acl+:<name or sid> 01627 * 01628 * In the forms "system.nt_sec_desc.*" and 01629 * "system.nt_sec_desc.*+", the asterisk and plus signs are 01630 * literal, i.e. the string is provided exactly as shown, and 01631 * the value parameter will return a complete security 01632 * descriptor with name:value pairs separated by tabs, 01633 * commas, or newlines (not spaces!). 01634 * 01635 * The plus sign ('+') indicates that SIDs should be mapped 01636 * to names. Without the plus sign, SIDs are not mapped; 01637 * rather they are simply converted to a string format. 01638 * 01639 * @param value A pointer to a buffer in which the value of the specified 01640 * attribute will be placed (unless size is zero). 01641 * 01642 * @param size The size of the buffer pointed to by value. This parameter 01643 * may also be zero, in which case the size of the buffer 01644 * required to hold the attribute value will be returned, 01645 * but nothing will be placed into the value buffer. 01646 * 01647 * @return 0 on success, < 0 on error with errno set: 01648 * - EINVAL The client library is not properly initialized 01649 * or one of the parameters is not of a correct 01650 * form 01651 * - ENOMEM No memory was available for internal needs 01652 * - EEXIST If the attribute already exists and the flag 01653 * SMBC_XATTR_FLAG_CREAT was specified 01654 * - ENOATTR If the attribute does not exist and the flag 01655 * SMBC_XATTR_FLAG_REPLACE was specified 01656 * - EPERM Permission was denied. 01657 * - ENOTSUP The referenced file system does not support 01658 * extended attributes 01659 * 01660 */ 01661 int smbc_getxattr(const char *url, 01662 const char *name, 01663 const void *value, 01664 size_t size); 01665 01666 01667 /**@ingroup attribute 01668 * Get extended attributes for a file. The POSIX function which this maps to 01669 * would act on a symbolic link rather than acting on what the symbolic link 01670 * points to, but with no symbolic links in SMB file systems, this function 01671 * is functionally identical to smbc_getxattr(). 01672 * 01673 * @param url The smb url of the file or directory to get extended 01674 * attributes for. 01675 * 01676 * @param name The name of an attribute to be retrieved. Names are of 01677 * one of the following forms: 01678 * 01679 * system.nt_sec_desc.<attribute name> 01680 * system.nt_sec_desc.* 01681 * system.nt_sec_desc.*+ 01682 * 01683 * where <attribute name> is one of: 01684 * 01685 * revision 01686 * owner 01687 * owner+ 01688 * group 01689 * group+ 01690 * acl:<name or sid> 01691 * acl+:<name or sid> 01692 * 01693 * In the forms "system.nt_sec_desc.*" and 01694 * "system.nt_sec_desc.*+", the asterisk and plus signs are 01695 * literal, i.e. the string is provided exactly as shown, and 01696 * the value parameter will return a complete security 01697 * descriptor with name:value pairs separated by tabs, 01698 * commas, or newlines (not spaces!). 01699 * 01700 * The plus sign ('+') indicates that SIDs should be mapped 01701 * to names. Without the plus sign, SIDs are not mapped; 01702 * rather they are simply converted to a string format. 01703 * 01704 * @param value A pointer to a buffer in which the value of the specified 01705 * attribute will be placed (unless size is zero). 01706 * 01707 * @param size The size of the buffer pointed to by value. This parameter 01708 * may also be zero, in which case the size of the buffer 01709 * required to hold the attribute value will be returned, 01710 * but nothing will be placed into the value buffer. 01711 * 01712 * @return 0 on success, < 0 on error with errno set: 01713 * - EINVAL The client library is not properly initialized 01714 * or one of the parameters is not of a correct 01715 * form 01716 * - ENOMEM No memory was available for internal needs 01717 * - EEXIST If the attribute already exists and the flag 01718 * SMBC_XATTR_FLAG_CREAT was specified 01719 * - ENOATTR If the attribute does not exist and the flag 01720 * SMBC_XATTR_FLAG_REPLACE was specified 01721 * - EPERM Permission was denied. 01722 * - ENOTSUP The referenced file system does not support 01723 * extended attributes 01724 * 01725 */ 01726 int smbc_lgetxattr(const char *url, 01727 const char *name, 01728 const void *value, 01729 size_t size); 01730 01731 01732 /**@ingroup attribute 01733 * Get extended attributes for a file. 01734 * 01735 * @param fd A file descriptor associated with an open file (as 01736 * previously returned by smbc_open(), to get extended 01737 * attributes for. 01738 * 01739 * @param name The name of an attribute to be retrieved. Names are of 01740 * one of the following forms: 01741 * 01742 * system.nt_sec_desc.<attribute name> 01743 * system.nt_sec_desc.* 01744 * system.nt_sec_desc.*+ 01745 * 01746 * where <attribute name> is one of: 01747 * 01748 * revision 01749 * owner 01750 * owner+ 01751 * group 01752 * group+ 01753 * acl:<name or sid> 01754 * acl+:<name or sid> 01755 * 01756 * In the forms "system.nt_sec_desc.*" and 01757 * "system.nt_sec_desc.*+", the asterisk and plus signs are 01758 * literal, i.e. the string is provided exactly as shown, and 01759 * the value parameter will return a complete security 01760 * descriptor with name:value pairs separated by tabs, 01761 * commas, or newlines (not spaces!). 01762 * 01763 * The plus sign ('+') indicates that SIDs should be mapped 01764 * to names. Without the plus sign, SIDs are not mapped; 01765 * rather they are simply converted to a string format. 01766 * 01767 * @param value A pointer to a buffer in which the value of the specified 01768 * attribute will be placed (unless size is zero). 01769 * 01770 * @param size The size of the buffer pointed to by value. This parameter 01771 * may also be zero, in which case the size of the buffer 01772 * required to hold the attribute value will be returned, 01773 * but nothing will be placed into the value buffer. 01774 * 01775 * @return 0 on success, < 0 on error with errno set: 01776 * - EINVAL The client library is not properly initialized 01777 * or one of the parameters is not of a correct 01778 * form 01779 * - ENOMEM No memory was available for internal needs 01780 * - EEXIST If the attribute already exists and the flag 01781 * SMBC_XATTR_FLAG_CREAT was specified 01782 * - ENOATTR If the attribute does not exist and the flag 01783 * SMBC_XATTR_FLAG_REPLACE was specified 01784 * - EPERM Permission was denied. 01785 * - ENOTSUP The referenced file system does not support 01786 * extended attributes 01787 * 01788 */ 01789 int smbc_fgetxattr(int fd, 01790 const char *name, 01791 const void *value, 01792 size_t size); 01793 01794 01795 /**@ingroup attribute 01796 * Remove extended attributes for a file. This is used for modifying a file's 01797 * security descriptor (i.e. owner, group, and access control list) 01798 * 01799 * @param url The smb url of the file or directory to remove the extended 01800 * attributes for. 01801 * 01802 * @param name The name of an attribute to be removed. Names are of 01803 * one of the following forms: 01804 * 01805 * system.nt_sec_desc.<attribute name> 01806 * system.nt_sec_desc.* 01807 * system.nt_sec_desc.*+ 01808 * 01809 * where <attribute name> is one of: 01810 * 01811 * revision 01812 * owner 01813 * owner+ 01814 * group 01815 * group+ 01816 * acl:<name or sid> 01817 * acl+:<name or sid> 01818 * 01819 * In the forms "system.nt_sec_desc.*" and 01820 * "system.nt_sec_desc.*+", the asterisk and plus signs are 01821 * literal, i.e. the string is provided exactly as shown, and 01822 * the value parameter will return a complete security 01823 * descriptor with name:value pairs separated by tabs, 01824 * commas, or newlines (not spaces!). 01825 * 01826 * The plus sign ('+') indicates that SIDs should be mapped 01827 * to names. Without the plus sign, SIDs are not mapped; 01828 * rather they are simply converted to a string format. 01829 * 01830 * @return 0 on success, < 0 on error with errno set: 01831 * - EINVAL The client library is not properly initialized 01832 * - ENOMEM No memory was available for internal needs 01833 * - EPERM Permission was denied. 01834 * - ENOTSUP The referenced file system does not support 01835 * extended attributes 01836 * 01837 */ 01838 int smbc_removexattr(const char *url, 01839 const char *name); 01840 01841 01842 /**@ingroup attribute 01843 * Remove extended attributes for a file. This is used for modifying a file's 01844 * security descriptor (i.e. owner, group, and access control list) The POSIX 01845 * function which this maps to would act on a symbolic link rather than acting 01846 * on what the symbolic link points to, but with no symbolic links in SMB file 01847 * systems, this function is functionally identical to smbc_removexattr(). 01848 * 01849 * @param url The smb url of the file or directory to remove the extended 01850 * attributes for. 01851 * 01852 * @param name The name of an attribute to be removed. Names are of 01853 * one of the following forms: 01854 * 01855 * system.nt_sec_desc.<attribute name> 01856 * system.nt_sec_desc.* 01857 * system.nt_sec_desc.*+ 01858 * 01859 * where <attribute name> is one of: 01860 * 01861 * revision 01862 * owner 01863 * owner+ 01864 * group 01865 * group+ 01866 * acl:<name or sid> 01867 * acl+:<name or sid> 01868 * 01869 * In the forms "system.nt_sec_desc.*" and 01870 * "system.nt_sec_desc.*+", the asterisk and plus signs are 01871 * literal, i.e. the string is provided exactly as shown, and 01872 * the value parameter will return a complete security 01873 * descriptor with name:value pairs separated by tabs, 01874 * commas, or newlines (not spaces!). 01875 * 01876 * The plus sign ('+') indicates that SIDs should be mapped 01877 * to names. Without the plus sign, SIDs are not mapped; 01878 * rather they are simply converted to a string format. 01879 * 01880 * @return 0 on success, < 0 on error with errno set: 01881 * - EINVAL The client library is not properly initialized 01882 * - ENOMEM No memory was available for internal needs 01883 * - EPERM Permission was denied. 01884 * - ENOTSUP The referenced file system does not support 01885 * extended attributes 01886 * 01887 */ 01888 int smbc_lremovexattr(const char *url, 01889 const char *name); 01890 01891 01892 /**@ingroup attribute 01893 * Remove extended attributes for a file. This is used for modifying a file's 01894 * security descriptor (i.e. owner, group, and access control list) 01895 * 01896 * @param fd A file descriptor associated with an open file (as 01897 * previously returned by smbc_open(), to get extended 01898 * attributes for. 01899 * 01900 * @param name The name of an attribute to be removed. Names are of 01901 * one of the following forms: 01902 * 01903 * system.nt_sec_desc.<attribute name> 01904 * system.nt_sec_desc.* 01905 * system.nt_sec_desc.*+ 01906 * 01907 * where <attribute name> is one of: 01908 * 01909 * revision 01910 * owner 01911 * owner+ 01912 * group 01913 * group+ 01914 * acl:<name or sid> 01915 * acl+:<name or sid> 01916 * 01917 * In the forms "system.nt_sec_desc.*" and 01918 * "system.nt_sec_desc.*+", the asterisk and plus signs are 01919 * literal, i.e. the string is provided exactly as shown, and 01920 * the value parameter will return a complete security 01921 * descriptor with name:value pairs separated by tabs, 01922 * commas, or newlines (not spaces!). 01923 * 01924 * The plus sign ('+') indicates that SIDs should be mapped 01925 * to names. Without the plus sign, SIDs are not mapped; 01926 * rather they are simply converted to a string format. 01927 * 01928 * @return 0 on success, < 0 on error with errno set: 01929 * - EINVAL The client library is not properly initialized 01930 * - ENOMEM No memory was available for internal needs 01931 * - EPERM Permission was denied. 01932 * - ENOTSUP The referenced file system does not support 01933 * extended attributes 01934 * 01935 */ 01936 int smbc_fremovexattr(int fd, 01937 const char *name); 01938 01939 01940 /**@ingroup attribute 01941 * List the supported extended attribute names associated with a file 01942 * 01943 * @param url The smb url of the file or directory to list the extended 01944 * attributes for. 01945 * 01946 * @param list A pointer to a buffer in which the list of attributes for 01947 * the specified file or directory will be placed (unless 01948 * size is zero). 01949 * 01950 * @param size The size of the buffer pointed to by list. This parameter 01951 * may also be zero, in which case the size of the buffer 01952 * required to hold all of the attribute names will be 01953 * returned, but nothing will be placed into the list buffer. 01954 * 01955 * @return 0 on success, < 0 on error with errno set: 01956 * - EINVAL The client library is not properly initialized 01957 * - ENOMEM No memory was available for internal needs 01958 * - EPERM Permission was denied. 01959 * - ENOTSUP The referenced file system does not support 01960 * extended attributes 01961 * 01962 * @note This function always returns all attribute names supported 01963 * by NT file systems, regardless of wether the referenced 01964 * file system supports extended attributes (e.g. a Windows 01965 * 2000 machine supports extended attributes if NTFS is used, 01966 * but not if FAT is used, and Windows 98 doesn't support 01967 * extended attributes at all. Whether this is a feature or 01968 * a bug is yet to be decided. 01969 */ 01970 int smbc_listxattr(const char *url, 01971 char *list, 01972 size_t size); 01973 01974 /**@ingroup attribute 01975 * List the supported extended attribute names associated with a file The 01976 * POSIX function which this maps to would act on a symbolic link rather than 01977 * acting on what the symbolic link points to, but with no symbolic links in 01978 * SMB file systems, this function is functionally identical to 01979 * smbc_listxattr(). 01980 * 01981 * @param url The smb url of the file or directory to list the extended 01982 * attributes for. 01983 * 01984 * @param list A pointer to a buffer in which the list of attributes for 01985 * the specified file or directory will be placed (unless 01986 * size is zero). 01987 * 01988 * @param size The size of the buffer pointed to by list. This parameter 01989 * may also be zero, in which case the size of the buffer 01990 * required to hold all of the attribute names will be 01991 * returned, but nothing will be placed into the list buffer. 01992 * 01993 * @return 0 on success, < 0 on error with errno set: 01994 * - EINVAL The client library is not properly initialized 01995 * - ENOMEM No memory was available for internal needs 01996 * - EPERM Permission was denied. 01997 * - ENOTSUP The referenced file system does not support 01998 * extended attributes 01999 * 02000 * @note This function always returns all attribute names supported 02001 * by NT file systems, regardless of wether the referenced 02002 * file system supports extended attributes (e.g. a Windows 02003 * 2000 machine supports extended attributes if NTFS is used, 02004 * but not if FAT is used, and Windows 98 doesn't support 02005 * extended attributes at all. Whether this is a feature or 02006 * a bug is yet to be decided. 02007 */ 02008 int smbc_llistxattr(const char *url, 02009 char *list, 02010 size_t size); 02011 02012 /**@ingroup attribute 02013 * List the supported extended attribute names associated with a file 02014 * 02015 * @param fd A file descriptor associated with an open file (as 02016 * previously returned by smbc_open(), to get extended 02017 * attributes for. 02018 * 02019 * @param list A pointer to a buffer in which the list of attributes for 02020 * the specified file or directory will be placed (unless 02021 * size is zero). 02022 * 02023 * @param size The size of the buffer pointed to by list. This parameter 02024 * may also be zero, in which case the size of the buffer 02025 * required to hold all of the attribute names will be 02026 * returned, but nothing will be placed into the list buffer. 02027 * 02028 * @return 0 on success, < 0 on error with errno set: 02029 * - EINVAL The client library is not properly initialized 02030 * - ENOMEM No memory was available for internal needs 02031 * - EPERM Permission was denied. 02032 * - ENOTSUP The referenced file system does not support 02033 * extended attributes 02034 * 02035 * @note This function always returns all attribute names supported 02036 * by NT file systems, regardless of wether the referenced 02037 * file system supports extended attributes (e.g. a Windows 02038 * 2000 machine supports extended attributes if NTFS is used, 02039 * but not if FAT is used, and Windows 98 doesn't support 02040 * extended attributes at all. Whether this is a feature or 02041 * a bug is yet to be decided. 02042 */ 02043 int smbc_flistxattr(int fd, 02044 char *list, 02045 size_t size); 02046 02047 /**@ingroup print 02048 * Print a file given the name in fname. It would be a URL ... 02049 * 02050 * @param fname The URL of a file on a remote SMB server that the 02051 * caller wants printed 02052 * 02053 * @param printq The URL of the print share to print the file to. 02054 * 02055 * @return 0 on success, < 0 on error with errno set: 02056 * 02057 * - EINVAL fname or printq was NULL or smbc_init not 02058 * not called. 02059 * and errors returned by smbc_open 02060 * 02061 */ 02062 int smbc_print_file(const char *fname, const char *printq); 02063 02064 /**@ingroup print 02065 * Open a print file that can be written to by other calls. This simply 02066 * does an smbc_open call after checking if there is a file name on the 02067 * URI. If not, a temporary name is added ... 02068 * 02069 * @param fname The URL of the print share to print to? 02070 * 02071 * @returns A file handle for the print file if successful. 02072 * Returns -1 if an error ocurred and errno has the values 02073 * - EINVAL fname was NULL or smbc_init not called. 02074 * - all errors returned by smbc_open 02075 * 02076 */ 02077 int smbc_open_print_job(const char *fname); 02078 02079 /**@ingroup print 02080 * List the print jobs on a print share, for the moment, pass a callback 02081 * 02082 * @param purl The url of the print share to list the jobs of 02083 * 02084 * @param fn Callback function the receives printjob info 02085 * 02086 * @return 0 on success, < 0 on error with errno set: 02087 * - EINVAL fname was NULL or smbc_init not called 02088 * - EACCES ??? 02089 */ 02090 int smbc_list_print_jobs(const char *purl, smbc_list_print_job_fn fn); 02091 02092 /**@ingroup print 02093 * Delete a print job 02094 * 02095 * @param purl Url of the print share 02096 * 02097 * @param id The id of the job to delete 02098 * 02099 * @return 0 on success, < 0 on error with errno set: 02100 * - EINVAL fname was NULL or smbc_init not called 02101 * 02102 * @todo what errno values are possible here? 02103 */ 02104 int smbc_unlink_print_job(const char *purl, int id); 02105 02106 /**@ingroup callback 02107 * Remove a server from the cached server list it's unused. 02108 * 02109 * @param context pointer to smb context 02110 * 02111 * @param srv pointer to server to remove 02112 * 02113 * @return On success, 0 is returned. 1 is returned if the server could not 02114 * be removed. Also useable outside libsmbclient. 02115 */ 02116 int smbc_remove_unused_server(SMBCCTX * context, SMBCSRV * srv); 02117 02118 #ifdef __cplusplus 02119 } 02120 #endif 02121 02122 /**@ingroup directory 02123 * Convert strings of %xx to their single character equivalent. 02124 * 02125 * @param dest A pointer to a buffer in which the resulting decoded 02126 * string should be placed. This may be a pointer to the 02127 * same buffer as src_segment. 02128 * 02129 * @param src A pointer to the buffer containing the URL to be decoded. 02130 * Any %xx sequences herein are converted to their single 02131 * character equivalent. Each 'x' must be a valid hexadecimal 02132 * digit, or that % sequence is left undecoded. 02133 * 02134 * @param max_dest_len 02135 * The size of the buffer pointed to by dest_segment. 02136 * 02137 * @return The number of % sequences which could not be converted 02138 * due to lack of two following hexadecimal digits. 02139 */ 02140 #ifdef __cplusplus 02141 extern "C" { 02142 #endif 02143 int 02144 smbc_urldecode(char *dest, char * src, size_t max_dest_len); 02145 #ifdef __cplusplus 02146 } 02147 #endif 02148 02149 02150 /* 02151 * Convert any characters not specifically allowed in a URL into their %xx 02152 * equivalent. 02153 * 02154 * @param dest A pointer to a buffer in which the resulting encoded 02155 * string should be placed. Unlike smbc_urldecode(), this 02156 * must be a buffer unique from src. 02157 * 02158 * @param src A pointer to the buffer containing the string to be encoded. 02159 * Any character not specifically allowed in a URL is converted 02160 * into its hexadecimal value and encoded as %xx. 02161 * 02162 * @param max_dest_len 02163 * The size of the buffer pointed to by dest_segment. 02164 * 02165 * @returns The remaining buffer length. 02166 */ 02167 #ifdef __cplusplus 02168 extern "C" { 02169 #endif 02170 int 02171 smbc_urlencode(char * dest, char * src, int max_dest_len); 02172 #ifdef __cplusplus 02173 } 02174 #endif 02175 02176 02177 /**@ingroup directory 02178 * Return the version of the linked Samba code, and thus the version of the 02179 * libsmbclient code. 02180 * 02181 * @return The version string. 02182 */ 02183 #ifdef __cplusplus 02184 extern "C" { 02185 #endif 02186 const char * 02187 smbc_version(void); 02188 #ifdef __cplusplus 02189 } 02190 #endif 02191 02192 02193 #endif /* SMBCLIENT_H_INCLUDED */