SendInterface

class jetstream.sendinterface.SendInterface(api_interface, sync_interface, logging_interface)

SendInterface provides methods for controlling aspects of JetStream related to sending files. SendInterface is accessed from the APIInterface.

Tip

Methods whose names end with Async are asynchronous commands. These commands are sent to the server as a request and queued for processing. Asynchronous methods return a RequestId. Use getRequestStatus() and getRequestResult() to monitor the status of a request.

Method Summary

createDestination Adds a new destination to the JetStream server or returns an existing destination with matching parameters.
createManifest Creates a manifest for the provided file mapping.
createSharedToken Creates a shared token for a manifest.
createTransfer Initiates a new transfer from a manifest, to a given destination.
deleteDestination Deletes the specified destination.
deleteManifest Deletes the specified manifest.
deleteObjectUserData Remove a piece of user data associated with a destination, manifest, transfer or shared token.
deleteSharedToken Deletes the specified shared token.
deleteTransfer Deletes a transfer.
failTransfer Causes an active transfer to fail and present the given error message.
getConnection Returns the configuration for a specified connection.
getConnections Returns the current configurations for all known connections.
getDestination Returns the configuration for a specified destination.
getDestinations Returns the current configurations for all known destinations.
getManifest Returns a structure describing the current state of the given manifest.
getManifestFiles Returns the file mappings for a manifest.
getManifests Returns information for all known manifests.
getSharedToken Returns a structure describing a shared token.
getSharedTokens Returns information for all known shared tokens.
getTransfer Returns a structure describing the current state of a transfer.
getTransfers Returns a list of structures describing the state of all transfers.
resumeTransferAsync Resumes a transfer that has been suspended.
schedulePingAsync Schedules a series of pings to be sent to a destination.
setPriorityLanesAsync Set the priority lanes for transfers.
setSendRateMaxAsync Submits a request to adjust the maximum send rate for the specified destination.
setTransferPriorityAsync Adjusts the priority and priority lane of a transfer.
setTransferSendRateMaxAsync Adjusts the maximum send rate of a transfer.
suspendTransferAsync Suspends a transfer.
updateConnectionParamsAsync Update connection parameters.
updateObjectUserData Add or change a piece of user data associated with a destination, manifest, transfer or shared token.
updateTransferDefaults Sets the default values for new transfers.
waitForManifest Waits for the server to finish processing a manifest.
waitForTransfer Waits for a transfer to finish sending all data.

Method Documentation

SendInterface.createDestination(destinationAddress, sendRateMax=None, destinationPort=None, authenticateDestination=None, destinationPublicKey=None, relayAddress=None, relayPort=None, senderPort=None, exclusive=None)

Adds a new destination to the JetStream server or returns an existing destination with matching parameters.

A destination describes to JetStream how to configure its send operation such that its data will be successfully retrieved by a JetStream receiver. Fundamentally, a destination is identified by its host name (or IP) and its receiver port.

Note

Creating a destination does not guarantee there is a listening JetStream server at the other end.

Parameters:
  • destinationAddress (str) – The address (host name or IP) through which to connect to the destination.
  • sendRateMax (int) – The maximum send rate allowed for this server, in kilobits-per-second. If the destination already exists, then this value is ignored.
  • destinationPort (int) – The receiver UDP port for a destination.
  • authenticateDestination (bool) – Only allow connections to a destination with the public key specified by destinationPublicKey.
  • destinationPublicKey (str) – The public key of the destination to use for authentication.
  • relayAddress (str) – The address (host name or IP) for the relay server, if using a relay. Otherwise unspecified.
  • relayPort (int) – The port for the relay server, if using a relay. Otherwise unspecified.
  • senderPort (int) – The UDP port of the JetStream Sender server. Not specified or 0 will chose a new port. -1 will multiplex the receiver port, if possible.
  • exclusive (bool) – Create a new destination, even there is an existing one with matching parameters.
Returns:

Destination Structure

Return type:

dict

Example

>>> sender.createDestination(destinationAddress='receiver01')

Changed in version 1.4.2: Default value for senderPort is now None.

