Persistent Sessions

The life cycle of sessions in the queue normally ends once the set of files added to a session has been fully transferred. In terms of client-server interactions this means: connect to the server, transfer a predetermined set of files, disconnect. Sometimes however it can be useful to establish a connection of a more permanent nature, one that stays open regardless of how many files have been transferred over it, until it is explicitly closed. Persistent sessions support this type of client-server interaction.

Warning

Support for persistent sessions is still in its infancy and several features such as path management; availability of per-file error information, etc. are not yet available. The current implementation may be subject to change.

Persistent sessions are created as normal sessions, however instead of adding files using addPath: (ASFaspSession) the session is marked as persistent by setting its ASFaspSession::isPersistentSession attribute:

Objective-C     Swift

ASAccount *account;
ASFaspSession *session;

account = [ASAccount accountWithHost:@"example.com" user:@"usr" password:@"pw" sshPort:22 udpPort:33001];
session = [ASFaspSession sessionWithAccount:account upload:YES];
[session setIsPersistentSession:YES];

let account = ASAccount(host: "example.com", user: "usr", password: "pw", sshPort: 22, udpPort: 33001)
let session = ASFaspSession(account: account, upload: true)
session.isPersistentSession = true

Such a session can then be enqueued like any other. Note however that unlike regular sessions for which paths are added before they are enqueued, for persistent sessions paths may be added only while the session is running. In particular no paths should be added to a persistent session before it is enqueued.

Throughout the lifetime of a persistent session the life cycle of standard sessions applies and all the same ASTransferQueueDelegate methods are invoked (see Session Life Cycle). Once a persistent session is activated by the queue an attempt is made to establish a connection to the remote server. If successful the ASTransferQueueDelegate method queue:canAcceptPathsForPersistentSessionAtIndexPath: (ASTransferQueueDelegate-p) will be invoked once the session is ready to accept paths. From this moment and until the session either fails or is explicitly terminated the session may have paths added to it using addPathToPersistentSessionFromSource:destination: (ASFaspSession)

Objective-C     Swift

// ... 
// after canAcceptPathsForPersistentSessionAtIndexPath: has been invoked for this session
[session addPathToPersistentSessionFromSource:@"/absolute/path/to/file" destination:@"path/relative/to/docroot/on/server"];

// ... 
// after canAcceptPathsForPersistentSessionAtIndexPath: has been invoked for this session
session.addPathToPersistentSessionFromSource("/absolute/path/to/file", destination: "path/relative/to/docroot/on/server")

There is currently no way to inspect or modify the paths that have been added to a persistent session. Such paths are not stored in the session's ASFaspSession::files attribute. Furthermore, these paths are not persisted - if the session fails (or if the app is abruptly restarted) the persistent session will remain in the queue, however if or when it is restarted it will be "empty". Any files that had not finished transferring will no longer be part of the session and their paths will have to be added anew.

The ASTransferQueueDelegate methods queue:didStartTransferringFileForSessionAtIndexPath:fileName: (ASTransferQueueDelegate-p) and queue:didStopTransferringFileForSessionAtIndexPath:fileName: (ASTransferQueueDelegate-p) can be used to monitor progress on a per-file basis, albeit in a limited way due to the following limitations: didStopTransferringFileForSessionAtIndexPath: will be invoked for files upon success or upon failure but no error information is available at this time to indicate which is the case. Moreover these methods are not guaranteed to trigger for every file. Note also that files may be transferred several at a time (in parallel).

A persistent session may be terminated by calling cancelSessionAtIndex: (ASTransferQueue) and passing the index of the persistent session. This will cause the connection to the server to be closed and the session to be deactivated. A persistent session that has been deactivated can be re-run by calling runSessionAtIndex: (ASTransferQueue) with the appropriate index.