OBEXFileTransferServices

Overview

Implements advanced OBEX operations in addition to simple PUT and GET.

Discussion

All operations are asynchronous and will callback over a respective delegate method if the initial return value is successful. The initial return value usually concerns the state of this object where as the delegate return value reflects the response of the remote device.

Methods

-abort

Abort the current operation

-changeCurrentFolderBackward

Change to the directory above the current level if not at the root

-changeCurrentFolderForwardToPath:

Change the remote path

-changeCurrentFolderRoot

Asynchronously change to the remote root directory

-changeCurrentFolderToRoot

Asynchronously change to the remote root directory

-connectToFTPService

Connect the (unconnected) OBEXSession to a remote device for FTP operations

-connectToObjectPushService

Connect the (unconnected) OBEXSession to a remote device for ObjectPush operations. Most of the FTP functionality of this object will be disabled.

-copyRemoteFile:toLocalPath:

Copy a remote file to a local path

-createFolder:

Create a folder on the remote target

-currentPath

Get the remote current directory path during an FTP session

-delegate

Get the delegate

-disconnect

Disconnect the (connected) OBEXSession from the remote device

-getDefaultVCard:

Get the remote default VCard, if it is supported

-initWithOBEXSession:

Create a new OBEXFileTransferServices object

-isBusy

Get the action state of the module

-isConnected

Get the connected state of this module.

-removeItem:

Remove a remote item.

-retrieveFolderListing

Get a remote directory listing

-sendData:type:name:

Send data to a remote target

-sendFile:

Put a local file to the remote target

-setDelegate:

Manually set the delegate

+withOBEXSession:

Create a new OBEXFileTransferServices object

Abort the current operation

- (OBEXError) abort; 

Return Value

kOBEXSuccess, or kOBEXGeneralError if no command is in progress. ABORT commands can only be sent on our turn, meaning we may have to timeout if the target side never responds to the command in progress. In that case this object will call back with a status of kOBEXTimeoutError and an error. Further results returned through the fileTransferServicesAbortComplete: delegate method if initially successful.

Discussion

Attempts send an abort request to the remote device. Returns the OBEXFileTransferServices object to an idle state though the state of the remote device is not guaranteed.

Change to the directory above the current level if not at the root

- (OBEXError) changeCurrentFolderBackward; 

Return Value

kOBEXSuccess or kOBEXSessionBusyError initially. Further results returned through the fileTransferServicesPathChangeComplete: delegate method if initially successful.

Discussion

Equivalent to 'cd ..' only if remote path is not already at root.

Change the remote path

- (OBEXError) changeCurrentFolderForwardToPath: (NSString*) inDirName; 

Parameters

inDirName

The name of the remote folder to be set as current

Return Value

kOBEXSuccess, kOBEXSessionBusyError, or kOBEXBadArgumentError initially. Further results returned through the fileTransferServicesPathChangeComplete: delegate method if initially successful.

Discussion

Equivalent to 'cd dirName'.

Asynchronously change to the remote root directory

changeCurrentFolderToRoot

- (OBEXError) changeCurrentFolderToRoot; 

Return Value

kOBEXSuccess or kOBEXSessionBusyError initially. Further results returned through the fileTransferServicesPathChangeComplete: delegate method if initially successful.

Discussion

Equivalent to 'cd ~/'

Asynchronously change to the remote root directory

changeCurrentFolderRoot

- (OBEXError) changeCurrentFolderToRoot; 

Discussion

Equivalent to 'cd ~/'

Connect the (unconnected) OBEXSession to a remote device for FTP operations

- (OBEXError) connectToFTPService; 

Return Value

kOBEXSuccess, kOBEXSessionBusyError, or kOBEXSessionAlreadyConnectedError, kOBEXNoResourcesError initially. Further results returned through the fileTransferServicesConnectionComplete: delegate method if initially successful.

Discussion

If the OBEXSession given to OBEXFileTransferServices on creation is not connected it can be manually connected through this method.

Connect the (unconnected) OBEXSession to a remote device for ObjectPush operations. Most of the FTP functionality of this object will be disabled.

- (OBEXError) connectToObjectPushService; 

Return Value

kOBEXSuccess, kOBEXSessionBusyError, or kOBEXSessionAlreadyConnectedError, kOBEXNoResourcesError initially. Further results returned through the fileTransferServicesConnectionComplete: delegate method if initially successful.

Discussion

If the OBEXSession given to OBEXFileTransferServices on creation is not connected it can be manually connected through this method.

Copy a remote file to a local path

- (OBEXError) copyRemoteFile: (NSString*) inRemoteFileName toLocalPath: (NSString*) inLocalPathAndName; 

Parameters

inRemoteFileName

The name of the remote file to get

inLocalPathAndName

The path and name of where the received file will go

Return Value

kOBEXSuccess, kOBEXSessionBusyError, or kOBEXBadArgumentError. initially. Further results returned through the fileTransferServicesGetComplete: and fileTransferServicesGetProgress: delegate methods if initially successful.

Discussion

Equivalent to 'cp remotePath/remoteFileName localPathAndName'.

Create a folder on the remote target

- (OBEXError) createFolder: (NSString*) inDirName; 

Parameters

inDirName

The name of the folder to be created

Return Value

kOBEXSuccess, kOBEXSessionBusyError, or kOBEXBadArgumentError initially. Further results returned through the fileTransferServicesCreateFolderComplete delegate method if initially successful.