Changed in version 1.4.3: Added tag parameter.

Changed in version 1.6.0: Default value for sendRateMax is now None.

Changed in version 1.7.0: Removed sendRateMin, sendRate, encryptionEnabled and tag parameters.

Changed in version 1.7.1: Added exclusive parameter.

SendInterface.createManifest(fileMappings=None, mappings=None, symlinkOptions=None)

Creates a manifest for the provided file mapping.

The creation of a manifest happens immediately. The createManifest() method returns a structure with manifestId, which identifies the new manifest. This manifestId indicates that the JetStream server has started to collect information from the file system for all of the specified files. However, the manifest is not necessarily yet ready for use to create a transfer. If one or more directory paths are specified for the manifest, or a large list of files, then the server must recursively visit each subdirectory and file, which may take some time. You will need to monitor the progress of the manifest to know when the traversal has completed. Use getManifest() or waitForManifest() to monitor the status of a manifest.

Parameters:
  • fileMappings (dict) – Deprecated. A dictionary mapping source paths to their desired path file name at the destination.
  • mappings (dict) – A dictionary mapping destination paths to source paths.
  • symlinkOptions (int) – A bitflag specifying how and whether to follow and copy symlinks during a transfer. If not specified, the default is to copy the contents of file or directory symlinks.
Returns:

Manifest Structure

Return type:

dict

mappings:

A dictionary that maps the desired destination path to a given source path. For example, suppose you want to send the file “readme.txt”. At your location (as the sender), the file exists at the path “/usr/docs”. At its destination, you want the file to be named “introduction.txt” as part of a package below the path “project”. The file mapping would be as follows:

Each source path may be a file or directory and must exist at the time of the call.

Example:

>>> createManifest( mappings={'/project/introduction.txt': '/usr/docs/readme.txt'} )

When the source files do not exist, or the file sizes are known in advance, a manifest that skips all I/O may be created (i.e. no directory traversal or existence checks are run). To do this, specify a mapping with information about the source data:

  • src: Source file name (it must exist when transfer is started).
  • size: Size of the source file, specified in bytes.
  • flags: Specifies whether the entry is a file or directory. Use one of the FILETYPE_* constants (See constants).
  • access: A string which represents the file permissions. The only recognized access is ‘x’ (executable).

If neither size nor flags is specified, the entry is interpreted to be an empty directory. If flags specifies a directory, size is ignored.

Example:

>>> createManifest( mappings={'/storage/destinationFile.txt': {'src':'/sourceFile.txt', 'size':100}} )
>>> createManifest( mappings={'/project/data/destinationEmptyDir': {'src':'/emptyDir'}} )
symlinkOptions can be one of:

Changed in version 1.4.1: errorMessage key is always included in results, and is empty string if there were no errors.

Changed in version 1.5.1: Deprecated fileMappings since a source path may be specified more than once but a destination path may not.

Changed in version 1.8.2: Added symlinkOptions parameter. Added``flags`` and access to mappings.

SendInterface.createSharedToken(manifestId, password=None, downloadLimit=None, timeLimitSeconds=None, description=None)

Creates a shared token for a manifest.

The returned structure provides a ‘token’ which may be be used by clients to log on and have access to the manifest.

Parameters:
  • manifestId (str, dict) – A manifest ID or a Manifest Structure.
  • downloadLimit – (optional) Number of times a transfer can be initiated using this token.
  • timeLimitSeconds – (optional) Number of seconds from now before this token expires.
  • description – (optional) A description of what this token represents.
Returns:

Shared Token Structure

Return type:

dict

Raises:

CommandError – The manifest was not found.

See also

New in version 1.4.0.

SendInterface.createTransfer(destinationId, manifestId, destinationPath=None, userName=None, password=None, priority=None, transferFlags=None, checkpointFrequencySeconds=None, sendRateMax=None, priorityLane=None, overwriteMode=None)

Initiates a new transfer from a manifest, to a given destination.

The returned structure provides a transferId which may be submitted to getTransfer() in order to track the status of the transfer. Also provided is a processing key that indicates if the transfer is still in progress. The processing key clears to False once the transfer is completed, if it fails, or when it is suspended.

