NFSClient Class

Properties   Methods   Events   Config Settings   Errors  

This class is used to create a Network File System (NFS) client based on NFS version 4.0.

Syntax

class nfssdk.NFSClient

Remarks

This class provides a simple way to create a Network File System (NFS) client, enabling seamless connection and access to files hosted on an NFS server.

Getting Started

To begin, the remote_host and remote_port properties should first be set to the host and port of the NFS server. By default, the remote_port property is set to 2049. The local_host and local_port properties may also be set to specify the name of the local host or user-assigned IP interface through which connections are initiated. Note that NFS exports may require that requests originate from a port less than 1024 (IPPORT_RESERVED). In this case, local_port should be manually specified.

The security_mechanism (and other related properties) may also be set beforehand. Please refer to the security section below for additional details.

Once set, the connect method should be called to initiate a connection to the server. For example:

component.RemoteHost = "10.0.1.123"; component.RemotePort = 2049; component.Connect();

Once the connection is successful (or fails), the on_connected event will fire accordingly, with details regarding the connection status. Assuming the connection was successful, the connected property will be set to True.

After successfully connecting to the NFS server, the remote_path will always be set to the root from the classes perspective, /.

If the server exports a specific directory (e.g., /mnt/mynfs), the class may need to navigate to this export manually by calling change_remote_path with the relevant export path.

In some server-side configurations, the client may already start in the exported directory upon a connection, allowing immediate access without additional navigation.

Security

Before connecting to the server, the security_mechanism should be set accordingly. This property may be set to one of the following mechanisms:

System Authentication

By default, security_mechanism is set to sys, enabling RPC system authentication (AUTH_SYS). In this case, the rpc_uid and rpc_gid properties are used to specify the UID and GID the class should perform the request as. These properties are set to 0 by default, indicating root access.

Note: This mechanism is not secure. Network packets are still transferred in plaintext. This mechanism is only recommended for systems operating over a local network.

Kerberos Authentication

For additional security, the security_mechanism may be set to krb5, krb5i, or krb5p to enable RPC Kerberos authentication (RPCSEC_GSS).

It is important to note the differences between the listed Kerberos security mechanisms. If krb5 is utilized, Kerberos will only be used to perform client authentication.

If krb5i is utilized, Kerberos will be used to perform client authentication and integrity protection, ensuring that incoming and outgoing packets are untampered. However, packets remain unencrypted, making sensitive data potentially visible to anyone monitoring the network.

If krb5p is utilized, Kerberos will be used to perform client authentication, integrity protection, and packet encryption, making this the most secure option.

If the security mechanism is set to any of the Kerberos security mechanisms, the following properties must also be set accordingly:

• kdc_host
• kdc_port
• spn
• user
• password or keytab_file

For example, connecting with a Kerberos security mechanism may look like:

// Configure general settings nfsclient.RemoteHost = "10.0.1.223"; nfsclient.RemotePort = 2049; nfsclient.SecurityMechanism = "krb5p"; // Configure kerberos settings nfsclient.KDCHost = "10.0.1.226"; nfsclient.User = "nfsclient@EXAMPLE.COM"; nfsclient.SPN = "nfs/nfs-server.example.com"; nfsclient.KeytabFile = "C:\\nfsclient.keytab"; // alternative to 'Password' nfsclient.Connect();

Navigating the Server

As mentioned previously, upon successfully connecting to the NFS server, the remote_path will always be set to the root from the classes perspective, /. change_remote_path may or may not need to be called to navigate to the relevant server-side export.

Regardless, many methods operate based on the current working directory of the class as identified by remote_path. For example, when calling list_directory, the directory contents of the current remote_path will be listed.

As such, the change_remote_path method can be used to change the current working directory of the class to some specified path. Both relative and absolute paths are supported with this method.

Absolute Paths

If the path begins with a /, it is considered an absolute path and must specify the entire path from the root of the server. For example:

component.ChangeRemotePath("/home/testuser/myfolder");

Relative Paths

If the path does not begin with a /, it is considered a relative path and is resolved in relation to the current directory. For instance, a value of myfolder will indicate a subfolder of the current directory. The special value .. refers to the parent directory of the current path. For example:

//Change to the 'myfolder' sub-directory component.ChangeRemotePath("myfolder"); //Navigate up two levels and then into the 'another/folder' path. component.ChangeRemotePath("../../another/folder");

Note that absolute and relative paths are supported for almost every class method that takes a file name and path as a parameter. Additionally, absolute and relative paths are supported by the remote_file property, which many methods make use of. For more information, please refer to the below section and individual method descriptions.

Managing Files and Directories

This section describes many different operations that can be performed on the NFS server. Before going into additional details, it is important to note that the behavior of many methods here operate depending on whether the specified remote_file or method parameter is an absolute or relative path.

If the specified remote_file or method parameter is an absolute path, the current remote_path will be ignored in favor of the absolute path. However, if the specified remote_file or method parameter is a relative path, the operation will be performed relative to the current remote_path.

File Lookup

To check whether a file or directory exists in the NFS server, the check_file_exists method may be used. This method will search for the object specified by remote_file. For example:

// Relative Path component.ChangeRemotePath("/home/testuser/myfolder"); component.RemoteFile = "test.txt"; // Checks for test.txt in /home/testuser/myfolder if(component.CheckFileExists()) { component.Download(); } // Absolute Path component.RemoteFile = "/home/test/test.txt"; // Checks for test.txt in /home/test if(component.CheckFileExists()) { component.Download(); }

Listing Directories

To list the contents of a directory, the list_directory method should be called to retrieve the entries of the current working directory (as indicated by the current remote_path).

The on_dir_list event will fire for each entry in the current directory. The remote_file property may be used to specify a file mask for filtering the entries returned via on_dir_list.

For example:

// List all text files in /home/test component.OnDirList += (o, e) => { Console.WriteLine("Dir Entry: " + e.FileName); }; component.ChangeRemotePath("/home/test"); component.RemoteFile = "*.txt"; component.ListDirectory();

Note: Because remote_file acts as a file mask, to retrieve a complete directory listing remote_file should be set to an empty string (or a mask like "*").

For more information about using remote_file as a filemask, please refer to the remote_file or list_directory documentation.

Create and Delete Objects

Files and directories may be created using create_file and make_directory, respectively. Note that create_file is used to create a new file containing no data. To create a new file with content, please refer to the upload method. For example:

// Create directory component.MakeDirectory("testdir"); // Create empty file in new directory component.ChangeRemotePath("testdir"); component.CreateFile("test.txt");

Files and directories may be deleted using delete_file and remove_directory, respectively. For example (based on the previous directory structure in the last example):

