smbclient.h   [plain text]


/*
 * Copyright (c) 2009 - 2010 Apple Inc. All rights reserved.
 *
 * @APPLE_LICENSE_HEADER_START@
 *
 * This file contains Original Code and/or Modifications of Original Code
 * as defined in and that are subject to the Apple Public Source License
 * Version 2.0 (the 'License'). You may not use this file except in
 * compliance with the License. Please obtain a copy of the License at
 * http://www.opensource.apple.com/apsl/ and read it before using this
 * file.
 *
 * The Original Code and all software distributed under the License are
 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
 * Please see the License for the specific language governing rights and
 * limitations under the License.
 *
 * @APPLE_LICENSE_HEADER_END@
 */

#ifndef SMBCLIENT_H_8C21E785_0577_44E0_8CA1_8577A1010DF0
#define SMBCLIENT_H_8C21E785_0577_44E0_8CA1_8577A1010DF0

#include <Availability.h>
#include <stdint.h>
#include <sys/types.h>
#include <sys/socket.h>

#ifndef __cplusplus
#include <stdbool.h>
#endif

#ifdef __cplusplus
extern "C" {
#endif

/*!
 * @header SMB Client API
 * This API provides a relatively high level interface to performing SMB
 * protocol transactions. The API abstracts the version of the SMB protocol
 * as well as the various capabilities supported by the target server.
 */

#if !defined(SMBCLIENT_EXPORT)
#if defined(__GNUC__)
#define SMBCLIENT_EXPORT __attribute__((visibility("default")))
#else
#define SMBCLIENT_EXPORT
#endif
#endif /* SMBCLIENT_EXPORT */
	
#if !defined(_NTSTATUS_DEFINED)
#define _NTSTATUS_DEFINED
typedef uint32_t NTSTATUS;
#endif

#define NT_SUCCESS(status) ((status & 0xC0000000) == STATUS_SUCCESS)

/* NT_STATUS_SUCCESS is being depricated and should not be used */
#if !defined(NT_STATUS_SUCCESS)
#define NT_STATUS_SUCCESS 0
#endif
	
struct smb_server_handle;
typedef struct smb_server_handle * SMBHANDLE;

typedef uint64_t SMBFID;

typedef enum SMBAuthType
{
    kSMBAuthTypeAuthenticated,
    kSMBAuthTypeKerberos,
    kSMBAuthTypeUser,
    kSMBAuthTypeGuest,
    kSMBAuthTypeAnonymous
} SMBAuthType;

/*!
 * @function SMBOpenServer
 * @abstract Connect to a SMB tree
 * @param targetServer A UTF-8 encoded UNC name or SMB URL.
 * @param outConnection Filled in with a SMBHANDLE if the connection is
 * successful.
 * This is equivalent to calling SMBOpenServerEx with options of 0L.
 * @result Returns an NTSTATUS error code.
 */
SMBCLIENT_EXPORT
NTSTATUS
SMBOpenServer(
    const char *targetServer,
    SMBHANDLE * outConnection)
__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA)
;

/*! Do not prompt the user for authentication. */
#define kSMBOptionNoPrompt				0x00000001
/*! Don't touch the nsmb.conf in the users home directory. */
#define kSMBOptionNoUserPreferences		0x00000002
/*! Force the connection to use a new virtual circuit. */
#define kSMBOptionForceNewSession		0x00000004
/*! Connect as guest. */
#define kSMBOptionAllowGuestAuth		0x00000008
/*! Connect as anonymous. */
#define kSMBOptionAllowAnonymousAuth	0x00000010
/*! Only connect as guest. */
#define kSMBOptionUseGuestOnlyAuth		0x00000020
/*! Only connect as anonymous. */
#define kSMBOptionUseAnonymousOnlyAuth	0x00000040
/*! Create an authenticated session connection, don't tree connect. */
#define kSMBOptionSessionOnly			0x00010000

#define kSMBOptionOnlyAuthMask			(kSMBOptionUseGuestOnlyAuth | \
										kSMBOptionUseAnonymousOnlyAuth)
/*!
 * @function SMBOpenServerEx
 * @abstract Connect to a SMB tree with options
 * @param targetServer A UTF-8 encoded UNC name or SMB URL.
 * @param outConnection Filled in with a SMBHANDLE if the connection is
 * successful.
 * @param pOptions SMB
 * @result Returns an NTSTATUS error code.
 */