Parameters:
  • destinationId (str, dict) – A destination ID or a Destination Structure.
  • manifestId (str, dict) – A manifest ID or a Manifest Structure.
  • destinationPath – (optional) Specifies a directory that will be created as the parent for all files in the transfer. The manifest paths are respected, and added below this destination path.
  • userName (str) – (optional) User name to authenticate the transfer. The transfer is authenticated by the receiving server.
  • password (str) – (optional) Password to authenticate the transfer. The transfer is authenticated by the receiving server.
  • priority (int) – (optional) Specifies the initial priority for the new transfer. Lower values are considered higher priority; i.e. priority 1 takes precedence over priority 2. Accepted values are between 0 and 4294967295, inclusive. The default is 100. The priority of a transfer may be adjusted at any time using setTransferPriorityAsync().
  • transferFlags (int) – (optional) A flag which controls whether to enable writes and reads on the destination.
  • checkpointFrequencySeconds (int) – (optional) How frequently to take a checkpoint. A checkpoint is a guarantee that files have been written to storage. If the receiver of a transfer is terminated and subsequently resumed, the transfer can safely continue from its last checkpoint. If 0 (zero), checkpoints are disabled. If None, the transfer will use the default from the destination.
  • sendRateMax (float) – (optional) Specifies the maximum transfer rate in kilobits/second. The actual transfer rate may be less depending on the destination settings and network conditions. The maximum send rate may be adjusted at any time using setTransferSendRateMaxAsync().
  • priorityLane (str) – (optional) The priority lane for the new transfer.
  • overwriteMode (int) – (optional) How to handle creating files, if a file with the same name already exists.
Returns:

Transfer Structure

Return type:

dict

Raises:

CommandError – The destination or manifest was not found.

transferFlags can be one of:
overwriteMode can be one of:

Note

The userName and password parameters are required if the destination server is running as root or as a daemon.

Tip

Use getpass.getuser() to auto-fill the userName parameter.

Use getpass.getpass() to prompt for the password parameter interactively.

Changed in version 1.4.3: Added transferSendRate, transferDataSendRate, transferThroughputRate`` keys to return value.

Changed in version 1.6.1: Added sendRateMax and priorityLane parameters.

Changed in version 1.7.0: Added overwriteMode parameters.

SendInterface.deleteDestination(destinationId)

Deletes the specified destination.

This deletes all transfers associated with the destination. If the destination is recreated, any transfers will need to be recreated, as well.

Note

A destination may not be deleted while any transfers are active. You must delete any active transfers first.

Parameters:destinationId (str, dict) – A destination ID or a Destination Structure.
Returns:None
Raises:CommandError – The destination was not found.
SendInterface.deleteManifest(manifestId)

Deletes the specified manifest.

A manifest may be deleted at any time, even if it has been used to initiate a transfer which is currently active.

Parameters:manifestId (str, dict) – A manifest ID or a Manifest Structure.
Returns:None
Raises:CommandError – The manifest was not found.

Changed in version 1.3.0: Deletes items owned by authenticated user only, unless superuser.

SendInterface.deleteObjectUserData(objId, key)

Remove a piece of user data associated with a destination, manifest, transfer or shared token.

Parameters:id (int, dict) – An object ID or a structure (Destination Structure, Manifest Structure, Transfer Structure, Shared Token Structure)
Returns:None
Raises:CommandError – The user data could not be deleted.

New in version 1.4.1.

SendInterface.deleteSharedToken(token)

Deletes the specified shared token.

A shared token may be deleted at any time, even if it is currently being used as part of a transfer or log in session. The active transfer will continue and will not be terminated.

Parameters:token (str, dict) – A Shared Token or Shared Token Structure.
Returns:None
Raises:CommandError – The shared token was not found.

New in version 1.4.0.

SendInterface.deleteTransfer(transferId)

Deletes a transfer.

A transfer may not be deleted while it is active. You must first suspend it using suspendTransferAsync().

