Model Validation

The SDK leverages Apple's Core Data framework for maintaining consistency of its models and persisting them to disk. In general this usage of Core Data is hidden from view and the user need not be concerned with it, but it becomes directly relevant if model validations fail for any session or account.

An ASAccount instance is invalid if:

• any of its attributes are nil
• its ssh port, udp port or encryption cipher are set to a number less than 0

An ASFaspSession instance is invalid if:

• at least one of the attributes uuid, files, createpath, pathmtu, or token are nil

All ASTransferQueue methods that act on sessions and accounts validate the instances they are passed before acting on them. If validation fails these methods log an error and raise an exception (!). If you are populating session or account properties with user input, or other possibly invalid input, you should validate these objects before attempting to use them. You can so by invoking the 'validate' method on these objects, shown here on an account:

Objective-C     Swift

NSError *err = nil;
if (![account validate:&err]) {
    // Handle error 
    // ...
 }

var err: NSError?
if !account.validate(error:&err) {
    // Handle error
    // ...
}

see validate: (ASAccount) and validate: (ASFaspSession) for more information

Core Data Validation Errors

The error returned from validate: is an unmodified Core Data error.These errors always have the domain NSCocoaErrorDomain and contain one of the error codes described in Apple's Core Data Constants Reference under 'Validation Error Codes'.

Validation is Global to a Thread

Validation always occurs for all sessions and accounts of a given thread at the same time.

Whenever you perform an action that requires validating a model (such as enqueuing a session) all sessions or accounts that have been modified on the same thread will be validated at the same time.

Because of this fact it is strongly suggested that you do not leave unvalidated or invalid objects "lying around" - when you modify an account or a session, validate it, and if validation fails, handle the failure then and there, otherwise the invalid object might cause an exception to be raised when an otherwise unrelated action is initiated.

Handling Validation Errors

The best way to handle validation errors will vary from application to application, depending among other things on the source of the invalid input. Ultimately however it is imperative that the invalid object be forced into a valid state. The simplest way to do so is to refresh the object, causing all changes to be discarded and returning the object to its last valid state (see refresh (ASAccount) and refresh (ASFaspSession))

Deleting Accounts and Sessions

Model validation also occurs when sessions or accounts are deleted. Again, validation errors will cause an error to be logged and an exception to be raised.

Sessions should only be deleted if they are inactive and not enqueued. Deleting a session that is active or enqueued will not result in an immediate exception but may cause undesired behavior.

Attempting to delete an account that is referenced by any existent sessions will cause a validation error. In order to avoid such a situation use validateForDelete: (ASAccount) to check if an account can be deleted before attempting to do so.