SMBCLIENT_EXPORT
NTSTATUS
SMBOpenServerEx(
    const char *targetServer,
    SMBHANDLE * outConnection,
    uint64_t    options)
__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA)
    ;

/*!
 * @function SMBMountShare
 * @abstract Mount a SMB share
 * @param inConnection A SMBHANDLE created by SMBOpenServer.
 * @param targetShare A UTF-8 encoded share name, may be null.
 * @param mountPoint A UTF-8 encoded mount point that must exist.
 * This is equivalent to calling SMBMountShareEx with , no mount flags, options,
 * file modes or directory modes.
 * @result Returns an NTSTATUS error code.
 */
SMBCLIENT_EXPORT
NTSTATUS
SMBMountShare(
	SMBHANDLE	inConnection,
	const char	*targetShare,
	const char	*mountPoint)
__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA)
;

	/*! Don't use NTFS Streams even if they are supported by the server. */
#define kSMBMntOptionNoStreams			0x00000001
	/*! Don't use Remote Notifications even if they are supported by the server. */
#define kSMBMntOptionNoNotifcations		0x00000002
	/*! Mount the volume soft, return time out error durring reconnect. */
#define kSMBMntOptionSoftMount			0x00000004
#define kSMBReservedTMMount				0x00000008

/*!
 * @function SMBOpenServerWithMountPoint
 * @abstract Find a shared session from a mounted volume
 * @param pTargetMountPath A UTF-8 encoded mount path.
 * @param pTargetTreeName A UTF-8 encoded tree connect name.
 * @param outConnection Filled in with a SMBHANDLE if the connection is
 * successful.
 * @param pOptions SMB
 * @result Returns an NTSTATUS error code.
 */
SMBCLIENT_EXPORT
NTSTATUS
SMBOpenServerWithMountPoint(
	const char	*targetMountPath,
	const char	*targetTreeName,
	SMBHANDLE	*outConnection,
	uint64_t	options)
__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA)
;

/*!
 * @function SMBRetainServer
 * @abstract Increments the SMBHANDLE reference count.
 * @param inConnection A SMBHANDLE created by SMBOpenServer.
 * @result Returns an NTSTATUS error code.
 */
SMBCLIENT_EXPORT
NTSTATUS
SMBRetainServer(
    SMBHANDLE inConnection)
__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA)
;

/*!
 * @function SMBReleaseServer
 * @abstract Decrements the SMBHANDLE reference count. If the reference count
 * goes to zero, the server object is destroyed.
 * @param inConnection A SMBHANDLE created by SMBOpenServer.
 * @result Returns an NTSTATUS error code.
 */
SMBCLIENT_EXPORT
NTSTATUS
SMBReleaseServer(
    SMBHANDLE inConnection)
__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA)
;

/*!
 * The SMB protocol dialect negotiated for the current connection.
 * Clients can generally assume that kSMBDialectSMB means "NT LM 0.12".
 */
typedef enum SMBDialect
{
    kSMBDialectSMB,
    kSMBDialectSMB2_002,
    kSMBDialectSMB2_1
} SMBDialect;

#define kPropertiesVersion	1

/* includes the c-style null terminator */
#define kMaxSrvNameLen	256

typedef struct SMBServerPropertiesV1
{
	uint32_t	version;
    SMBAuthType authType;
    SMBDialect  dialect;
    uint64_t    capabilities;	/* Either SMB or SMB2 capability flags */
	uint64_t    maxReadBytes;
    uint64_t    maxWriteBytes;
    uint64_t    maxTransactBytes;
	uint32_t    treeOptionalSupport;
	uint64_t    internalFlags;		/* Reserved for internal use */
	char		serverName[kMaxSrvNameLen];
	uint8_t		reserved[1024];
} SMBServerPropertiesV1;

/*!
 * @function SMBGetServerProperties
 * @abstract Return properties about the connection.
 * @param inConnection A SMBHANDLE created by SMBOpenServer.
 * @param outProperties Depending on the version request the properties of the
 * connection
 * @param inVersion The version of the properties requested
 * @param inPropertiesSize The size of the outProperties, must match the size of
 * the version being requested.
 * @result Returns an NTSTATUS error code.
 */
SMBCLIENT_EXPORT
NTSTATUS
SMBGetServerProperties(
		SMBHANDLE	inConnection,
		void		*outProperties,
		uint32_t	inVersion,
		size_t		inPropertiesSize)