Parameters:transferId (int, dict) – A transfer ID or a Transfer Structure.
Returns:None
Raises:CommandError – The transfer was not found.
SendInterface.failTransfer(transferId, errorMessage=None)

Causes an active transfer to fail and present the given error message.

Parameters:
  • transferId (int, dict) – A transfer ID or a Transfer Structure.
  • errorMessage (string, optional) – A message describing why the transfer failed.
Returns:

None

Raises:

CommandError – The transfer was not found.

New in version 1.4.1.

SendInterface.getConnection(connectionId)

Returns the configuration for a specified connection.

A connection describes amalgamate configuration information and performance statistics shared by destinations which connect to the same server.

Parameters:connectionId (int, dict) – A connection ID or a Connection Structure.
Returns:Connection Structure
Return type:dict

New in version 1.7.0.

SendInterface.getConnections(limit=0)

Returns the current configurations for all known connections.

A connection describes amalgamate configuration information and performance statistics shared by destinations which connect to the same server.

Parameters:limit (int) – (optional) The maximum number of results to retrieve. If not specified, all available connections are returned.
Returns:A list of connection structures, each describing a connection.
Return type:list

New in version 1.7.0.

SendInterface.getDestination(destinationId)

Returns the configuration for a specified destination.

Parameters:destinationId (str, dict) – A destination ID or a Destination Structure.
Returns:Destination Structure
Return type:dict
Raises:CommandError – The destination was not found.
SendInterface.getDestinations(limit=0)

Returns the current configurations for all known destinations.

Parameters:limit (int) – (optional) The maximum number of results to retrieve. If not specified, all available transfers are returned.
Returns:A list of destination structures, each describing a destination.
Return type:list

Changed in version 1.3.0: Added limit parameter.

SendInterface.getManifest(manifestId)

Returns a structure describing the current state of the given manifest.

Parameters:manifestId (str, dict) – A manifest ID or a Manifest Structure.
Returns:Manifest Structure
Return type:dict
Raises:CommandError – The manifest was not found.

Tip

The status field in the returned structure may be used to determine whether the server is still processing the manifest. Please refer to Manifest Structure for list of possible values and their meaning.

Changed in version 1.3.0: Returns items owned by authenticated user only, unless superuser.

Changed in version 1.4.1: errorMessage key is always included in results, and is empty string if there were no errors.

SendInterface.getManifestFiles(manifestId)

Returns the file mappings for a manifest.

Parameters:manifestId (str, dict) – A manifest ID or a Manifest Structure.
Returns:Manifest Files Structure
Return type:dict
Raises:CommandError – The manifest was not found.

Changed in version 1.3.0: Added limit parameter. Returns items owned by authenticated user only, unless superuser.

SendInterface.getManifests(before=None, after=None, limit=None)

Returns information for all known manifests.

Parameters:
  • before (str, dict) – (optional) This expects a manifest ID. If specified, filter results to include only manifests before this manifest ID. The specified manifest ID will not be included in the result. Also allowed is the full dict representating a manifest structure, as from createManifest().
  • after (str, dict) – (optional) This expects a manifest ID. If specified, filter results to include only manifests after this manifest ID. The specified manifest ID will not be included in the result. Also allowed is the full dict representating a manifest structure, as from createManifest().
  • limit (int) – (optional) The maximum number of results to retrieve. If not specified, all available manifests are returned.
Returns:

A list of manifest structures, each describing a manifest.

Return type:

list

Changed in version 1.3.0: Added limit, before, and after parameters. Returns items owned by authenticated user only, unless superuser.

Changed in version 1.4.1: errorMessage key is always included in results, and is empty string if there were no errors.

SendInterface.getSharedToken(token)

Returns a structure describing a shared token.

Parameters:token (str, dict) – A Shared Token or Shared Token Structure.
Returns:Shared Token Structure
Return type:dict
Raises:CommandError – The shared token was not found.

See also

New in version 1.4.0.

SendInterface.getSharedTokens(limit=None)

Returns information for all known shared tokens.

