Struct Client 

pub struct Client { /* private fields */ }

This struct represents a high-level SMB client, and it is highly encouraged to use it for interacting with SMB servers, instead of manually creating connections.

General usage

When connecting to a new share, even if it’s on the same server, you must always connect to the share using Client::share_connect.

Drop behavior

When the client drops, the held connections are not forcibly closed, but rather kept alive until all their references are dropped. For example, if a file is opened from the client, and the client is dropped, the connection, session and tree of the opened file, will still be alive, but you will not be able to use the client to interact with them.

To force a closure of all connections and their managed resources, use the Client::close method.

Example

use smb::{Client, ClientConfig, UncPath, FileCreateArgs, FileAccessMask};
use std::str::FromStr;
#[cfg(feature = "async")]
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // instantiate the client
    let client = Client::new(ClientConfig::default());

    // Connect to a share
    let target_path = UncPath::from_str(r"\\server\share").unwrap();
    client.share_connect(&target_path, "username", "password".to_string()).await?;

    // And open a file on the server
    let file_to_open = target_path.with_path("file.txt");
    let file_open_args = FileCreateArgs::make_open_existing(FileAccessMask::new().with_generic_read(true));
    let file = client.create_file(&file_to_open, &file_open_args).await?;
    // now, you can do a bunch of operations against `file`, and close it at the end.
    Ok(())
}

Implementations

impl Client

pub fn new(config: ClientConfig) -> Self

Creates a new Client instance with the given configuration.

pub fn config(&self) -> &ClientConfig

pub async fn close(&self) -> Result<()>

Shuts down the client, and all its managed connections.

Any resource held by the client will not be accessible after calling this method, directly or indirectly.

See Drop behavior for more information.

pub async fn list_shares(&self, server: &str) -> Result<Vec<ShareInfo1>>

Lists all shares on the specified server.

pub async fn share_connect( &self, target: &UncPath, user_name: &str, password: String, ) -> Result<()>

Connects to a share on the specified server.

This method is the equivalent for executing a net use command on a local windows machine.

Once the connection completes, the client will be able to access resource under the specified share, without needing to re-authenticate.

If the share is already connected, this method will do nothing, and will log a warning indicating the double-connection attempt.

Arguments

• target - The UNC path of the share to connect to. The method refers to the server and share components in this path.
• user_name - The username to use for authentication.
• password - The password to use for authentication.

Returns

The connected share - a Tree instance.

Notes

This is the best high-level method that performs share connection, but it might not suit advanced use cases.

You can replace calls to this method by performing the connection, session and share setup manually, just like it does, using the Client::connect method:

// instantiate the client
// Connect to a share
let target_path = UncPath::from_str(r"\\server\share").unwrap();
let connection = client.share_connect(&target_path, "username", "password".to_string()).await?;

pub async fn connect(&self, server: &str) -> Result<Arc<Connection>>

Makes a connection to the specified server. If a matching connection already exists, returns it.

Note: You should usually connect the client through the Client::share_connect method. Using this method, for example, will require you to hold a reference to trees, or otherwise they will disconnect (as opposed to the share_connect method, which assures keeping the tree alive!)

See Client::connect_to_address to connect to a server using a specific socket address.

Arguments

• server - The target server to make the connection for.

Returns

The connected connection, if succeeded. Error if failed to make the connection,

pub async fn connect_to_address( &self, server: &str, server_address: SocketAddr, ) -> Result<Arc<Connection>>

Makes a connection to the specified server and address. If a matching connection already exists, returns it.

Note: You should usually connect the client through the Client::share_connect method. Using this method, for example, will require you to hold a reference to trees, or otherwise they will disconnect (as opposed to the share_connect method, which assures keeping the tree alive!)

See Client::connect to connect to a server using DNS resolution.

Arguments

• server - The target server to make the connection for.
• server_address - An optional socket address to connect to. If the port is set to 0, the default port will be used according to the transport that is used.

Returns

The connected connection, if succeeded. Error if failed to make the connection, or failed to connect the remote.

pub async fn connect_transport_to_address( &self, server: &str, server_address: SocketAddr, transport: TransportConfig, ) -> Result<Arc<Connection>>

Just like Client::connect_to_address, but allows specifying a custom transport configuration.

pub async fn get_connection(&self, server: &str) -> Result<Arc<Connection>>

Returns the underlying Connection for the specified server, after a successful call to Client::connect or Client::share_connect.

pub async fn get_connection_ip(&self, ip: IpAddr) -> Result<Arc<Connection>>

pub async fn get_session(&self, path: &UncPath) -> Result<Arc<Session>>

pub async fn get_channels( &self, path: &UncPath, ) -> Result<HashMap<u32, AltChannelInfo>>

Returns a map of channel IDs to their corresponding connections for the specified session,

pub async fn get_tree(&self, path: &UncPath) -> Result<Arc<Tree>>

Returns the underlying Tree for the specified UNC path, after a successful call to Client::share_connect.

pub async fn create_file( &self, path: &UncPath, args: &FileCreateArgs, ) -> Result<Resource>

Creates (or opens) a file on the specified path, using the specified args.

See FileCreateArgs for detailed information regarding the file open options.

The function also handles DFS resolution if it is enabled in the client configuration.

Arguments

• path - The UNC path of the file to create or open.
• args - The arguments to use when creating or opening the file.

Returns

A result containing the created or opened file resource, or an error.

pub async fn ipc_connect( &self, server: &str, username: &str, password: String, ) -> Result<()>

Similar Client::share_connect, but connects to the SMB pipes share (IPC$).

After calling this method, the Client::open_pipe method can be used to open named pipes.

pub async fn _ipc_connect( &self, server: &str, identity: &AuthIdentity, ) -> Result<()>

pub async fn open_pipe(&self, server: &str, pipe_name: &str) -> Result<Pipe>

Opens a named pipe on the specified server. Use this when intending to communicate with a service using a named pipe, for convenience.

Arguments

• server - The name of the server hosting the pipe.
• pipe_name - The name of the pipe to open.

Returns

A result containing the opened Pipe resource, or an error.

Notes

before calling this method, you MUST call the Client::ipc_connect method, that connects to the IPC$ share on the server, which then allows for communication with the named pipe.

Trait Implementations

impl Default for Client

fn default() -> Self

Starts the client with default configuration.