Transferring Files
Using ASFaspSession
Regular sessions, represented by ASFaspSession, transfer a set of files that is known before starting the session: a connection is established with the remote host, the files are transferred and then the connection is terminated.
To transfer files using ASFaspSession create an ASFaspSessionParameters object using the ASFaspSessionParameters uploadSessionWithParameters: or downloadSessionWithParameters: methods:
ASFaspSessionParameters *parameters;
parameters = [ASFaspSessionParameters downloadSessionWithHost:@"example.com" user:@"transfer_user"];
parameters.password = @"open_sesame";
parameters.sshPort = 22;
parameters.destinationPath = documentsDir;
Create an ASFaspSession object using the ASFaspSessionParameters object created in the previous step and provide a list of path sources:
NSArray *sources = @[@"/path/file1", @"path/file2"];
ASFaspSession *session = [ASFaspSession sessionWithParameters:parameters sources:sources];
Start the session by calling one of the methods start, startAsync or startAsyncWithSessionEnd:
[session start];
Of these start is synchronous and will block the current thread until the session’s transfer completes or fails. The stop method can be used to stop the transfer before it completes:
[session stop];
This method will return immediately while the session will run a little longer until it is fully stopped.
Using ASPersistentFaspSession
Persistent sessions, represented by ASPersistentFaspSession, allow adding files to the session even after the session is started: a connection is established with the remote host and then the session waits. Whenever files are added to the session they are transferred, but the connection to the remote host is maintained until the session is made to stop.
To transfer files using ASFaspPersistentSession one uses an instance of ASFaspSessionParameters as in the previous section to create an ASPersistentFaspSession instance but without providing any sources:
let session = ASPersistentFaspSession.sessionWithParameters(parameters)
It is important that no sources be added until after the session has started. To start the session call one of the methods start, startAsync or startAsyncWithSessionEnd:. Of these start is synchronous and will block the current thread until the session is stopped or fails:
[session start];
Use the method addPathWithSource:destination: to add paths to the session. Files added in this way will be transferred so long as the session is open:
[session addPathWithSource:@"/src/path" destination:@"/dest/path"];
This method should not be called before the session’s onSessionWillStartData: callback has been invoked, otherwise an exception is raised. The session will run until it is stopped by calling stop from a different thread:
[session stop];
Please note that while the start method is synchronous the callbacks may get executed on a thread different than the one from which start was invoked (for both types of transfers).
Transfer Management
Only one FASP transfer may be started at a time. Calling start on a transfer while another transfer is still running will cause an IllegalStateException to be thrown, therefore one should wait until the start method of one transfer terminates before calling start on another. It is safe to start a transfer from the sessionDidEnd:state callback (or the end block) of a previous session.
Callbacks and blocks
The protocol ASFaspSessionDelegate describes the various callbacks that sessions will invoke during their lifetime. Session delegates can be added to any session (regular or persistent):
[session.delegates addObject:delegate]
Once a delegate has been added to a session that delegate will receive the session callbacks. Each callback is passed the associated session as an ASAbstractFaspSession, from which both ASFaspSession and ASPersistentFaspSession inherit.
Here is an implementation of the onSessionProgressDidChange: callback that prints out various session statistics:
- (void)sessionProgressDidChange:(ASAbstractFaspSession *)session {
NSLog(@"EVENT - session progress");
NSLog(@" - %.2f", session.stats.progress);
NSLog(@" - %llu", session.stats.bytesTotal);
NSLog(@" - %llu", session.stats.bytesWritten);
NSLog(@" - %llu", session.stats.bytesRemaining);
NSLog(@" - %.2f", session.stats.averageBitsPerSecond);
NSLog(@" - %.2f", session.stats.averageSecondsRemaining);
}
The callback sessionDidEnd:state: accepts an ASFaspSessionState parameter which indicates the final state of the session (succeeded, failed or stopped). In addition to these callbacks one may use blocks to handle the session end event. For this one must start the session using the method startAsyncWithSessionEnd:.
Samples
Sample projects for Objective-C and Swift are provided in the samples directory. To run the sample projects follow the installation instructions for the SDK for the appropriate platform. Once this is done the projects are ready to run. The code that creates and runs the transfers is in ViewController.m and ViewController.swift.