// Remove file created previously component.ChangeRemotePath("testdir"); component.DeleteFile("test.txt"); // Navigate out of directory component.ChangeRemotePath("../"); component.RemoveDirectory("testdir");

Uploading Files

As mentioned, create_file may be used to create a new, empty file. To upload a file with content, the upload method should be used. The remote_file property will specify the remote location to upload the local data to. If the remote_file exists and overwrite is set to false, an error will occur while uploading.

The class can either upload the specified local_file, or upload the contents of a stream, which can be set via set_upload_stream. When uploading via a stream, the CloseStreamAfterTransfer config may be set to determine whether or not to close the stream after the transfer (enabled by default).

As an alternative to upload, the upload_range method may be used to upload a specified number of bytes to a given position in the remote_file. This method can also be used to append data to the end of a file, however, the append method may be also be used for this purpose. For specific examples, please refer to the documentation for each method.

Downloading Files

To download the content of a file hosted on the server, the download method should be used. The remote_file property should be set to the remote file to download. The local_file property can be used to specify a local file to download the specified remote file to. If the local_file already exists and overwrite is false, an error will occur.

The class can either download the remote file contents to the specified local_file, or download the contents to a stream, which can be set via set_download_stream. When downloading via a stream, the CloseStreamAfterTransfer config may be set to determine whether or not to close the stream after the transfer (enabled by default).

As an alternative to download, the download_range method may be used to download a specified number of bytes to some local buffer.

Lastly, as an alternative to local_file or set_download_stream, the downloaded file contents are also available in the on_transfer event. Note the on_transfer event will always fire containing the transferred data, so data may be retrieved here even if local_file is set or set_download_stream is called. For specific examples, please refer to the documentation for each method.

Creating and Reading Links

The class supports creating hard links and symbolic links using the create_link method.

create_link takes three parameters, the name of the link to be created, the target of the link, and the type of link (hard link or symbolic link). Please see below for a simple example:

nfs.ChangeRemotePath("/nfs"); // Create symlink.txt in /nfs pointing to existing_file.txt in the same directory nfs.CreateLink("symlink.txt", "existing_file.txt", 0); // Create hardlink.txt in /nfs pointing to existing_file.txt in the same directory nfs.CreateLink("hardlink.txt", "existing_file.txt", 1);

To read a hard link, you can set the remote_file property to the name of the hard link, and call download (with the relevant local file or stream set).

However, reading a symbolic link requires some additional steps. First, the read_link method should be called, which will return a byte array containing the contents of the symbolic link as stored on the server. Typically, the contents are a file name that the link points to. Before going into detail, please see below for a simple example:

nfs.ChangeRemotePath("/nfs"); // Create symlink.txt in /nfs pointing to existing_file.txt in the same directory nfs.CreateLink("symlink.txt", "existing_file.txt", 0); // Read link byte[] linkData = nfs.ReadLink("symlink.txt"); string file = Encoding.UTF8.GetString(linkData); nfs.RemoteFile = file; nfs.LocalFile = "temp.txt"; nfs.Download();

In NFS v4.0, the contents of a symbolic link are treated as opaque (binary data) at the protocol level. The server stores this opaque data and returns this to the client when requested, meaning it is up to the client to interpret the link data.

Most of the time, the opaque data will represent the file the symbolic link is pointing to relative to the position of the symbolic link, meaning it can be converted to a UTF8 string representing this file. The contents of the file should then be downloaded by setting remote_file (and possibly remote_path) accordingly and calling download.

Handling File Attributes

The class provides a couple of ways to handle file attributes. As mentioned previously, when calling list_directory, the on_dir_list event will fire for each directory entry. During this event, the file_attributes collection will be populated with the attributes of the associated directory entry. Note that the attributes are only meant to be retrieved during this event, rather than set.

Outside of on_dir_list, the query_file_attributes method must be called to retrieve a file's attributes. After doing so, the file_attributes property will be populated accordingly.

To update relevant file attributes, the file_attributes property can be modified, and update_file_attributes can be called to make those changes remotely. Note that not all attributes are able to be modified. Please see below for a simple example:

// First, query attributes component.RemoteFile = "/home/test/test.txt"; component.QueryFileAttributes(); // Update OwnerId and OwnerGroupId of file component.FileAttributes.OwnerId = "1000"; component.FileAttributes.OwnerGroupId = "1000"; component.UpdateFileAttributes();

Property List

---

The following is the full list of the properties of the class with short descriptions. Click on the links for further details.

Method List

---

The following is the full list of the methods of the class with short descriptions. Click on the links for further details.

Event List

---

The following is the full list of the events fired by the class with short descriptions. Click on the links for further details.

Config Settings

---

The following is a list of config settings for the class with short descriptions. Click on the links for further details.

connected property

Whether the class is connected.

Syntax

def get_connected() -> bool: ...

connected = property(get_connected, None)

Default Value

FALSE

Remarks

This property is used to determine whether or not the class is connected to the remote host. Use the connect and disconnect methods to manage the connection.

This property is read-only.

file_access_time property

Contains the number of seconds since 12:00:00 AM, January 1, 1970, when this file was last accessed.

Syntax

def get_file_access_time() -> int: ...
def set_file_access_time(value: int) -> None: ...

file_access_time = property(get_file_access_time, set_file_access_time)

Default Value

0

Remarks

Contains the number of seconds since 12:00:00 AM, January 1, 1970, when this file was last accessed.

file_access_time_nanos property

Contains a subsecond value associated with this file's AccessTime .

Syntax

def get_file_access_time_nanos() -> int: ...
def set_file_access_time_nanos(value: int) -> None: ...

file_access_time_nanos = property(get_file_access_time_nanos, set_file_access_time_nanos)

Default Value

0

Remarks

Contains a subsecond value associated with this file's file_access_time.

file_allocation_size property

Number of file system bytes allocated to this file object.

Syntax

def get_file_allocation_size() -> int: ...

file_allocation_size = property(get_file_allocation_size, None)

Default Value

0

Remarks

Number of file system bytes allocated to this file object.

This property is read-only.

file_creation_time property

Specifies the number of seconds since 12:00:00 AM, January 1, 1970, when this file was created.

Syntax

def get_file_creation_time() -> int: ...

file_creation_time = property(get_file_creation_time, None)

Default Value

0

Remarks

Specifies the number of seconds since 12:00:00 AM, January 1, 1970, when this file was created.

This property is read-only.

file_creation_time_nanos property

Contains a subsecond value associated with this file's CreationTime .

Syntax

def get_file_creation_time_nanos() -> int: ...

file_creation_time_nanos = property(get_file_creation_time_nanos, None)

Default Value

0

Remarks

Contains a subsecond value associated with this file's file_creation_time.

This property is read-only.

file_type property

The type of file.

Syntax

def get_file_type() -> int: ...

