For those who want to utilize pysmb in Twisted framework, pysmb has a smb.SMBProtocol.SMBProtocol implementation. In most cases, you do not need to touch or import the SMBProtocol directly. All the SMB functionalities are exposed in the SMBProtocolFactory.
All the SMBProtocolFactory public methods that provide file functionlities will return a twisted.internet.defer.Deferred instance. A NotReadyError exception is raised when the underlying SMB is not authenticated. If the underlying SMB connection has been terminated, a NotConnectedError exception is raised.
All the file operation methods in SMBProtocolFactory class accept a timeout parameter. This parameter specifies the time limit where pysmb will wait for the entire file operation (except storeFile and retrieveFile methods) to complete. If the file operation fails to complete within the timeout period, the returned Deferred instance’s errback method will be called with a SMBTimeout exception.
If you are interested in learning the results of the operation or to know when the operation has completed, you should add a handling method to the returned Deferred instance via Deferred.addCallback. If the file operation fails, the Deferred.errback function will be called with an OperationFailure; on timeout, it will be called with a SMBTimeout.
The following illustrates a simple file retrieving implementation.:
import tempfile
from twisted.internet import reactor
from smb.SMBProtocol import SMBProtocolFactory
class RetrieveFileFactory(SMBProtocolFactory):
def __init__(self, *args, **kwargs):
SMBProtocolFactory.__init__(self, *args, **kwargs)
def fileRetrieved(self, write_result):
file_obj, file_attributes, file_size = write_result
# Retrieved file contents are inside file_obj
# Do what you need with the file_obj and then close it
# Note that the file obj is positioned at the end-of-file,
# so you might need to perform a file_obj.seek() to if you
# need to read from the beginning
file_obj.close()
self.transport.loseConnection()
def onAuthOK(self):
d = self.retrieveFile(self.service, self.path, tempfile.NamedTemporaryFile())
d.addCallback(self.fileRetrieved)
d.addErrback(self.d.errback)
def onAuthFailed(self):
print 'Auth failed'
# There will be some mechanism to capture userID, password, client_machine_name, server_name and server_ip
# client_machine_name can be an arbitary ASCII string
# server_name should match the remote machine name, or else the connection will be rejected
factory = RetrieveFileFactory(userID, password, client_machine_name, server_name, use_ntlm_v2 = True)
factory.service = 'smbtest'
factory.path = '/rfc1001.txt'
reactor.connectTCP(server_ip, 139, factory)
Starting from pysmb 1.1.0, pysmb will utilize SMB2 protocol for communication if the remote SMB/CIFS service supports SMB2. Otherwise, it will fallback automatically back to using SMB1 protocol.
To disable SMB2 protocol in pysmb, set the SUPPORT_SMB2 flag in the smb_structs module to False before creating the SMBProtocolFactory instance.:
from smb import smb_structs
smb_structs.SUPPORT_SMB2 = False
Create a new SMBProtocolFactory instance. You will pass this instance to reactor.connectTCP() which will then instantiate the TCP connection to the remote SMB/CIFS server. Note that the default TCP port for most SMB/CIFS servers is 139.
username and password are the user credentials required to authenticate the underlying SMB connection with the remote server. File operations can only be proceeded after the connection has been authenticated successfully.
Parameters: |
|
---|
Disconnect from the remote SMB/CIFS server. The TCP connection will be closed at the earliest opportunity after this method returns.
Returns: | None |
---|
Creates a new directory path on the service_name.
Parameters: |
|
---|---|
Returns: | A twisted.internet.defer.Deferred instance. The callback function will be called with the path parameter. |
Delete the empty folder at path on service_name
Parameters: |
|
---|---|
Returns: | A twisted.internet.defer.Deferred instance. The callback function will be called with the path parameter. |
Delete one or more regular files. It supports the use of wildcards in file names, allowing for deletion of multiple files in a single request.
Parameters: |
|
---|---|
Returns: | A twisted.internet.defer.Deferred instance. The callback function will be called with the path_file_pattern parameter. |
Send an echo command containing data to the remote SMB/CIFS server. The remote SMB/CIFS will reply with the same data.
Parameters: |
|
---|---|
Returns: | A twisted.internet.defer.Deferred instance. The callback function will be called with the data parameter. |
Retrieve a directory listing of files/folders at path
Parameters: |
|
---|---|
Returns: | A twisted.internet.defer.Deferred instance. The callback function will be called with a list of smb.base.SharedFile instances. |
Retrieve a list of shared resources on remote server.
Parameters: | timeout (integer/float) – Number of seconds that pysmb will wait before raising SMBTimeout via the returned Deferred instance’s errback method. |
---|---|
Returns: | A twisted.internet.defer.Deferred instance. The callback function will be called with a list of smb.base.SharedDevice instances. |
Retrieve a list of available snapshots (a.k.a. shadow copies) for path.
Note that snapshot features are only supported on Windows Vista Business, Enterprise and Ultimate, and on all Windows 7 editions.
Parameters: |
|
---|---|
Returns: | A list of python datetime.DateTime instances in GMT/UTC time zone |
Override this method in your SMBProtocolFactory subclass to add in post-authentication handling. This method will be called when the server has replied that the SMB connection has been successfully authenticated.
Override this method in your SMBProtocolFactory subclass to add in post-authentication handling. This method will be called when the server has replied that the SMB connection has been successfully authenticated. File operations can proceed when this method has been called.
Rename a file or folder at old_path to new_path shared at service_name. Note that this method cannot be used to rename file/folder across different shared folders
old_path and new_path are string/unicode referring to the old and new path of the renamed resources (relative to) the shared folder. If the path contains non-English characters, an unicode string must be used to pass in the path.
Parameters: |
|
---|---|
Returns: | A twisted.internet.defer.Deferred instance. The callback function will be called with a 2-element tuple of ( old_path, new_path ). |
Retrieve the contents of the file at path on the service_name and write these contents to the provided file_obj.
Use retrieveFileFromOffset() method if you need to specify the offset to read from the remote path and/or the maximum number of bytes to write to the file_obj.
The meaning of the timeout parameter will be different from other file operation methods. As the downloaded file usually exceeeds the maximum size of each SMB/CIFS data message, it will be packetized into a series of request messages (each message will request about about 60kBytes). The timeout parameter is an integer/float value that specifies the timeout interval for these individual SMB/CIFS message to be transmitted and downloaded from the remote SMB/CIFS server.
Parameters: |
|
---|---|
Returns: | A twisted.internet.defer.Deferred instance. The callback function will be called with a 3-element tuple of ( file_obj, file attributes of the file on server, number of bytes written to file_obj ). The file attributes is an integer value made up from a bitwise-OR of SMB_FILE_ATTRIBUTE_xxx bits (see smb_constants.py) |
Retrieve the contents of the file at path on the service_name and write these contents to the provided file_obj.
The meaning of the timeout parameter will be different from other file operation methods. As the downloaded file usually exceeeds the maximum size of each SMB/CIFS data message, it will be packetized into a series of request messages (each message will request about about 60kBytes). The timeout parameter is an integer/float value that specifies the timeout interval for these individual SMB/CIFS message to be transmitted and downloaded from the remote SMB/CIFS server.
Parameters: |
|
---|---|
Returns: | A twisted.internet.defer.Deferred instance. The callback function will be called with a 3-element tuple of ( file_obj, file attributes of the file on server, number of bytes written to file_obj ). The file attributes is an integer value made up from a bitwise-OR of SMB_FILE_ATTRIBUTE_xxx bits (see smb_constants.py) |
Store the contents of the file_obj at path on the service_name.
The meaning of the timeout parameter will be different from other file operation methods. As the uploaded file usually exceeeds the maximum size of each SMB/CIFS data message, it will be packetized into a series of messages (usually about 60kBytes). The timeout parameter is an integer/float value that specifies the timeout interval for these individual SMB/CIFS message to be transmitted and acknowledged by the remote SMB/CIFS server.
Parameters: |
|
---|---|
Returns: | A twisted.internet.defer.Deferred instance. The callback function will be called with a 2-element tuple of ( file_obj, number of bytes uploaded ). |
SMB messages will never be signed regardless of remote server’s configurations; access errors will occur if the remote server requires signing.
SMB messages will only be signed when remote server requires signing.
SMB messages will be signed when remote server supports signing but not requires signing.
The single SMBProtocol instance for each SMBProtocolFactory instance. Usually, you should not need to touch this attribute directly.