Parameters:limit (int) – (optional) The maximum number of results to retrieve. If not specified, all available shared tokens are returned.
Returns:A list of shared token structures, each describing a shared token.
Return type:list

See also

New in version 1.4.0.

SendInterface.getTransfer(transferId)

Returns a structure describing the current state of a transfer.

Parameters:transferId (int, dict) – A transfer ID or a Transfer Structure.
Returns:Transfer Structure
Return type:dict
Raises:CommandError – The transfer was not found.

Tip

The status field in the returned structure may be used to determine the state of the transfer. Please refer to Transfer Structure for list of possible values and their meaning.

See also

Changed in version 1.4.3: Added transferSendRate, transferDataSendRate, transferThroughputRate keys to return value.

SendInterface.getTransfers(destinationId=None, before=None, after=None, limit=None)

Returns a list of structures describing the state of all transfers.

If the optional destinationId parameter is specified, the results are limited to only the transfers for the given destination. Otherwise, all transfers are returned.

Parameters:
  • destinationId (str, dict) – (optional) A destination ID or a Destination Structure.
  • before (str, dict) – (optional) A transfer ID or a Transfer Structure. If specified, filter results to include only transfers before this transferId. The specified transfer ID will not be included in the result.
  • after (str, dict) – (optional) A transfer ID or a Transfer Structure. If specified, filter results to include only transfers after this transferId. The specified transfer ID will not be included in the result.
  • limit (int) – (optional) The maximum number of results to retrieve. If not specified, all available transfers are returned.
Returns:

A list of transfer structures, each describing a transfer.

Return type:

list

Raises:

CommandError – The destination was not found.

Changed in version 1.3.0: Added limit, before, and after parameters.

Changed in version 1.4.3: Added transferSendRate, transferDataSendRate, transferThroughputRate keys to return value.

SendInterface.resumeTransferAsync(transferId)

Resumes a transfer that has been suspended.

Resuming a transfer will restore it to the server’s processing queue, and it will resume sending data to its destination.

Resuming a transfer moves the transfer back in the processing queue. The transfer may not resume sending files immediately, depending on the traffic from other ongoing transfers. Use getTransfer() or waitForTransfer() to monitor the status of the transfer.

Only suspended transfers can be resumed. If a transfer is already complete, or has failed, this request will fail.

Parameters:transferId (int, dict) – A transfer ID or a Transfer Structure.
Returns:Request Structure containing a requestId for this request. Use getRequestStatus() or getRequestResult() to monitor the status of the request.

getRequestResult() will return Transfer Structure.

Return type:dict
Raises:CommandError – The transfer was not found, or could not be resumed.

Example

>>> request = send.resumeTransferAsync(transfer)
{'requestId': 7}
>>> status = send.getRequestStatus(request)
{'status': 'complete', ...}
>>> result = send.getRequestResult(request)
{'transferId': 13}
>>> transfer = send.getTransfer(result)
{'status': 'resuming', ...}
SendInterface.schedulePingAsync(destinationId, pingCount)

Schedules a series of pings to be sent to a destination.

Pings are scheduled and interleaved into the transmission protocol at a regulated frequency. A response is assigned to the Destination as ‘lastReceiverDestinationId’. Use getDestination to monitor a ping response.

Parameters:
  • destinationId (str, dict) – A destination ID or a Destination Structure.
  • pingCount – The number of pings to send.
Returns:

Returns a Request Structure containing a requestId for this request. Use getRequestStatus() or getRequestResult() to monitor the status of the request.

Return type:

dict

Raises:

CommandError – The destination was not found.

SendInterface.setPriorityLanesAsync(destinationId, priorityLanes)

Set the priority lanes for transfers.

Each priority lane represents a priority queue of transfers. Transfers in each lane are transmitted simultaneously using the given proportion of the current send rate.

Parameters:
  • destinationId (str, dict) – A destination ID or a Destination Structure.
  • priorityLanes (dict) – A mapping from lane name to lane rate proportions. See below for rules when specifying custom lanes.
Returns:

Returns a Request Structure containing a requestId for this request. Use getRequestStatus() or getRequestResult() to monitor the status of the request.