file_type = property(get_file_type, None)

Possible Values

1   # REG
2   # DIR
3   # BLK
4   # CHR
5   # LNK
6   # SOCK
7   # FIFO
8   # ATTRDIR
9   # NAMEDATTR

Default Value

0

Remarks

The type of file. file_type may be one of the following values:

This property is read-only.

file_is_dir property

Specifies whether or not the file represented by these attributes is a directory.

Syntax

def get_file_is_dir() -> bool: ...

file_is_dir = property(get_file_is_dir, None)

Default Value

FALSE

Remarks

Specifies whether or not the file represented by these attributes is a directory.

This property is read-only.

file_is_symlink property

Specifies whether or not the file or directory represented by these attributes is a symbolic link.

Syntax

def get_file_is_symlink() -> bool: ...

file_is_symlink = property(get_file_is_symlink, None)

Default Value

FALSE

Remarks

Specifies whether or not the file or directory represented by these attributes is a symbolic link.

This property is read-only.

file_link_count property

Number of hard links to this object.

Syntax

def get_file_link_count() -> int: ...

file_link_count = property(get_file_link_count, None)

Default Value

0

Remarks

Number of hard links to this object.

This property is read-only.

file_mime_type property

Specifies a value that can be used in the Content-Type header for a MIME entity part containing this file.

Syntax

def get_file_mime_type() -> str: ...

file_mime_type = property(get_file_mime_type, None)

Default Value

""

Remarks

Specifies a value that can be used in the Content-Type header for a MIME entity part containing this file.

This property is read-only.

file_mode property

Mode of a file.

Syntax

def get_file_mode() -> int: ...
def set_file_mode(value: int) -> None: ...

file_mode = property(get_file_mode, set_file_mode)

Default Value

0

Remarks

Mode of a file

file_modified_time property

Specifies the number of seconds since 12:00:00 AM, January 1, 1970, that this file was last modified.

Syntax

def get_file_modified_time() -> int: ...
def set_file_modified_time(value: int) -> None: ...

file_modified_time = property(get_file_modified_time, set_file_modified_time)

Default Value

0

Remarks

Specifies the number of seconds since 12:00:00 AM, January 1, 1970, that this file was last modified.

file_modified_time_nanos property

Includes a subsecond value associated with this file's ModifiedTime .

Syntax

def get_file_modified_time_nanos() -> int: ...
def set_file_modified_time_nanos(value: int) -> None: ...

file_modified_time_nanos = property(get_file_modified_time_nanos, set_file_modified_time_nanos)

Default Value

0

Remarks

Includes a subsecond value associated with this file's file_modified_time.

file_owner_group_id property

The string name of the group ownership of this object.

Syntax

def get_file_owner_group_id() -> str: ...
def set_file_owner_group_id(value: str) -> None: ...

file_owner_group_id = property(get_file_owner_group_id, set_file_owner_group_id)

Default Value

""

Remarks

The string name of the group ownership of this object.

file_owner_id property

The string name of the owner of this object.

Syntax

def get_file_owner_id() -> str: ...
def set_file_owner_id(value: str) -> None: ...

file_owner_id = property(get_file_owner_id, set_file_owner_id)

Default Value

""

Remarks

The string name of the owner of this object.

file_size property

Specifies the total size, in bytes, of this file.

Syntax

def get_file_size() -> int: ...
def set_file_size(value: int) -> None: ...

file_size = property(get_file_size, set_file_size)

Default Value

0

Remarks

Specifies the total size, in bytes, of this file.

firewall_auto_detect property

Whether to automatically detect and use firewall system settings, if available.

Syntax

def get_firewall_auto_detect() -> bool: ...
def set_firewall_auto_detect(value: bool) -> None: ...

firewall_auto_detect = property(get_firewall_auto_detect, set_firewall_auto_detect)

Default Value

FALSE

Remarks

Whether to automatically detect and use firewall system settings, if available.

firewall_type property

The type of firewall to connect through.

Syntax

def get_firewall_type() -> int: ...
def set_firewall_type(value: int) -> None: ...

firewall_type = property(get_firewall_type, set_firewall_type)

Possible Values

0   # None
1   # Tunnel
2   # SOCKS4
3   # SOCKS5
10   # SOCKS4A

Default Value

0

Remarks

The type of firewall to connect through. The applicable values are as follows:

firewall_host property

The name or IP address of the firewall (optional).

Syntax

def get_firewall_host() -> str: ...
def set_firewall_host(value: str) -> None: ...

firewall_host = property(get_firewall_host, set_firewall_host)

Default Value

""

Remarks

The name or IP address of the firewall (optional). If a firewall_host is given, the requested connections will be authenticated through the specified firewall when connecting.

If this property is set to a Domain Name, a DNS request is initiated. Upon successful termination of the request, this property is set to the corresponding address. If the search is not successful, the class fails with an error.

firewall_password property

A password if authentication is to be used when connecting through the firewall.

Syntax

def get_firewall_password() -> str: ...
def set_firewall_password(value: str) -> None: ...

firewall_password = property(get_firewall_password, set_firewall_password)

Default Value

""

Remarks

A password if authentication is to be used when connecting through the firewall. If firewall_host is specified, the firewall_user and firewall_password properties are used to connect and authenticate to the given firewall. If the authentication fails, the class fails with an error.

firewall_port property

The Transmission Control Protocol (TCP) port for the firewall Host .

Syntax

def get_firewall_port() -> int: ...
def set_firewall_port(value: int) -> None: ...

firewall_port = property(get_firewall_port, set_firewall_port)

Default Value

0

Remarks

The Transmission Control Protocol (TCP) port for the firewall firewall_host. See the description of the firewall_host property for details.

Note: This property is set automatically when firewall_type is set to a valid value. See the description of the firewall_type property for details.

firewall_user property

A username if authentication is to be used when connecting through a firewall.

Syntax

def get_firewall_user() -> str: ...
def set_firewall_user(value: str) -> None: ...

firewall_user = property(get_firewall_user, set_firewall_user)

Default Value

""

Remarks

A username if authentication is to be used when connecting through a firewall. If firewall_host is specified, this property and the firewall_password property are used to connect and authenticate to the given Firewall. If the authentication fails, the class fails with an error.

kdc_host property

Specifies domain name or IP address of the Key Distribution Center (KDC).

Syntax

def get_kdc_host() -> str: ...
def set_kdc_host(value: str) -> None: ...

kdc_host = property(get_kdc_host, set_kdc_host)

Default Value

""

Remarks

This property specifies the domain name or IP address of the Key Distribution Center (KDC).

If this property is set to a Domain Name, a DNS request is initiated and upon successful termination of the request, this property is set to the corresponding address. If the search is not successful, an error is returned.

