libdsm  0.4.3
Minimalist and read-only SMB client lib
Functions
smb_session.h File Reference

Functions to connect and authenticate to an SMB server. More...

#include "bdsm/export.h"
#include "bdsm/smb_defs.h"
#include "bdsm/smb_types.h"

Functions

BDSM_EXPORT smb_sessionsmb_session_new ()
 Allocates a new Session object. More...
 
BDSM_EXPORT void smb_session_destroy (smb_session *s)
 Close a session and deallocate its ressources. More...
 
BDSM_EXPORT void smb_session_abort (smb_session *s)
 Interrupt any I/O smb_session functions (smb_session_connect, smb_fread...) More...
 
BDSM_EXPORT void smb_session_set_creds (smb_session *s, const char *domain, const char *login, const char *password)
 Set the credentials for this session. More...
 
BDSM_EXPORT int smb_session_connect (smb_session *s, const char *hostname, uint32_t ip, int transport)
 Establish a connection and negotiate a session protocol with a remote host. More...
 
BDSM_EXPORT int smb_session_login (smb_session *s)
 Authenticate on the remote host with the provided credentials. More...
 
BDSM_EXPORT int smb_session_is_guest (smb_session *s)
 Am i logged in as Guest ? More...
 
BDSM_EXPORT const char * smb_session_server_name (smb_session *s)
 Returns the server name with the <XX> type. More...
 
BDSM_EXPORT int smb_session_supports (smb_session *s, int what)
 Check if a feature is supported/has been negociated with the server. More...
 
BDSM_EXPORT uint32_t smb_session_get_nt_status (smb_session *s)
 Get the last NT_STATUS. More...
 

Detailed Description

Functions to connect and authenticate to an SMB server.

Function Documentation

BDSM_EXPORT void smb_session_abort ( smb_session s)

Interrupt any I/O smb_session functions (smb_session_connect, smb_fread...)

This function can be called from any threads. The session is unusable after this call, only smb_session_destroy() should be called after.

Parameters
sThe session to abort
BDSM_EXPORT int smb_session_connect ( smb_session s,
const char *  hostname,
uint32_t  ip,
int  transport 
)

Establish a connection and negotiate a session protocol with a remote host.

You have to provide both the ip and the name. This is a constraint of Netbios, which requires you to know its name before he accepts to speak with you.

Parameters
sA session object.
hostnameThe ASCII netbios name, the name type will be coerced to <20> since libdsm is about reading files
ipThe ip of the machine to connect to (in network byte order)
transportThe type of transport used, it could be SMB_TRANSPORT_TCP or SMB_TRANSPORT_NBT (Netbios over TCP, ie legacy)
Returns
0 on success or a DSM error code in case of error
BDSM_EXPORT void smb_session_destroy ( smb_session s)

Close a session and deallocate its ressources.

After destroying a session, all the smb_tid, smb_fid and smb_fd associated with this session becomes invalid.

Parameters
sThe session to destroy
BDSM_EXPORT uint32_t smb_session_get_nt_status ( smb_session s)

Get the last NT_STATUS.

Valid only if a smb_ function returned the DSM_ERROR_NT error.

Parameters
sThe session object
BDSM_EXPORT int smb_session_is_guest ( smb_session s)

Am i logged in as Guest ?

Parameters
sThe session object
Returns
1 -> Logged in as guest 0 -> Logged in as regular user -1 -> Error (not logged in, invalid session, etc.)
BDSM_EXPORT int smb_session_login ( smb_session s)

Authenticate on the remote host with the provided credentials.

Can be called if session state is SMB_STATE_DIALECT_OK. If successfull, session state transition to SMB_STATE_SESSION_OK Provides the credentials with smb_session_set_creds.

Parameters
sThe session object.
Returns
0 on success or a DSM error code in case of error. Success doesn't mean you are logged in with the user you requested. If guest are activated on the remote host, when login fails, you are logged in as 'Guest'. Failure might also indicate you didn't supplied all the credentials
BDSM_EXPORT smb_session* smb_session_new ( )

Allocates a new Session object.

To be able to perform actions on shares and file, you'll need to call smb_session_connect, then authenticate with smb_authenticate.

Returns
A new Session object.
BDSM_EXPORT const char* smb_session_server_name ( smb_session s)

Returns the server name with the <XX> type.

Parameters
sThe session object
Returns
The server name or NULL. The memory is owned by the session object.
BDSM_EXPORT void smb_session_set_creds ( smb_session s,
const char *  domain,
const char *  login,
const char *  password 
)

Set the credentials for this session.

Any of the params except s can be NULL.

Parameters
sThe session object.
domainDomain to authenticate on. Often it's the same as netbios host.
loginThe user to login as.
passwordthe user's password.
BDSM_EXPORT int smb_session_supports ( smb_session s,
int  what 
)

Check if a feature is supported/has been negociated with the server.

Parameters
sThe session object
whatWhich features to check ?
See also
smb_session_supports_what
Returns
0 if the feature is not supported, something else otherwise