Return type:

dict

Raises:

CommandError – The destinationId was not found or the priority lanes are invalid.

priorityLanes mapping has to be specified according to the following rules:
  • All lanes must be updated simulataneously.
  • There must be at least one lane.
  • Lane names cannot be blank.
  • Lane names must be unique.
  • Lane rate proportions must sum to 1.0.
  • At most one lane can have a rate proportion of 0.0, which is the idle lane: data will only be transfered when all other lanes are empty.
  • The number of lanes cannot be changed if there are transfers in-progress.
  • The name of a lane cannot be changed if the lane has a transfer in-progress.
  • Rates may be updated while transfer are in-progress.

By default, the priority lanes are set as follows

Lane Bandwidth allocation
High 70%
Normal 25%
Low 5%
Idle 0%

New in version 1.6.1.

SendInterface.setSendRateMaxAsync(destinationId, sendRateMax)

Submits a request to adjust the maximum send rate for the specified destination.

When the maximum send rate is adjusted, the minimum send rate and actual send rate will also be adjusted, if necessary, so as not to exceed the maximum rate.

Parameters:
  • destinationId (str, dict) – A destination ID or a Destination Structure.
  • sendRateMax (float) – The maximum send rate that will be allowed by the JetStream rate controller, in kilobits/second.
Returns:

Returns a Request Structure containing a requestId for this request. Use getRequestStatus() or getRequestResult() to monitor the status of the request.

Return type:

dict

Example

>>> request = send.setSendRateAsync(destinationId, sendRate=750000)
{'requestId': 1}
>>> result = send.getRequestResult(request)
{'sendRateMax': 750000.0}
SendInterface.setTransferPriorityAsync(transferId, priority=None, priorityLane=None)

Adjusts the priority and priority lane of a transfer.

Priority is specified as an unsigned integer from 0 to 4294967295. Lower values are considered higher priority; i.e. priority 1 takes precedence over priority 2. The default is 100. The priority of a transfer may be adjusted at any time.

Priority lane is the priority queue which will process the transfer.

Parameters:
  • transferId (int, dict) – A transfer ID or a Transfer Structure.
  • priority (int, optional) – The new priority to assign to the transfer. Accepted values are between 0 and 4294967295, inclusive.
  • priorityLane (str, optional) – The new priority lane to assign to the transfer.
Returns:

Returns a Request Structure containing a requestId for this request. Use getRequestStatus() or getRequestResult() to monitor the status of the request.

Return type:

dict

Result:
dict: getRequestResult() yields a dict with the transferId. Use getTransfer() to retrieve the full Transfer Structure.
Raises:
  • CommandError – An invalid priority or priority lane was specified.
  • CommandError – The transfer was not found.

Changed in version 1.6.1: Added priorityLane parameter.

SendInterface.setTransferSendRateMaxAsync(transferId, sendRateMax)

Adjusts the maximum send rate of a transfer.

The actual transfer rate of a transfer may be less depending on the destination settings and network conditions. A rate of -1 turns off rate throttling for this transfer.

Parameters:
  • transferId (int, dict) – A transfer ID or a Transfer Structure.
  • sendRateMax (float) – Specifies the maximum transfer rate in kilobits/second.
Returns:

Returns a Request Structure containing a requestId for this request. Use getRequestStatus() or getRequestResult() to monitor the status of the request.

Return type:

dict

Result:
dict: getRequestResult() yields a dict with the commited sendRateMax value.
Raises:CommandError – The transfer was not found.

New in version 1.6.1.

SendInterface.suspendTransferAsync(transferId)

Suspends a transfer.

Suspending a transfer removes it from the server’s processing queue, and it will stop sending data to its destination. The transfer is kept in its current (incomplete) state until it is resumed, or deleted.

Only active transfers can be suspended. If a transfer is already complete, or has failed, this request will fail.

Parameters:transferId (int, dict) – A transfer ID or a Transfer Structure.
Returns:Request Structure containing a requestId for this request. Use getRequestStatus() or getRequestResult() to monitor the status of the request.

getRequestResult() will return Transfer Structure.