Note that this property is only applicable when security_mechanism is set to krb5, krb5i, or krb5p.

kdc_port property

Specifies the port for the Key Distribution Center (KDC).

Syntax

def get_kdc_port() -> int: ...
def set_kdc_port(value: int) -> None: ...

kdc_port = property(get_kdc_port, set_kdc_port)

Default Value

88

Remarks

This property specifies the port for the Key Distribution Center (KDC). The default value is 88.

Note that this property is only applicable when security_mechanism is set to krb5, krb5i, or krb5p.

keytab_file property

Specifies the path to the Kerberos Keytab file.

Syntax

def get_keytab_file() -> str: ...
def set_keytab_file(value: str) -> None: ...

keytab_file = property(get_keytab_file, set_keytab_file)

Default Value

""

Remarks

This property specifies the path to a Kerberos Keytab file.

If specified, the credentials for a specific user are read from this file, assuming an entry for the user exists in the file. The password should not be specified if using a Keytab file.

Note that this property is only applicable when security_mechanism is set to krb5, krb5i, or krb5p.

local_file property

This is the path to a local file for download or upload. If the file exists, it is overwritten.

Syntax

def get_local_file() -> str: ...
def set_local_file(value: str) -> None: ...

local_file = property(get_local_file, set_local_file)

Default Value

""

Remarks

This property is used by the upload and download methods to specify the path to a local file to be downloaded or uploaded. See the method descriptions for more information.

Example (Setting LocalFile)

// Download remotefile.txt to C:\\localfile.txt component.LocalFile = "C:\\localfile.txt"; component.RemoteFile = "remotefile.txt"; component.Download(); // Upload C:\\localfile2.txt to folder/remotefile2.txt component.LocalFile = "C:\\localfile2.txt"; component.RemoteFile = "folder/remotefile2.txt"; component.Upload();

local_host property

The name of the local host or user-assigned IP interface through which connections are initiated or accepted.

Syntax

def get_local_host() -> str: ...
def set_local_host(value: str) -> None: ...

local_host = property(get_local_host, set_local_host)

Default Value

""

Remarks

This property contains the name of the local host as obtained by the gethostname() system call, or if the user has assigned an IP address, the value of that address.

In multihomed hosts (machines with more than one IP interface) setting LocalHost to the IP address of an interface will make the class initiate connections (or accept in the case of server classs) only through that interface. It is recommended to provide an IP address rather than a hostname when setting this property to ensure the desired interface is used.

If the class is connected, the local_host property shows the IP address of the interface through which the connection is made in internet dotted format (aaa.bbb.ccc.ddd). In most cases, this is the address of the local host, except for multihomed hosts (machines with more than one IP interface).

Note: local_host is not persistent. You must always set it in code, and never in the property window.

local_port property

The TCP port in the local host where the class binds.

Syntax

def get_local_port() -> int: ...
def set_local_port(value: int) -> None: ...

local_port = property(get_local_port, set_local_port)

Default Value

0

Remarks

This property must be set before a connection is attempted. It instructs the class to bind to a specific port (or communication endpoint) in the local machine.

Setting this property to 0 (default) enables the system to choose an open port at random. The chosen port will be returned by the local_port property after the connection is established.

local_port cannot be changed once a connection is made. Any attempt to set this property when a connection is active will generate an error.

This property is useful when trying to connect to services that require a trusted port on the client side.

Note: NFS exports may require that requests originate from a port less than 1024 (IPPORT_RESERVED). In this case, this property should be manually specified.

overwrite property

This indicates whether the class should overwrite the local or remote file during a download or upload.

Syntax

def get_overwrite() -> bool: ...
def set_overwrite(value: bool) -> None: ...

overwrite = property(get_overwrite, set_overwrite)

Default Value

FALSE

Remarks

This property indicates whether the class should overwrite any local or remote files when calling download, upload, or create_file.

When uploading and overwrite is false, an error will be thrown if the specified remote_file exists. When true, the remote_file will be overwritten.

When downloading and overwrite is false, an error will be thrown if the specified local_file exists. When true, the local_file will be overwritten.

password property

Specifies the password of the User to authenticate.

Syntax

def get_password() -> str: ...
def set_password(value: str) -> None: ...

password = property(get_password, set_password)

Default Value

""

Remarks

This property specifies the password of the user to authenticate.

Note that this property is only applicable when security_mechanism is set to krb5, krb5i, or krb5p.

remote_file property

This is the name of the remote file for uploading, downloading, and performing other operations.

Syntax

def get_remote_file() -> str: ...
def set_remote_file(value: str) -> None: ...

remote_file = property(get_remote_file, set_remote_file)

Default Value

""

Remarks

This property contains the name of the remote file to be uploaded or downloaded and is either an absolute file path or a relative path based on the remote path set by calling change_remote_path.

A number of methods use remote_file as an argument.

Example 1. Setting RemoteFile:

component.LocalFile = "C:\\localfile.txt"; component.RemoteFile = "remotefile.txt"; component.Download(); component.LocalFile = "C:\\localfile2.txt"; component.RemoteFile = "folder/remotefile2.txt"; component.Download();

Note: This property will also act as a file mask when calling list_directory.

Example 2. Using RemoteFile as a file mask: component.RemoteFile = "*.txt" component.ListDirectory()

The following special characters are supported for pattern matching:

If these characters need to be used as a literal in a pattern, then they must be escaped by surrounding them with brackets []. Note: "]" and "-" do not need to be escaped. See below for the escape sequences:

For example, to match the value [Something].txt, specify the pattern [[]Something].txt.

remote_host property

Specifies the address of the NFS server.

Syntax

def get_remote_host() -> str: ...
def set_remote_host(value: str) -> None: ...

remote_host = property(get_remote_host, set_remote_host)

Default Value

""

Remarks

This property specifies the IP address (IP number in dotted internet format) or the domain name of the NFS server. It is set before a connection is attempted and should not be changed once a connection is established.

remote_path property

Specifies the current path in the NFS server.

Syntax

def get_remote_path() -> str: ...

remote_path = property(get_remote_path, None)

Default Value

""

Remarks

This property specifies the current working directory on the NFS server. The change_remote_path method can be used to change the working directory to an absolute path or to a relative path with respect to the current value of remote_path.

Example. Changing Directory:

component.RemoteHost = "nfs.server.net"; component.RemotePort = 2049; component.Connect(); component.ChangeRemotePath("/home/user"); Console.WriteLine(component.RemotePath); // Outputs "/home/user"

This property is read-only.

remote_port property

Specifies the port the NFS server is listening on.

Syntax

def get_remote_port() -> int: ...
def set_remote_port(value: int) -> None: ...

remote_port = property(get_remote_port, set_remote_port)

Default Value

2049

Remarks

