def echo(self, data, timeout=10):
"""
Send an echo command containing *data* to the remote SMB/CIFS server. The remote SMB/CIFS will reply with the same *data*.
:param string data: Data to send to the remote server.
:return: The *data* parameter
"""
if not self.sock:
raise NotConnectedError('Not connected to server')
results = []
def cb(r):
self.is_busy = False
results.append(r)
def eb(failure):
self.is_busy = False
raise failure
self.is_busy = True
try:
self._echo(data, cb, eb)
while self.is_busy:
self._pollForNetBIOSPacket(timeout)
finally:
self.is_busy = False
return results[0]
def storeFile(self, service_name, path, file_obj, timeout=30):
"""
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.
:param string/unicode service_name: the name of the shared folder for the *path*
:param string/unicode path: Path of the file on the remote server. If the file at *path* does not exist, it will be created. Otherwise, it will be overwritten.
If the *path* refers to a folder or the file cannot be opened for writing, an :doc:`OperationFailure<smb_exceptions>` will be called in the returned *Deferred* errback.
:param file_obj: A file-like object that has a *read* method. Data will read continuously from *file_obj* until EOF.
:return: A *twisted.internet.defer.Deferred* instance. The callback function will be called with a 2-element tuple of ( *file_obj*, number of bytes uploaded ).
"""
if not self.instance:
raise NotConnectedError('Not connected to server')
d = defer.Deferred()
self.instance._storeFile(service_name,
path,
file_obj,
d.callback,
d.errback,
timeout=timeout)
return d
def listSnapshots(self, service_name, path, timeout=30):
"""
Retrieve a list of available snapshots (shadow copies) for *path*.
Note that snapshot features are only supported on Windows Vista Business, Enterprise and Ultimate, and on all Windows 7 editions.
:param string/unicode service_name: the name of the shared folder for the *path*
:param string/unicode path: path relative to the *service_name* where we are interested in the list of available snapshots
:return: A list of python *datetime.DateTime* instances in GMT/UTC time zone
"""
if not self.sock:
raise NotConnectedError('Not connected to server')
results = []
def cb(entries):
self.is_busy = False
results.extend(entries)
def eb(failure):
self.is_busy = False
raise failure
self.is_busy = True
try:
self._listSnapshots(service_name, path, cb, eb, timeout=timeout)
while self.is_busy:
self._pollForNetBIOSPacket(timeout)
finally:
self.is_busy = False
return results
def listShares(self, timeout=30):
"""
Retrieve a list of shared resources on remote server.
:return: A list of :doc:`smb.base.SharedDevice<smb_SharedDevice>` instances describing the shared resource
"""
if not self.sock:
raise NotConnectedError('Not connected to server')
results = []
def cb(entries):
self.is_busy = False
results.extend(entries)
def eb(failure):
self.is_busy = False
raise failure
self.is_busy = True
try:
self._listShares(cb, eb, timeout)
while self.is_busy:
self._pollForNetBIOSPacket(timeout)
finally:
self.is_busy = False
return results
def deleteDirectory(self, service_name, path, timeout=30):
"""
Delete the empty folder at *path* on *service_name*
:param string/unicode service_name: Contains the name of the shared folder.
:param string/unicode path: The path of the to-be-deleted folder (relative to) the shared folder.
If the path contains non-English characters, an unicode string must be used to pass in the path.
:return: None
"""
if not self.sock:
raise NotConnectedError('Not connected to server')
def cb(r):
self.is_busy = False
def eb(failure):
self.is_busy = False
raise failure
self.is_busy = True
try:
self._deleteDirectory(service_name, path, cb, eb, timeout=timeout)
while self.is_busy:
self._pollForNetBIOSPacket(timeout)
finally:
self.is_busy = False
def deleteFiles(self, service_name, path_file_pattern, timeout=30):
"""
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.
:param string/unicode service_name: Contains the name of the shared folder.
:param string/unicode path_file_pattern: The pathname of the file(s) to be deleted, relative to the service_name.
Wildcards may be used in th filename component of the path.
If your path/filename contains non-English characters, you must pass in an unicode string.
:return: None
"""
if not self.sock:
raise NotConnectedError('Not connected to server')
def cb(r):
self.is_busy = False
def eb(failure):
self.is_busy = False
raise failure
self.is_busy = True
try:
self._deleteFiles(service_name,
path_file_pattern,
cb,
eb,
timeout=timeout)
while self.is_busy:
self._pollForNetBIOSPacket(timeout)
finally:
self.is_busy = False
def rename(self, service_name, old_path, new_path, timeout=30):
"""
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.
:param string/unicode service_name: Contains the name of the shared folder.
:return: None
"""
if not self.sock:
raise NotConnectedError('Not connected to server')
def cb(r):
self.is_busy = False
def eb(failure):
self.is_busy = False
raise failure
self.is_busy = True
try:
self._rename(service_name, old_path, new_path, cb, eb)
while self.is_busy:
self._pollForNetBIOSPacket(timeout)
finally:
self.is_busy = False
def listPath(self,
service_name,
path,
search=SMB_FILE_ATTRIBUTE_READONLY | SMB_FILE_ATTRIBUTE_HIDDEN
| SMB_FILE_ATTRIBUTE_SYSTEM | SMB_FILE_ATTRIBUTE_DIRECTORY
| SMB_FILE_ATTRIBUTE_ARCHIVE,
pattern='*',
timeout=30):
"""
Retrieve a directory listing of files/folders at *path*
:param string/unicode service_name: the name of the shared folder for the *path*
:param string/unicode path: path relative to the *service_name* where we are interested to learn about its files/sub-folders.
:param integer search: integer value made up from a bitwise-OR of *SMB_FILE_ATTRIBUTE_xxx* bits (see smb_constants.py).
The default *search* value will query for all read-only, hidden, system, archive files and directories.
:param string/unicode pattern: the filter to apply to the results before returning to the client.
:param integer/float timeout: Number of seconds that pysmb will wait before raising *SMBTimeout* via the returned *Deferred* instance's *errback* method.
:return: A *twisted.internet.defer.Deferred* instance. The callback function will be called with a list of :doc:`smb.base.SharedFile<smb_SharedFile>` instances.
"""
if not self.instance:
raise NotConnectedError('Not connected to server')
d = defer.Deferred()
self.instance._listPath(service_name,
path,
d.callback,
d.errback,
search=search,
pattern=pattern,
timeout=timeout)
return d
def getAttributes(self, service_name, path, timeout=30):
"""
Retrieve information about the file at *path* on the *service_name*.
:param string/unicode service_name: the name of the shared folder for the *path*
:param string/unicode path: Path of the file on the remote server. If the file cannot be opened for reading, an :doc:`OperationFailure<smb_exceptions>` will be raised.
:return: A :doc:`smb.base.SharedFile<smb_SharedFile>` instance containing the attributes of the file.
"""
if not self.sock:
raise NotConnectedError('Not connected to server')
results = []
def cb(info):
self.is_busy = False
results.append(info)
def eb(failure):
self.is_busy = False
raise failure
self.is_busy = True
try:
self._getAttributes(service_name, path, cb, eb, timeout)
while self.is_busy:
self._pollForNetBIOSPacket(timeout)
finally:
self.is_busy = False
return results[0]
def resetFileAttributes(self, service_name, path_file_pattern, timeout = 30):
"""
Reset file attributes of one or more regular files or folders.
It supports the use of wildcards in file names, allowing for unlocking of multiple files/folders in a single request.
This function is very helpful when deleting files/folders that are read-only.
Note: this function is currently only implemented for SMB2! Technically, it sets the FILE_ATTRIBUTE_NORMAL flag, therefore clearing all other flags. (See https://msdn.microsoft.com/en-us/library/cc232110.aspx for further information)
:param string/unicode service_name: Contains the name of the shared folder.
:param string/unicode path_file_pattern: The pathname of the file(s) to be deleted, relative to the service_name.
Wildcards may be used in the filename component of the path.
If your path/filename contains non-English characters, you must pass in an unicode string.
:return: None
"""
if not self.sock:
raise NotConnectedError('Not connected to server')
def cb(r):
self.is_busy = False
def eb(failure):
self.is_busy = False
raise failure
self.is_busy = True
try:
self._resetFileAttributes(service_name, path_file_pattern, cb, eb, timeout = timeout)
while self.is_busy:
self._pollForNetBIOSPacket(timeout)
finally:
self.is_busy = False
def listPath(self, service_name, path,
search = SMB_FILE_ATTRIBUTE_READONLY | SMB_FILE_ATTRIBUTE_HIDDEN | SMB_FILE_ATTRIBUTE_SYSTEM | SMB_FILE_ATTRIBUTE_DIRECTORY | SMB_FILE_ATTRIBUTE_ARCHIVE,
pattern = '*', timeout = 30):
"""
Retrieve a directory listing of files/folders at *path*
:param string/unicode service_name: the name of the shared folder for the *path*
:param string/unicode path: path relative to the *service_name* where we are interested to learn about its files/sub-folders.
:param integer search: integer value made up from a bitwise-OR of *SMB_FILE_ATTRIBUTE_xxx* bits (see smb_constants.py).
The default *search* value will query for all read-only, hidden, system, archive files and directories.
:param string/unicode pattern: the filter to apply to the results before returning to the client.
:return: A list of :doc:`smb.base.SharedFile<smb_SharedFile>` instances.
"""
if not self.sock:
raise NotConnectedError('Not connected to server')
results = [ ]
def cb(entries):
self.is_busy = False
results.extend(entries)
def eb(failure):
self.is_busy = False
raise failure
self.is_busy = True
try:
self._listPath(service_name, path, cb, eb, search = search, pattern = pattern, timeout = timeout)
while self.is_busy:
self._pollForNetBIOSPacket(timeout)
finally:
self.is_busy = False
return results
def write(self, data):
assert self.sock
data_len = len(data)
total_sent = 0
while total_sent < data_len:
sent = self.sock.send(data[total_sent:])
if sent == 0:
raise NotConnectedError('Server disconnected')
total_sent = total_sent + sent
def closeConnection(self):
"""
Disconnect from the remote SMB/CIFS server. The TCP connection will be closed at the earliest opportunity after this method returns.
:return: None
"""
if not self.instance:
raise NotConnectedError('Not connected to server')
self.instance.transport.loseConnection()
def listPath(self,
service_name,
path,
search=SMB_FILE_ATTRIBUTE_READONLY | SMB_FILE_ATTRIBUTE_HIDDEN
| SMB_FILE_ATTRIBUTE_SYSTEM | SMB_FILE_ATTRIBUTE_DIRECTORY
| SMB_FILE_ATTRIBUTE_ARCHIVE | SMB_FILE_ATTRIBUTE_INCL_NORMAL,
pattern='*',
timeout=30):
"""
Retrieve a directory listing of files/folders at *path*
For simplicity, pysmb defines a "normal" file as a file entry that is not read-only, not hidden, not system, not archive and not a directory.
It ignores other attributes like compression, indexed, sparse, temporary and encryption.
Note that the default search parameter will query for all read-only (SMB_FILE_ATTRIBUTE_READONLY), hidden (SMB_FILE_ATTRIBUTE_HIDDEN),
system (SMB_FILE_ATTRIBUTE_SYSTEM), archive (SMB_FILE_ATTRIBUTE_ARCHIVE), normal (SMB_FILE_ATTRIBUTE_INCL_NORMAL) files
and directories (SMB_FILE_ATTRIBUTE_DIRECTORY).
If you do need to include "normal" files in the result, define your own search parameter without the SMB_FILE_ATTRIBUTE_INCL_NORMAL constant.
SMB_FILE_ATTRIBUTE_NORMAL should be used by itself and not be used with other bit constants.
:param string/unicode service_name: the name of the shared folder for the *path*
:param string/unicode path: path relative to the *service_name* where we are interested to learn about its files/sub-folders.
:param integer search: integer value made up from a bitwise-OR of *SMB_FILE_ATTRIBUTE_xxx* bits (see smb_constants.py).
:param string/unicode pattern: the filter to apply to the results before returning to the client.
:return: A list of :doc:`smb.base.SharedFile<smb_SharedFile>` instances.
"""
if not self.sock:
raise NotConnectedError('Not connected to server')
results = []
def cb(entries):
self.is_busy = False
results.extend(entries)
def eb(failure):
self.is_busy = False
raise failure
self.is_busy = True
try:
self._listPath(service_name,
path,
cb,
eb,
search=search,
pattern=pattern,
timeout=timeout)
while self.is_busy:
self._pollForNetBIOSPacket(timeout)
finally:
self.is_busy = False
return results
def listShares(self, timeout=30):
"""
Retrieve a list of shared resources on remote server.
:param integer/float timeout: Number of seconds that pysmb will wait before raising *SMBTimeout* via the returned *Deferred* instance's *errback* method.
:return: A *twisted.internet.defer.Deferred* instance. The callback function will be called with a list of :doc:`smb.base.SharedDevice<smb_SharedDevice>` instances.
"""
if not self.instance:
raise NotConnectedError('Not connected to server')
d = defer.Deferred()
self.instance._listShares(d.callback, d.errback, timeout)
return d
def echo(self, data, timeout=10):
"""
Send an echo command containing *data* to the remote SMB/CIFS server. The remote SMB/CIFS will reply with the same *data*.
:param string data: Data to send to the remote server.
:param integer/float timeout: Number of seconds that pysmb will wait before raising *SMBTimeout* via the returned *Deferred* instance's *errback* method.
:return: A *twisted.internet.defer.Deferred* instance. The callback function will be called with the *data* parameter.
"""
if not self.instance:
raise NotConnectedError('Not connected to server')
d = defer.Deferred()
self.instance._echo(data, d.callback, d.errback, timeout)
return d
def deleteDirectory(self, service_name, path):
"""
Delete the empty folder at *path* on *service_name*
:param string/unicode service_name: Contains the name of the shared folder.
:param string/unicode path: The path of the to-be-deleted folder (relative to) the shared folder.
If the path contains non-English characters, an unicode string must be used to pass in the path.
:param integer/float timeout: Number of seconds that pysmb will wait before raising *SMBTimeout* via the returned *Deferred* instance's *errback* method.
:return: A *twisted.internet.defer.Deferred* instance. The callback function will be called with the *path* parameter.
"""
if not self.instance:
raise NotConnectedError('Not connected to server')
d = defer.Deferred()
self.instance._deleteDirectory(service_name, path, d.callback,
d.errback)
return d
def getAttributes(self, service_name, path, timeout=30):
"""
Retrieve information about the file at *path* on the *service_name*.
:param string/unicode service_name: the name of the shared folder for the *path*
:param string/unicode path: Path of the file on the remote server. If the file cannot be opened for reading, an :doc:`OperationFailure<smb_exceptions>` will be raised.
:return: A *twisted.internet.defer.Deferred* instance. The callback function will be called with a :doc:`smb.base.SharedFile<smb_SharedFile>` instance containing the attributes of the file.
"""
if not self.instance:
raise NotConnectedError('Not connected to server')
d = defer.Deferred()
self.instance._getAttributes(service_name,
path,
d.callback,
d.errback,
timeout=timeout)
return d
def rename(self, service_name, old_path, new_path):
"""
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.
:param string/unicode service_name: Contains the name of the shared folder.
:param integer/float timeout: Number of seconds that pysmb will wait before raising *SMBTimeout* via the returned *Deferred* instance's *errback* method.
:return: A *twisted.internet.defer.Deferred* instance. The callback function will be called with a 2-element tuple of ( *old_path*, *new_path* ).
"""
if not self.instance:
raise NotConnectedError('Not connected to server')
d = defer.Deferred()
self.instance._rename(service_name, old_path, new_path, d.callback,
d.errback)
return d
def listSnapshots(self, service_name, path, timeout=30):
"""
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.
:param string/unicode service_name: the name of the shared folder for the *path*
:param string/unicode path: path relative to the *service_name* where we are interested in the list of available snapshots
:return: A list of python *datetime.DateTime* instances in GMT/UTC time zone
"""
if not self.instance:
raise NotConnectedError('Not connected to server')
d = defer.Deferred()
self.instance._listSnapshots(service_name,
path,
d.callback,
d.errback,
timeout=timeout)
return d
def deleteFiles(self, service_name, path_file_pattern, timeout=30):
"""
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.
:param string/unicode service_name: Contains the name of the shared folder.
:param string/unicode path_file_pattern: The pathname of the file(s) to be deleted, relative to the service_name.
Wildcards may be used in th filename component of the path.
If your path/filename contains non-English characters, you must pass in an unicode string.
:param integer/float timeout: Number of seconds that pysmb will wait before raising *SMBTimeout* via the returned *Deferred* instance's *errback* method.
:return: A *twisted.internet.defer.Deferred* instance. The callback function will be called with the *path_file_pattern* parameter.
"""
if not self.instance:
raise NotConnectedError('Not connected to server')
d = defer.Deferred()
self.instance._deleteFiles(service_name,
path_file_pattern,
d.callback,
d.errback,
timeout=timeout)
return d
def listPath(self,
service_name,
path,
search=SMB_FILE_ATTRIBUTE_READONLY | SMB_FILE_ATTRIBUTE_HIDDEN
| SMB_FILE_ATTRIBUTE_SYSTEM | SMB_FILE_ATTRIBUTE_DIRECTORY
| SMB_FILE_ATTRIBUTE_ARCHIVE | SMB_FILE_ATTRIBUTE_INCL_NORMAL,
pattern='*',
timeout=30):
"""
Retrieve a directory listing of files/folders at *path*
For simplicity, pysmb defines a "normal" file as a file entry that is not read-only, not hidden, not system, not archive and not a directory.
It ignores other attributes like compression, indexed, sparse, temporary and encryption.
Note that the default search parameter will query for all read-only (SMB_FILE_ATTRIBUTE_READONLY), hidden (SMB_FILE_ATTRIBUTE_HIDDEN),
system (SMB_FILE_ATTRIBUTE_SYSTEM), archive (SMB_FILE_ATTRIBUTE_ARCHIVE), normal (SMB_FILE_ATTRIBUTE_INCL_NORMAL) files
and directories (SMB_FILE_ATTRIBUTE_DIRECTORY).
If you do not need to include "normal" files in the result, define your own search parameter without the SMB_FILE_ATTRIBUTE_INCL_NORMAL constant.
SMB_FILE_ATTRIBUTE_NORMAL should be used by itself and not be used with other bit constants.
:param string/unicode service_name: the name of the shared folder for the *path*
:param string/unicode path: path relative to the *service_name* where we are interested to learn about its files/sub-folders.
:param integer search: integer value made up from a bitwise-OR of *SMB_FILE_ATTRIBUTE_xxx* bits (see smb_constants.py).
:param string/unicode pattern: the filter to apply to the results before returning to the client.
:param integer/float timeout: Number of seconds that pysmb will wait before raising *SMBTimeout* via the returned *Deferred* instance's *errback* method.
:return: A *twisted.internet.defer.Deferred* instance. The callback function will be called with a list of :doc:`smb.base.SharedFile<smb_SharedFile>` instances.
"""
if not self.instance:
raise NotConnectedError('Not connected to server')
d = defer.Deferred()
self.instance._listPath(service_name,
path,
d.callback,
d.errback,
search=search,
pattern=pattern,
timeout=timeout)
return d
def storeFile(self, service_name, path, file_obj, timeout=30):
"""
Store the contents of the *file_obj* at *path* on the *service_name*.
:param string/unicode service_name: the name of the shared folder for the *path*
:param string/unicode path: Path of the file on the remote server. If the file at *path* does not exist, it will be created. Otherwise, it will be overwritten.
If the *path* refers to a folder or the file cannot be opened for writing, an :doc:`OperationFailure<smb_exceptions>` will be raised.
:param file_obj: A file-like object that has a *read* method. Data will read continuously from *file_obj* until EOF.
:return: Number of bytes uploaded
"""
if not self.sock:
raise NotConnectedError('Not connected to server')
results = []
def cb(r):
self.is_busy = False
results.append(r[1])
def eb(failure):
self.is_busy = False
raise failure
self.is_busy = True
try:
self._storeFile(service_name,
path,
file_obj,
cb,
eb,
timeout=timeout)
while self.is_busy:
self._pollForNetBIOSPacket(timeout)
finally:
self.is_busy = False
return results[0]
max_length=-1L,
timeout=30):
"""
Retrieve the contents of the file at *path* on the *service_name* and write these contents to the provided *file_obj*.
:param string/unicode service_name: the name of the shared folder for the *path*
:param string/unicode path: Path of the file on the remote server. If the file cannot be opened for reading, an :doc:`OperationFailure<smb_exceptions>` will be raised.
:param file_obj: A file-like object that has a *write* method. Data will be written continuously to *file_obj* up to *max_length* number of bytes.
:param integer/long offset: the offset in the remote *path* where the first byte will be read and written to *file_obj*. Must be either zero or a positive integer/long value.
:param integer/long max_length: maximum number of bytes to read from the remote *path* and write to the *file_obj*. Specify a negative value to read from *offset* to the EOF.
If zero, the method returns immediately after the file is opened successfully for reading.
:return: A 2-element tuple of ( 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)
"""
if not self.sock:
raise NotConnectedError('Not connected to server')
results = []
def cb(r):
self.is_busy = False
results.append(r[1:])
def eb(failure):
self.is_busy = False
raise failure
self.is_busy = True
try:
self._retrieveFileFromOffset(service_name,
path,