__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA)
;

/*!
 * @function SMBCreateFile
 * @abstract Create of open a file.
 * @param inConnection
 * @param lpFileName The UTF-8 encoded file path.
 * @param dwShareMode
 * @param lpSecurityAttributes
 * @param dwCreateDisposition
 * @param dsFlagsAndAttributes
 * @param phFile
 * @result Returns an NTSTATUS error code.
 */
SMBCLIENT_EXPORT
NTSTATUS
SMBCreateFile(
    SMBHANDLE   inConnection,
    const char * lpFileName,
    uint32_t    dwDesiredAccess,
    uint32_t    dwShareMode,
    void *      lpSecurityAttributes,
    uint32_t    dwCreateDisposition,
    uint32_t    dwFlagsAndAttributes,
    SMBFID *    phFile)
__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA)
;

	
/*!
 * @function SMBCreateNamedStreamFile
 * @abstract Create of open a file.
 * @param inConnection
 * @param lpFileName The UTF-8 encoded file path.
 * @param lpFileStreamName The UTF-8 encoded file stream name. Must be a legal 
 * named streams that starts with a colon, if null then just the path will be 
 * opened/created.
 * @param dwShareMode
 * @param lpSecurityAttributes
 * @param dwCreateDisposition
 * @param dsFlagsAndAttributes
 * @param phFile
 * @result Returns an NTSTATUS error code.
 */
SMBCLIENT_EXPORT
NTSTATUS
SMBCreateNamedStreamFile(
    SMBHANDLE   inConnection,
    const char * lpFileName,
    const char * lpFileStreamName,
    uint32_t    dwDesiredAccess,
    uint32_t    dwShareMode,
    void *      lpSecurityAttributes,
    uint32_t    dwCreateDisposition,
    uint32_t    dwFlagsAndAttributes,
    SMBFID *    phFile)
__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA)
;
	
/*!
 * @function SMBRawTransaction
 * @abstract Send and receive a pre-marshalled SMB packet.
 * @result Returns an NTSTATUS error code.
 */
SMBCLIENT_EXPORT
NTSTATUS
SMBRawTransaction(
    SMBHANDLE   inConnection,
    const void *lpInBuffer,
    size_t		nInBufferSize,
    void		*lpOutBuffer,
    size_t		nOutBufferSize,
    size_t		*lpBytesRead)
__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA)
;

/*!
 * @function SMBTransactMailSlot
 * @abstract Perform a transact operation using a mailslot.
 * @result Returns an NTSTATUS error code.
 */
SMBCLIENT_EXPORT
NTSTATUS
SMBTransactMailSlot(
	SMBHANDLE   inConnection,
	const char	 *MailSlot,
	const void *sndParamBuffer,
	size_t		sndParamBufferSize,
	void		*rcvParamBuffer,
	size_t		*rcvParamBufferSize,
	void		*rcvDataBuffer,
	size_t		*rcvDataBufferSize)
__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA)
;

/*!
 * @function SMBTransactNamedPipe
 * @abstract Perform a transact operation on an open named pipe.
 * @result Returns an NTSTATUS error code.
 */
SMBCLIENT_EXPORT
NTSTATUS
SMBTransactNamedPipe(
    SMBHANDLE   inConnection,
    SMBFID      hNamedPipe,
    const void *inBuffer,
    size_t		inBufferSize,
    void		*outBuffer,
    size_t		outBufferSize,
    size_t		*bytesRead)
__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA)
;

/*!
 * @function SMBReadFile
 * @abstract Fread from an open file handle.
 * @result Returns an NTSTATUS error code.
 */
SMBCLIENT_EXPORT
NTSTATUS
SMBReadFile(
    SMBHANDLE   inConnection,
    SMBFID      hFile,
    void *      lpBuffer,
    off_t       nOffset,
    size_t		nNumberOfBytesToRead,
    size_t		*lpNumberOfBytesRead)
__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA)
;

/*!
 * @function SMBWriteFile
 * @abstract Write to an open file handle.
 * @result Returns an NTSTATUS error code.
 */
SMBCLIENT_EXPORT
NTSTATUS
SMBWriteFile(
    SMBHANDLE   inConnection,
    SMBFID      hFile,
    const void *lpBuffer,
    off_t       nOffset,
    size_t		nNumberOfBytesToWrite,
    size_t		*lpNumberOfBytesWritten)