This property specifies the port the NFS server is listening on (i.e., the port the class will connect to).By default, this value is 2049.

A valid port number (a value between 1 and 65535) is required for the connection to take place. The property must be set before a connection is attempted and cannot be changed once a connection is established. Any attempt to change this property while connected will fail with an error.

rpc_gid property

Specifies the group identifier (GID) associated with requests during RPC system authentication.

Syntax

def get_rpc_gid() -> int: ...
def set_rpc_gid(value: int) -> None: ...

rpc_gid = property(get_rpc_gid, set_rpc_gid)

Default Value

0

Remarks

This property specifies the group identifier (GID) associated with requests during RPC system authentication (AUTH_SYS).

The specified GID will be sent in all outgoing requests in order to identify the relevant primary group of the user making the request. The user can be identified by the rpc_uid property.

Note this property is only applicable when security_mechanism is set to sys.

rpc_uid property

Specifies the user identifier (UID) associated with requests during RPC system authentication.

Syntax

def get_rpc_uid() -> int: ...
def set_rpc_uid(value: int) -> None: ...

rpc_uid = property(get_rpc_uid, set_rpc_uid)

Default Value

0

Remarks

This property specifies the user identifier (UID) associated with requests during RPC system authentication (AUTH_SYS).

The specified UID will be sent in all outgoing requests in order to identify the user making the request.

Note this property is only applicable when security_mechanism is set to sys.

security_mechanism property

Specifies the RPC security mechanism the client should use when connecting to the NFS Server.

Syntax

def get_security_mechanism() -> str: ...
def set_security_mechanism(value: str) -> None: ...

security_mechanism = property(get_security_mechanism, set_security_mechanism)

Default Value

"sys"

Remarks

This property specifies the RPC security mechanism the client should use when connecting to the NFS server.

This property may be set to one of the following mechanisms:

By default, this property is set to sys, and only system authentication is supported. When set to sys, the following properties may be set to specify the UID and GID the class should perform the request as:

• rpc_uid
• rpc_gid

Kerberos Security Mechanisms

It is important to note the differences between the listed Kerberos security mechanisms. If krb5 is utilized, Kerberos will only be used to perform client authentication.

If krb5i is utilized, Kerberos will be used to perform client authentication and integrity protection, ensuring that incoming and outgoing packets are untampered. However, packets remain unencrypted, making sensitive data potentially visible to anyone monitoring the network.

If krb5p is utilized, Kerberos will be used to perform client authentication, integrity protection, and packet encryption, making this the most secure option.

If the security mechanism is set to any of the Kerberos security mechanisms, the following properties must also be set accordingly:

• kdc_host
• kdc_port
• spn
• user
• password or keytab_file

For example, connecting with a Kerberos security mechanism may look like:

// Configure general settings nfsclient.RemoteHost = "10.0.1.223"; nfsclient.RemotePort = 2049; nfsclient.SecurityMechanism = "krb5p"; // Configure kerberos settings nfsclient.KDCHost = "10.0.1.226"; nfsclient.User = "nfsclient@EXAMPLE.COM"; nfsclient.SPN = "nfs/nfs-server.example.com"; nfsclient.KeytabFile = "C:\\nfsclient.keytab"; // alternative to 'Password' nfsclient.Connect();

spn property

Specifies the Service Principal Name (SPN).

Syntax

def get_spn() -> str: ...
def set_spn(value: str) -> None: ...

spn = property(get_spn, set_spn)

Default Value

""

Remarks

This property specifies the Service Principal Name (SPN) that the user is attempting to access. This should be set to the SPN of the remote NFS Server, if applicable.

Note that this property is only applicable when security_mechanism is set to krb5, krb5i, or krb5p.

start_byte property

The offset in bytes at which to begin the Upload or Download.

Syntax

def get_start_byte() -> int: ...
def set_start_byte(value: int) -> None: ...

start_byte = property(get_start_byte, set_start_byte)

Default Value

0

Remarks

The start_byte property is used by the upload and download methods to determine at what offset to begin the transfer. This allows for resuming both uploads and downloads. The value of this property is reset to 0 after a successful transfer.

When downloading a file, this property specifies both the starting position in the remote_file to read from, as well as the starting position in the local_file (or stream, if using set_download_stream) to write to.

When uploading a file, this property specifies both the starting position in the local_file (or stream, if using set_upload_stream) to read from, as well as the starting position in the remote_file to write to.

Please see below for a simple example of resuming an upload:

long bytesTransferred = 0; component.OnTransfer += (o, e) => { bytesTransferred = e.BytesTransferred; }; component.LocalFile = "C:\nfs\test.txt"; component.RemoteFile = "test.txt"; bool uploadSuccessful = false; int maxRetries = 5; int retryCount = 0; while (!uploadSuccessful) { try { component.StartByte = bytesTransferred; // 0 initially, updated by Transfer event as necessary component.Upload(); uploadSuccessful = true; } catch (NFSSDKException ex) { retryCount++; if (retryCount >= maxRetries) { Console.WriteLine("Max retry attempts reached. Upload failed."); throw ex; } } }

timeout property

This property includes the timeout for the class.

Syntax

def get_timeout() -> int: ...
def set_timeout(value: int) -> None: ...

timeout = property(get_timeout, set_timeout)

Default Value

60

Remarks

If the timeout property is set to 0, all operations return immediately, potentially failing with a WOULDBLOCK error if data cannot be sent immediately.

If timeout is set to a positive value, data is sent in a blocking manner and the class will wait for the operation to complete before returning control. The class will handle any potential WOULDBLOCK errors internally and automatically retry the operation for a maximum of timeout seconds.

The class will use do_events to enter an efficient wait loop during any potential waiting period, making sure that all system events are processed immediately as they arrive. This ensures that the host application does not freeze and remains responsive.

If timeout expires, and the operation is not yet complete, the class fails with an error.

Note: By default, all timeouts are inactivity timeouts, that is, the timeout period is extended by timeout seconds when any amount of data is successfully sent or received.

The default value for the timeout property is 60 seconds.

user property

Specifies the name and domain of the user to authenticate.

Syntax

def get_user() -> str: ...
def set_user(value: str) -> None: ...

user = property(get_user, set_user)

Default Value

""

Remarks

This property specifies the name and realm/domain of the user to authenticate.

The value specified must be in one of the following formats:

• user@domain
• domain/user

Note that this property is only applicable when security_mechanism is set to krb5, krb5i, or krb5p.

abort method

Aborts the current upload or download.

Syntax

def abort() -> None: ...

Remarks

This method is used to abort the current upload or download.

append method

Appends data from LocalFile to a remote file RemoteFile on a NFS server.

Syntax

def append() -> None: ...

Remarks

This method is similar to the upload method, but the local file specified by local_file is appended to remote_file on the server as opposed to replacing it as with the upload method. remote_file is either an absolute path on the server or a path relative to remote_path. The server will create a file with that name if it does not already exist (similar to upload).

change_remote_path method

Changes the current path on the server.

Syntax

def change_remote_path(remote_path: str) -> None: ...

Remarks

This method changes the current path on the server to the specified RemotePath parameter. When called, the class will issue a command to the server to change the directory. The RemotePath parameter may hold an absolute or relative path.

The current path on the server can be found by querying the remote_path property.

Absolute Paths

If the path begins with a /, it is considered an absolute path and must specify the entire path from the root of the server. For example:

component.ChangeRemotePath("/home/testuser/myfolder");

Relative Paths

If the path does not begin with a /, it is considered a relative path and is resolved in relation to the current directory. For instance, a value of myfolder will indicate a subfolder of the current directory. The special value .. refers to the parent directory of the current path. For example:

//Change to the 'myfolder' sub-directory component.ChangeRemotePath("myfolder"); //Navigate up two levels and then into the 'another/folder' path. component.ChangeRemotePath("../../another/folder");

check_file_exists method

Checks whether the file specified by RemoteFile exists on the server.

Syntax

def check_file_exists() -> bool: ...

Remarks

This method checks whether the file specified by remote_file exists on the server. If the file exists, this method returns True, otherwise it returns False. remote_file must be specified before calling this method.

The remote_file can either specify the absolute path to the file, or a relative path based on the current working directory (indicated by the remote_path property). For instance:

// Relative Path component.ChangeRemotePath("/home/testuser/myfolder"); component.RemoteFile = "test.txt"; // Checks for test.txt in /home/testuser/myfolder if(component.CheckFileExists()) { component.Download(); } // Absolute Path component.RemoteFile = "/home/test/test.txt"; // Checks for test.txt in /home/test if(component.CheckFileExists()) { component.Download(); }

config method

Sets or retrieves a configuration setting.

Syntax

def config(configuration_string: str) -> str: ...

Remarks

config is a generic method available in every class. It is used to set and retrieve configuration settings for the class.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

connect method

This method connects to the NFS server.

Syntax

def connect() -> None: ...

Remarks

This method establishes a connection with the NFS server specified by remote_host and remote_port.

Prior to calling this method, the security_mechanism should be set appropriately, along with properties relevant to the specified mechanism. For example:

component.RemoteHost = "10.0.1.67"; component.RemotePort = 2049; component.Connect();

create_file method

Creates a file on the NFS server.

Syntax

def create_file(file_name: str) -> None: ...

Remarks

This method creates an empty file on the server with the name specified by the FileName parameter.

If the specified FileName already exists, and overwrite is false, an error will be thrown.

To upload a file with content, use upload instead.

create_link method

Creates a hard link or symbolic link on the server.

Syntax

def create_link(link_name: str, link_target: str, link_type: int) -> None: ...

Remarks

This method is used to create a hard link or symbolic link on the server.

The LinkName parameter is the name of the link to create, and is either an absolute path on the server or a path relative to remote_path.

The LinkTarget parameter specifies the target of the link.

The LinkType parameter indicates what type of link the class should attempt to create. Possible values are 0 or 1.

If specified as 0, the class will attempt to create a symbolic link pointing to the data (typically a file name) specified by the LinkTarget parameter.

If specified as 1, the class will attempt to create a hard link pointing to the file name specified by the LinkTarget parameter. Note that in this case, the LinkTarget is either an absolute path on the server or a path relative to remote_path. Please see below for a simple example.

nfs.ChangeRemotePath("/nfs"); // Create symlink.txt in /nfs pointing to existing_file.txt in the same directory nfs.CreateLink("symlink.txt", "existing_file.txt", 0); // Create hardlink.txt in /nfs pointing to existing_file.txt in the same directory nfs.CreateLink("hardlink.txt", "existing_file.txt", 1);

delete_file method

This method removes a file specified by FileName from the server.

Syntax

def delete_file(file_name: str) -> None: ...

Remarks

This method is used to remove a file specified by FileName from the server. The remote file or directory specified by FileName is deleted.

The FileName parameter is either an absolute path on the server, or a path relative to remote path set by change_remote_path. For example:

// Delete test.txt in /home/test directory component.ChangeRemotePath("/home/test"); component.DeleteFile("test.txt"); // Alternatively... component.DeleteFile("/home/test/test.txt");

disconnect method

This method disconnects from the NFS server.

Syntax

def disconnect() -> None: ...

Remarks

This method is used to disconnect from the NFS server.

do_events method

This method processes events from the internal message queue.

Syntax

def do_events() -> None: ...

Remarks

The method checks for events to process, such as incoming data, and fires corresponding events as necessary. If there are no events to process, the method waits for a time specified by the SelectWaitMillis configuration setting before returning.

Windows: By default, the server socket uses Windows messages, and do_events dispatches Windows messages internally. It is not necessary to call do_events from Windows GUI applications as these applications have an internal message dispatch loop. When called, this method must be called in the same thread or task in which the start_listening and stop_listening methods are called.

To avoid using Windows messages and a dispatch loop, set UseWindowsMessages to False. The application still needs to call this do_events method to let the class handle socket updates, but when Windows messages are not used, do_events and stop_listening may be called from a separate thread or task.

Linux: The method may be called from any worker thread, and events will fire in this thread.

macOS: In GUI applications, it is not necessary to call this method as the class registers itself in the main message loop. In other applications, the method may be called from any worker thread, and events will fire in this thread.

download method

This method downloads a remote file from the NFS server.

Syntax

def download() -> None: ...

Remarks

This method is used to download a remote file, specified by remote_file, from the NFS server.

The local_file property can be used to specify a local file to download the specified remote file to. If the local_file already exists and overwrite is false, an error will occur.

Alternatively, the set_download_stream method can be called to download the file contents to the specified stream. In this case, calling set_download_stream will automatically reset the value of local_file.

As an alternative to setting local_file or calling set_download_stream, the downloaded file contents are also available in the on_transfer event. Note that the downloaded data is always available via on_transfer, regardless of whether the data is downloaded to a stream or file (or neither).

For example:

// Using LocalFile component.RemoteFile = "/home/test/test.txt"; component.LocalFile = "C:\\nfsdir\\test.txt"; component.Download(); // Using SetDownloadStream FileStream fs = new FileStream("C:\\nfsdir\\test.txt", FileMode.Open); component.RemoteFile = "/home/test/test.txt"; component.SetDownloadStream(fs); component.Download();

download_range method

This method downloads a specific segment of a remote file from a NFS server.

Syntax

def download_range(path: str, file_name: str, start_byte: int, count: int, buffer: bytes) -> int: ...

Remarks

This method is used to download a specific segment of a remote file specified by Path and FileName.

StartByte is the offset (in bytes) relative to the beginning of the file from where to start reading, and Count is the number of bytes to read into the specified Buffer.

This functionality is particularly useful for efficient management of large files and targeted data retrieval within them. This method will return the total number of bytes read into the buffer.

Note: If the requested range extends beyond the end of the file, only the available bytes will be returned.

For example:

// E.g., downloading first 5 bytes of file byte[] downloadBuffer = new byte[5]; component.DownloadRange("/home/test", "test.txt", 0, downloadBuffer.Length, downloadBuffer);

list_directory method

This method lists the current working directory on the NFS server.

Syntax

def list_directory() -> None: ...

Remarks

This method is used to list the current working directory on the NFS server, as indicated by the current remote_path.

The on_dir_list event will fire for each entry in the current directory. The remote_file property may be used to specify a file mask for filtering the entries returned via on_dir_list.

For example:

// List all text files in /home/test component.OnDirList += (o, e) => { Console.WriteLine("Dir Entry: " + e.FileName); }; component.ChangeRemotePath("/home/test"); component.RemoteFile = "*.txt"; component.ListDirectory();

Note: Because remote_file acts as a file mask, to retrieve a complete directory listing remote_file should be set to an empty string (or a mask like "*").

The following special characters are supported for pattern matching:

If these characters need to be used as a literal in a pattern, then they must be escaped by surrounding them with brackets []. Note: "]" and "-" do not need to be escaped. See below for the escape sequences:

For example, to match the value [Something].txt, specify the pattern [[]Something].txt.

make_directory method

This method is used to create a directory on the NFS server.

Syntax

def make_directory(new_dir: str) -> None: ...

Remarks

This method is used to create a directory with a path specified by NewDir on the NFS server.

NewDir is either an absolute path on the server, or a path relative to the remote_path that is set by calling change_remote_path.

query_file_attributes method

This method queries the server for the file attributes of the specified RemoteFile .

Syntax

def query_file_attributes() -> None: ...

Remarks

This method is used to query the server for file attributes of the specified remote_file. After calling this method, the file_attributes property will be populated with the values returned by the server.

To update attributes, modify the desired values in file_attributes and call update_file_attributes. Please see below for a simple example:

// First, query attributes component.RemoteFile = "/home/test/test.txt"; component.QueryFileAttributes(); // Update OwnerId and OwnerGroupId of file component.FileAttributes.OwnerId = "1000"; component.FileAttributes.OwnerGroupId = "1000"; component.UpdateFileAttributes();

read_link method

Reads a symbolic link on the server.

Syntax

def read_link(link_name: str) -> bytes: ...

Remarks

This method is used to read a symbolic link on the server.

The LinkName parameter specifies the name of the symbolic link, and is either an absolute path on the server or a path relative to remote_path.

This method will return a byte array containing the contents of the symbolic link as stored on the server. In NFS v4.0, the contents of a symbolic link are treated as opaque (binary data) at the protocol level. The server simply stores this opaque data, and returns this to the client when requested, meaning it is up to the client to interpret the link data.

Most of the time, the opaque data will represent the file the symbolic link is pointing to relative to the position of the symbolic link, meaning it can be converted to a UTF8 string representing this file. The contents of the file should then be downloaded by setting remote_file (and possibly remote_path) accordingly and calling download.

Please see below for a simple example of reading the contents of a symbolic link, and reading the file pointed to by the symbolic link.

nfs.ChangeRemotePath("/nfs"); // Create symlink.txt in /nfs pointing to existing_file.txt in the same directory nfs.CreateLink("symlink.txt", "existing_file.txt", 0); // Read link byte[] linkData = nfs.ReadLink("symlink.txt"); string file = Encoding.UTF8.GetString(linkData); nfs.RemoteFile = file; nfs.LocalFile = "temp.txt"; nfs.Download();

remove_directory method

This removes a directory specified by DirName from the NFS server.

Syntax

def remove_directory(dir_name: str) -> None: ...

Remarks

This method is used to remove a directory with path specified by DirName from the NFS server. DirName is either an absolute path on the server, or a path relative to the remote_path that is set by calling change_remote_path.

rename_file method

This changes the name of RemoteFile to NewName .

Syntax

def rename_file(new_name: str) -> None: ...

Remarks

This method is used to change the name of a remote file, specified by remote_file, to NewName. remote_file and NewName are either absolute paths on the server, or a path relative to remote_path that is set by calling change_remote_path.

reset method

This method will reset the class.

Syntax

def reset() -> None: ...

Remarks

This method will reset the class's properties to their default values.

update_file_attributes method

This method updates the FileAttributes for the current RemoteFile .

Syntax

def update_file_attributes() -> None: ...

Remarks

This method is used to update the file_attributes for the current remote_file. After calling this method, the class will send any set file_attributes to the server.

For example:

// First, query attributes component.RemoteFile = "/home/test/test.txt"; component.QueryFileAttributes(); // Update OwnerId and OwnerGroupId of file component.FileAttributes.OwnerId = "1000"; component.FileAttributes.OwnerGroupId = "1000"; component.UpdateFileAttributes();

upload method

This method uploads a file to the NFS server.

Syntax

def upload() -> None: ...

Remarks

This method is used to upload a file to the NFS server.

The remote_file property is used to specify the remote location to upload the local data to. If the remote_file already exists and overwrite is false, an error will occur while uploading.

The local_file property can be used to specify a local file to upload to the specified remote location.

Alternatively, the set_upload_stream method can be called to upload the contents of a given stream. In this case, calling set_upload_stream will automatically reset the value of local_file.

The uploaded data will be made available in the on_transfer event. Please see below for a simple example.

// Using LocalFile component.LocalFile = "C:\\nfsdir\\test.txt"; component.RemoteFile = "/home/test/test.txt"; component.Upload(); // Using SetDownloadStream FileStream fs = new FileStream("C:\\nfsdir\\test.txt", FileMode.Open); component.SetUploadStream(fs); component.RemoteFile = "/home/test/test.txt"; component.Upload();

upload_range method

This method uploads a specific segment of data into a remote file on the NFS server.

Syntax

def upload_range(path: str, file_name: str, start_byte: int, count: int, buffer: bytes) -> None: ...

Remarks

This method is used to upload a specific segment of data into a remote file specified by Path and FileName. Count bytes will be updated from the provided Buffer starting in the remote file at the StartByte offset.

This functionality enables precise control over the insertion of data into a remote file, allowing for targeted modifications, overwriting, or additions starting from a specific position within the file.

Note: If the offset specified is beyond the file length, empty bytes will be created between the last file byte and the uploaded buffer.

For example:

// E.g., appending data to EOF component.RemoteFile = "/home/test/test.txt"; component.QueryFileAttributes(); int startByte = component.FileAttributes.Size; byte[] buffer = Encoding.Default.GetBytes("Upload these bytes"); component.UploadRange("/home/test", "test.txt", startByte, buffer.Length, buffer);

on_connected event

Fired immediately after a connection completes (or fails).

Syntax

class NFSClientConnectedEventParams(object):
  @property
  def status_code() -> int: ...

  @property
  def description() -> str: ...

# In class NFSClient:
@property
def on_connected() -> Callable[[NFSClientConnectedEventParams], None]: ...
@on_connected.setter
def on_connected(event_hook: Callable[[NFSClientConnectedEventParams], None]) -> None: ...

Remarks

If the connection is made normally, StatusCode is 0 and Description is "OK".

If the connection fails, StatusCode has the error code returned by the Transmission Control Protocol (TCP)/IP stack. Description contains a description of this code. The value of StatusCode is equal to the value of the error.

Please refer to the Error Codes section for more information.

on_dir_list event

This event fires when a directory entry is received.

Syntax

class NFSClientDirListEventParams(object):
  @property
  def dir_entry() -> str: ...

  @property
  def file_name() -> str: ...

  @property
  def is_dir() -> bool: ...

  @property
  def file_size() -> int: ...

  @property
  def file_time() -> str: ...

  @property
  def is_symlink() -> bool: ...

# In class NFSClient:
@property
def on_dir_list() -> Callable[[NFSClientDirListEventParams], None]: ...
@on_dir_list.setter
def on_dir_list(event_hook: Callable[[NFSClientDirListEventParams], None]) -> None: ...

Remarks

The on_dir_list events are fired when a directory listing is received as a response to a list_directory call.

The on_start_transfer and on_end_transfer events mark the beginning and end of the event stream.

The DirEntry parameter contains the filename when list_directory is called and includes extended file information when list_directory_long is called.

The class tries to fill out the FileName, IsDir, FileSize, and FileTime parameters when calling the list_directory_long method. Except for FileName, these parameters are empty when a short "List Directory" is performed.

In Unix systems, the date is given in two types of formats: If the date is in the past 12 months the exact time is specified and the year is omitted. Otherwise, only the date and the year, but not hours or minutes, are given.

on_disconnected event

This event is fired when a connection is closed.

Syntax

class NFSClientDisconnectedEventParams(object):
  @property
  def status_code() -> int: ...

  @property
  def description() -> str: ...

# In class NFSClient:
@property
def on_disconnected() -> Callable[[NFSClientDisconnectedEventParams], None]: ...
@on_disconnected.setter
def on_disconnected(event_hook: Callable[[NFSClientDisconnectedEventParams], None]) -> None: ...

Remarks

This event is fired when a connection is closed.

If the connection is broken normally, StatusCode is 0 and Description is "OK".

If the connection is broken for any other reason, StatusCode will be non-zero, and the Description parameter will contain a description of this code.

on_end_transfer event

This event is fired when a file finishes uploading or downloading.

Syntax

class NFSClientEndTransferEventParams(object):
  @property
  def direction() -> int: ...

# In class NFSClient:
@property
def on_end_transfer() -> Callable[[NFSClientEndTransferEventParams], None]: ...
@on_end_transfer.setter
def on_end_transfer(event_hook: Callable[[NFSClientEndTransferEventParams], None]) -> None: ...

Remarks

This event is fired when a file is finished uploading or downloading.

This occurs when a file is finished transferring after calling upload, upload_range, download, and download_range.

The Direction parameter shows whether the client (0) or the server (1) is sending the data.

on_error event

Fired when information is available about errors during data delivery.

Syntax

class NFSClientErrorEventParams(object):
  @property
  def error_code() -> int: ...

  @property
  def description() -> str: ...

# In class NFSClient:
@property
def on_error() -> Callable[[NFSClientErrorEventParams], None]: ...
@on_error.setter
def on_error(event_hook: Callable[[NFSClientErrorEventParams], None]) -> None: ...

Remarks

The on_error event is fired in case of exceptional conditions during message processing. Normally the class fails with an error.

The ErrorCode parameter contains an error code, and the Description parameter contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the Error Codes section.

on_log event

This event is fired once for each log message.

Syntax

class NFSClientLogEventParams(object):
  @property
  def log_level() -> int: ...

  @property
  def message() -> str: ...

  @property
  def log_type() -> str: ...

# In class NFSClient:
@property
def on_log() -> Callable[[NFSClientLogEventParams], None]: ...
@on_log.setter
def on_log(event_hook: Callable[[NFSClientLogEventParams], None]) -> None: ...

Remarks

This event fires once for each log message generated by the class. The verbosity is controlled by the LogLevel configuration.

LogLevel indicates the detail level of the message. Possible values are:

Message is the log message.

LogType identifies the type of log entry. Possible values are as follows:

• NFS

on_start_transfer event

This event is fired when a file starts uploading or downloading.

Syntax

class NFSClientStartTransferEventParams(object):
  @property
  def direction() -> int: ...

# In class NFSClient:
@property
def on_start_transfer() -> Callable[[NFSClientStartTransferEventParams], None]: ...
@on_start_transfer.setter
def on_start_transfer(event_hook: Callable[[NFSClientStartTransferEventParams], None]) -> None: ...

Remarks

This event is fired when a file starts uploading or downloading.

This occurs immediately before a file starts transferring after calling upload, upload_range, download, and download_range.

The Direction parameter shows whether the client (0) or the server (1) is sending the data.

on_transfer event

This event is fired during the file download or upload.

Syntax

class NFSClientTransferEventParams(object):
  @property
  def direction() -> int: ...

  @property
  def bytes_transferred() -> int: ...

  @property
  def percent_done() -> int: ...

  @property
  def text() -> bytes: ...

# In class NFSClient:
@property
def on_transfer() -> Callable[[NFSClientTransferEventParams], None]: ...
@on_transfer.setter
def on_transfer(event_hook: Callable[[NFSClientTransferEventParams], None]) -> None: ...

Remarks

One or more on_transfer events are fired during file transfer. The BytesTransferred parameter shows the number of bytes transferred since the beginning of the transfer.

Text contains the portion of the file data being delivered.

The Direction parameter shows whether the client (0) or the server (1) is sending the data.

The PercentDone parameter shows the progress of the transfer in the corresponding direction. If PercentDone can not be calculated the value will be -1.

Note: Events are not re-entrant. Performing time-consuming operations within this event will prevent it from firing again in a timely manner and may affect overall performance.

NFSClient Config Settings

The class accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the config method.

NfsClient Config Settings

Base Config Settings

NFSClient Errors

NFSCLIENT Errors