Discussion

Equivalent to 'mkdir dirName'.

Get the remote current directory path during an FTP session

- (NSString*) currentPath; 

Return Value

The current path being browsed over FTP

Discussion

This path is changed with each path-specific command called on OBEXFileTransferServices.

Get the delegate

- (id) delegate; 

Return Value

The delegate object

Discussion

Get the delegate

Disconnect the (connected) OBEXSession from the remote device

- (OBEXError) disconnect; 

Return Value

kOBEXSuccess, kOBEXSessionNotConnectedError, or kOBEXSessionBusyError initially. Further results returned through the fileTransferServicesDisconnectionComplete: delegate method if initially successful.

Discussion

The user can manually disconnect the OBEXSession from the remote device if they want to. OBEXFileTransferServices will disconnect the OBEXSession at release only if it was responsible for opening the connection via a connect method.

Get the remote default VCard, if it is supported

- (OBEXError) getDefaultVCard:(NSString*) inLocalPathAndName; 

Parameters

inLocalPathAndName

The path and name of where the received file will go

Return Value

kOBEXSuccess, kOBEXSessionBusyError, or kOBEXBadArgumentError initially. Further results returned through the fileTransferServicesGetComplete: and fileTransferServicesGetProgress: delegate methods if initially successful.

Discussion

Some devices such as cellphones and computers support default VCards

Create a new OBEXFileTransferServices object

- (id) initWithOBEXSession:(IOBluetoothOBEXSession*)inOBEXSession; 

Parameters

inOBEXSession

A valid IOBluetoothOBEXSession

Return Value

A newly created OBEXFileTransferServices object on success, nil on failure

Discussion

This object must be constructed with a valid IOBluetoothOBEXSession. The given IOBluetoothOBEXSession does not need to be connected to the remote server. OBEXFileTransferServices can be manually connected through the provided connection methods.

Get the action state of the module

- (BOOL) isBusy; 

Return Value

Success or failure code.

Discussion

OBEXFileTransferServices will be considered "busy" when an operation in taking place or has not completed. Calling abort: on this module will not automatically reset its busy state. The user will have to wait for the operation to complete or for the current operation to timeout.

Get the connected state of this module.

- (BOOL) isConnected; 

Return Value

Success or failure code.

Discussion

Asks the OBEXSession that was passed to it on creation if it has an open OBEX connection

Remove a remote item.

- (OBEXError) removeItem: (NSString*) inItemName; 

Parameters

inItemName

The name of the remote item to be removed

Return Value

kOBEXSuccess, kOBEXSessionBusyError, or kOBEXBadArgumentError initially. Further results returned through the fileTransferServicesRemoveItemComplete: delegate method if initially successful.

Discussion

NOTE: Not available on Apple computers for security reasons.

Get a remote directory listing

- (OBEXError) retrieveFolderListing; 

Return Value

kOBEXSuccess or kOBEXSessionBusyError initially. Further results returned through the fileTransferServicesRetrieveFolderListingComplete: delegate method if initially successful.

Discussion

Equivalent to 'ls'.

Send data to a remote target

- (OBEXError) sendData:(NSData*)inData type:(NSString*)inType name:(NSString*)inName; 

Parameters

inData

The data to be sent

inType

The type of the data to be sent that will be used in the OBEX type header, usually a mime-type. For example, use "text/x-vCard" when sending vCards. This argument is optional.

inName

The name of the file that the data can be referenced as.

Return Value

kOBEXSuccess, kOBEXSessionBusyError, or kOBEXBadArgumentError initially. Further results returned through the fileTransferServicesSendComplete: and fileTransferServicesSendProgress: delegate methods if initially successful.

Discussion

Use this method when you have data to send but no file to read from.

Put a local file to the remote target

- (OBEXError) sendFile: (NSString*) inLocalPathAndName; 

Parameters

inLocalPathAndName

The name and path of the file to be sent an instance of OBEXFilePut.

Return Value

kOBEXSuccess, kOBEXSessionBusyError, or kOBEXBadArgumentError initially. Further results returned through the fileTransferServicesSendComplete: and fileTransferServicesSendProgress: delegate methods if initially successful.

Discussion

Equivalent to 'mv inLocalFilePath remoteCurrentPath'.

Manually set the delegate

- (void) setDelegate: (id) inDelegate; 

Parameters

inDelegate

An object that implements the methods defined in the OBEXFileTransferServicesDelegate category

Discussion

The only way to receive OBEXFileTransferServices transfer operation updates are through using the provided delegate methods below. The return values from all transfer operations on this object are only initial values reflecting the state of this object, not the transfers as a whole. Note that prior to 10.5, the delegate was erroneously retained by the FTS object. In 10.5 and later it is not retained.

Create a new OBEXFileTransferServices object

+ (OBEXFileTransferServices*) withOBEXSession: (IOBluetoothOBEXSession*) inOBEXSession; 

Parameters

inOBEXSession

A valid IOBluetoothOBEXSession that may or may not be connected

Return Value

A newly created OBEXFileTransferServices object on success, nil on failure

Discussion

This object must be constructed with a valid IOBluetoothOBEXSession. The given IOBluetoothOBEXSession does not need to be connected to the remote server. This module can be manually connected through the connect() method or will automatically connect when any transfer method is called on it.

Did this document help you? Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.