Return type:dict
Raises:CommandError – The transfer was not found, or could not be suspended.

Example

>>> request = send.suspendTransferAsync(transfer)
{'requestId': 7}
>>> status = send.getRequestStatus(request)
{'status': 'complete', ...}
>>> result = send.getRequestResult(request)
{'transferId': 13}
>>> transfer = send.getTransfer(result)
{'status': 'suspended', ...}
SendInterface.updateConnectionParamsAsync(connectionId, sendRateMin=None, sendRateMax=None, sendRate=None, rateControlEnabled=None, rateControlMethod=None)

Update connection parameters.

Parameters:
  • connectionId (str, dict) – A connection ID or a structure Connection Structure
  • sendRateMin (float) – The minimum send rate allowed for this destination, in kilobits-per-second. The rate controller will maintain the send rate at or above this value.
  • sendRateMax (float) – The maximum send rate allowed for this server, in kilobits-per-second. The rate controller will not allow the send rate to exceed this value.
  • sendRate (float) – The desired send rate, in kilobits-per-second. With rate control enabled, this value will change depending on decisions made by the rate controller.
  • rateControlEnabled (bool) – True enables the rate controller, False disables it.
  • rateControlMethod (int) – Sets the current rate control method. This parameter is reserved for internal and debugging purposes.
Returns:

None

Raises:

CommandError – The connection was not found.

New in version 1.7.0.

SendInterface.updateObjectUserData(objId, key, value=None)

Add or change a piece of user data associated with a destination, manifest, transfer or shared token.

Parameters:
Returns:

None

Raises:

CommandError – The user data could not be added or changed.

New in version 1.4.1.

SendInterface.updateTransferDefaults(destinationId, priority=None, transferFlags=None, checkpointFrequencySeconds=None, sendRateMax=None, priorityLane=None, overwriteMode=None)

Sets the default values for new transfers.

Set the default values used when creating new transfer with createTransfer(). Only parameters that not None will be modified. See createTransfer() for more details on the parameters.

Parameters:
  • destinationId (str, dict) – A destination ID or a Destination Structure.
  • priority – (optional) Specifies the initial priority for the new transfer.
  • transferFlags – (optional) A flag which controls whether to enable writes and reads on the destination.
  • checkpointFrequencySeconds – (optional) How frequently to take a checkpoint. If 0 (zero), checkpoints are disabled.
  • sendRateMax – (optional) Maximum transfer rate in kilobits/second.
  • priorityLane – (optional) The priority lane of the transfer.
  • overwriteMode – (optional) How to handle creating files if a file with the same name already exists.
Returns:

None

Raises:

CommandError – The destination was not found.

New in version 1.4.3.

Changed in version 1.6.1: Added sendRateMax and priorityLane parameters.

Changed in version 1.7.0: Added overwriteMode parameters.

SendInterface.waitForManifest(manifestId)

Waits for the server to finish processing a manifest.

After a manifest is created, the server must recursively visit each subdirectory and file in the specified file mapping, which may take some time. This method may be used to wait until server has finished initializing the manifest.

Note

This method will block until the manifest is complete.

Parameters:manifestId (str, dict) – A manifest ID or a Manifest Structure.
Returns:Manifest Structure
Return type:dict
Raises:CommandError – The manifest was not found.

Changed in version 1.3.0: Returns items owned by authenticated user only, unless superuser.

Changed in version 1.4.1: errorMessage key is always included in results, and is empty string if there were no errors.

SendInterface.waitForTransfer(transferId)

Waits for a transfer to finish sending all data.

After a transfer is created, it may take some time to send its files to the destination. waitForTransfer() may be used to wait until a transfer has finished sending all files.

Note

This method will block until the transfer is complete.

Parameters:transferId (int, dict) – A transfer ID or a Transfer Structure.
Returns:Transfer Structure. The status field will indicate that the transfer is complete.
Return type:dict
Raises:CommandError – The transfer was not found.

Changed in version 1.4.3: Added transferSendRate, transferDataSendRate, transferThroughputRate`` keys to return value.