__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA)
;

/*!
 * @function SMBDeviceIoControl
 * @abstract Perform a SMB fsctl on the given file handle.
 *
 * @param inConnection
 * @param hDevice
 * @param dwIoControlCode
 * @param lpInBuffer
 * @param nInBufferSize
 * @param lpOutBuffer
 * @param nOutBufferSize
 * @param lpBytesReturned
 *
 * @return Returns an NTSTATUS error code.
 */
SMBCLIENT_EXPORT
NTSTATUS
SMBDeviceIoControl(
    SMBHANDLE   inConnection,
    SMBFID      hDevice,
    uint32_t    dwIoControlCode,
    const void *lpInBuffer,
    size_t		nInBufferSize,
    void *      lpOutBuffer,
    size_t		nOutBufferSize,
    size_t *    lpBytesReturned)
__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA)
;

/*!
 * @function SMBCloseFile
 * @abstract Close an open file handle.
 * @result Returns an NTSTATUS error code.
 */
SMBCLIENT_EXPORT
NTSTATUS
SMBCloseFile(
    SMBHANDLE   inConnection,
    SMBFID      hFile)
__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA)
;

/*!
 * @function smbfs_version
 * @abstract return the framework version number.
 * @result framework version number.
 */
SMBCLIENT_EXPORT
int SMBFrameworkVersion(void)
    __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA)
;

/*!
 * @function SMBCreateURLString
 * @abstract Create a URL string that represents the value passed in. Escape out
 *           any needed character.
 * @param domain	The domain name used for authentication, can be null
 * @param user		The user name used for authentication, can be null
 * @param passwd	The password name used for authentication, can be null
 * @param server	The Server name you wish to connect to, cann't be null
 * @param path		The Share/Path name, can be null
 * @param port		The port you wish to connect on, -1 means use the default.
 * @result			Null terminated string, that can be used by SMBOpenServer.
 */
SMBCLIENT_EXPORT
char *SMBCreateURLString(
        const char *domain,
        const char * user,
        const char * passwd,
        const char *server,
        const char *path,
        int32_t port)
__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA)
;

/*!
 * @function SMBConvertFromUTF8ToCodePage
 * @abstract Convert from a UTF8 string using the system code page.
 * @param utf8Str The UTF8 string that needs to be converted
 * @param uppercase Uppercase string before returning
 * @result Null terminated string.
 */
SMBCLIENT_EXPORT
char *
SMBConvertFromUTF8ToCodePage(
	const char *utf8Str,
	int uppercase)
__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA)
;

/*!
 * @function SMBConvertFromCodePageToUTF8
 * @abstract Convert to a UTF8 string using the system code page.
 * @param cpStr The UTF8 string that needs to be converted
 * @result Null terminated UTF8 string.
 */
SMBCLIENT_EXPORT
char *
SMBConvertFromCodePageToUTF8(
	const char *cpStr)
__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA)
;

/*!
 * @function SMBConvertFromUTF16ToUTF8
 * @abstract Convert to a UTF16 string into a UTF8 string.
 * @param utf8str The UTF8 string that needs to be converted, should be double null
 * terminated.
 * @param maxLen Buffer size of the utf16 string. At most maxLen-1 characters
 * will be converted.
 * @param options Currently not used, future expansion
 * @result Null terminated UTF8 string.
 */
SMBCLIENT_EXPORT
char *
SMBConvertFromUTF16ToUTF8(
	const uint16_t *utf16str,
	size_t maxLen,
	uint64_t options)
__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA)
;

/*!
 * @function SMBConvertFromUTF8ToUTF16
 * @abstract Convert to a UTF8 string into a UTF16 string.
 * @param utf8str The UTF8 string that needs to be converted, should be null
 * terminated.
 * @param maxLen Buffer size of the utf8 string. At most maxLen-1 characters
 * will be converted.
 * @param options Currently not used, future expansion
 * @result UTF16 string.
 */
SMBCLIENT_EXPORT
uint16_t *
SMBConvertFromUTF8ToUTF16(
	   const char *utf8str,
	   size_t maxLen,
	   uint64_t options)
__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA)
;

#ifdef __cplusplus
} // extern "C"
#endif

#endif /* SMBCLIENT_H_8C21E785_0577_44E0_8CA1_8577A1010DF0 */
/* vim: set sw=4 ts=4 tw=79 et: */