The File Transfer profile defines the requirements for the protocols and procedures that shall be used by the applications providing the File Transfer usage model. More...

Modules
	FTP Configuration
	This module describes parameters used to configure FTP layer.

Data Structures
struct	bt_ftp_server_get_object_params
	Parameter to FTP_SESSION_SERVER_GET_FOLDER, FTP_SESSION_SERVER_GET_FILE, FTP_SESSION_SERVER_GET_FOLDER_FRAGMENT, FTP_SESSION_SERVER_GET_FILE_FRAGMENT events. More...

struct	bt_ftp_server_put_object_params
	Parameter to FTP_SESSION_SERVER_PUT_FILE, FTP_SESSION_SERVER_PUT_FILE_FRAGMENT events. More...

struct	bt_ftp_server_setpath_params
	Parameter to FTP_SESSION_SERVER_SETPATH event. More...

Macros
#define	bt_ftp_delete_folder bt_ftp_delete_file
	Delete a folder from a remote device. More...

Functions
bt_bool	bt_ftp_init (void)
	Initialize the FTP layer. More...

bt_ftp_session *	bt_ftp_allocate_session (void)
	Allocate FTP session. More...

void	bt_ftp_free_session (bt_ftp_session *psess)
	Release FTP session. More...

bt_bool	bt_ftp_connect (bt_ftp_session session, bt_bdaddr_t remote_addr, bt_uint header_count, bt_obex_header headers, bt_ftp_session_callback_pf callback, void param)
	Connect to a remote device. More...

bt_bool	bt_ftp_listen (bt_ftp_session session, bt_byte server_channel, bt_ftp_session_callback_pf callback, void param)
	Listen for incoming connections. More...

bt_bool	bt_ftp_disconnect (bt_ftp_session session, bt_uint header_count, bt_obex_header headers)
	Disconnect from a remote device. More...

bt_bool	bt_ftp_read_folder (bt_ftp_session session, bt_byte folder_name, bt_uint folder_name_len)
	Read a folder on a remote device. More...

bt_bool	bt_ftp_setpath (bt_ftp_session session, bt_byte folder_name, bt_uint folder_name_len)
	Set current folder on a remote device. More...

bt_bool	bt_ftp_read_file (bt_ftp_session session, bt_byte file_name, bt_uint file_name_len)
	Read a file from a remote device. More...

bt_bool	bt_ftp_send_file (bt_ftp_session session, bt_byte file_name, bt_uint file_name_len)
	Send a file to a remote device. More...

bt_bool	bt_ftp_delete_file (bt_ftp_session session, bt_byte file_name, bt_uint file_name_len)
	Delete a file from a remote device. More...

bt_bool	bt_ftp_abort (bt_ftp_session *session)
	Abort current operation. More...

Events
The following is a list of events FTP layer generates and can report to the upper layer when it completes executing an operation initiated by either local or remote device. FTP_SESSION_ are generated when FTP is used in client mode. FTP_SESSION_SERVER are generated when FTP is used in server mode. You need to call bt_ftp_listen to start the FTP server.
enum	bt_ftp_session_event_enum { , FTP_SESSION_CONNECT_FAILED, FTP_SESSION_OBEX_CONNECTION_STATE_CHANGED, FTP_SESSION_GET_FOLDER_FRAGMENT_RECEIVED, FTP_SESSION_GET_FOLDER_COMPLETED, FTP_SESSION_GET_FILE_FRAGMENT_RECEIVED, FTP_SESSION_GET_FILE_COMPLETED, FTP_SESSION_SETPATH_COMPLETED, FTP_SESSION_GET_FILE_ABORTED, FTP_SESSION_PUT_FILE_ABORTED, FTP_SESSION_GET_FILE_FRAGMENT, FTP_SESSION_PUT_FILE_COMPLETED , FTP_SESSION_DELETE_OBJECT_COMPLETED, FTP_SESSION_SERVER_GET_FOLDER, FTP_SESSION_SERVER_GET_FILE, FTP_SESSION_SERVER_GET_FOLDER_FRAGMENT, FTP_SESSION_SERVER_GET_FILE_FRAGMENT, FTP_SESSION_SERVER_GET_FOLDER_COMPLETED, FTP_SESSION_SERVER_GET_FILE_COMPLETED, FTP_SESSION_SERVER_PUT_FILE, FTP_SESSION_SERVER_PUT_FILE_FRAGMENT, FTP_SESSION_SERVER_PUT_FILE_COMPLETED, FTP_SESSION_SERVER_DELETE_FILE, FTP_SESSION_SERVER_DELETE_FOLDER = FTP_SESSION_SERVER_DELETE_FILE, FTP_SESSION_SERVER_SETPATH, FTP_SESSION_SERVER_GET_FOLDER_ABORTED, FTP_SESSION_SERVER_GET_FILE_ABORTED, FTP_SESSION_SERVER_PUT_FILE_ABORTED }

Detailed Description

The File Transfer profile defines the requirements for the protocols and procedures that shall be used by the applications providing the File Transfer usage model.

To use FTP client the application should do the following:

Call the bt_ftp_init() function.
Allocate an FTP session structure with bt_ftp_allocate_session().
To connect to a remote device call bt_ftp_connect(). One of the parameters to this function is a pointer to a callback function. That callback function will be called by the stack whenever the state of the session changes. The stack will notify when the connection is established by calling the state callback function.
Implement FTP_SESSION_ events.
Call bt_ftp_read_folder, bt_ftp_read_file, bt_ftp_send_file, bt_ftp_setpath, bt_ftp_delete_file, bt_ftp_delete folder to manipulate the file system on the FTP server.

To use FTP server the application should do the following:

Call the bt_ftp_init() function.
Allocate an FTP session structure with bt_ftp_allocate_session().
To wait for a connection from a remote device call bt_ftp_listen(). One of the parameters to this function is a pointer to a callback function. That callback function will be called by the stack whenever the state of the session changes. The stack will notify when the connection is established by calling the state callback function.
Implement FTP_SESSION_SERVER_ events (see event descriptions).

Macro Definition Documentation

#define bt_ftp_delete_folder bt_ftp_delete_file

Delete a folder from a remote device.

This function deletes a folder from a remote FTP server. Once the response from the FTP server is received the stack will send FTP_SESSION_DELETE_OBJECT_COMPLETED event.

Parameters

session	FTP session.
folder_name	The name of the file to write.
folder_name_len	The length of the file's name.

Returns

TRUE if the function succeeds.
FALSE otherwise.

Enumeration Type Documentation

enum bt_ftp_session_event_enum

Enumerator
FTP_SESSION_CONNECT_FAILED	This event is generated when an attempt to establish a connection with a remote device has failed.
FTP_SESSION_OBEX_CONNECTION_STATE_CHANGED	This event is generated when the state of a connection has changed. The new state is passed as `what_param` of the application callback. The connection state is one of the following values: OBEX_SESSION_STATE_DISCONNECTED OBEX_SESSION_STATE_RFCOMM_CONNECTED - RFCOMM connection has been established OBEX_SESSION_STATE_CONNECTED - OBEX connection has been established
FTP_SESSION_GET_FOLDER_FRAGMENT_RECEIVED	This event is generated when a fragment of a folder's content has been received.
FTP_SESSION_GET_FOLDER_COMPLETED	This event is generated when a folder's content has been completely received.
FTP_SESSION_GET_FILE_FRAGMENT_RECEIVED	This event is generated when a fragment of a file's content has been received.
FTP_SESSION_GET_FILE_COMPLETED	This event is generated when a file's content has been completely received.
FTP_SESSION_SETPATH_COMPLETED	This event is generated when current path on the FTP server has been set.
FTP_SESSION_GET_FILE_ABORTED	This event is generated when a file read has been aborted.
FTP_SESSION_PUT_FILE_ABORTED	This event is generated when a file write has been aborted.
FTP_SESSION_GET_FILE_FRAGMENT	This event is generated when FTP layer requests next file's fragment. See bt_ftp_send_file.
FTP_SESSION_PUT_FILE_COMPLETED	This event is generated when a file write has been completed.
FTP_SESSION_DELETE_OBJECT_COMPLETED	This event is generated when a request to delete a file or a folder has been completed.
FTP_SESSION_SERVER_GET_FOLDER	This event is generated when an FTP client has sent a request to get a folder from the local FTP server. The parameter to this event is bt_ftp_server_get_object_params structure. The name of the folder is specified with bt_ftp_server_get_object_params::object_name and bt_ftp_server_get_object_params::object_name_len. The application mail fail this request by setting bt_ftp_server_get_object_params::response_code to one of the OBEX error codes. In response to this event the app has to prepare itself for returning the contents of the folder as an XML document. I.e., the app may save the name of the folder, read the folder's content, convert it to XML and save in a memory buffer. The actual transfer will happen when the stack sends FTP_SESSION_SERVER_GET_FOLDER_FRAGMENT event
FTP_SESSION_SERVER_GET_FILE	This event is generated when an FTP client has sent a request to get a file from the local FTP server. The parameter to this event is bt_ftp_server_get_object_params structure. The name of the file is specified with bt_ftp_server_get_object_params::object_name and bt_ftp_server_get_object_params::object_name_len. The application mail fail this request by setting bt_ftp_server_get_object_params::response_code to one of the OBEX error codes. In response to this event the app has to prepare itself for returning the contents of the file. It should check if the file exists and set bt_ftp_server_get_object_params::response_code to OBEX_RESPONSE_NOT_FOUND if it does not. I.e., the app may save the name of the file, read the file's content in a memory buffer. The actual transfer will happen when the stack sends FTP_SESSION_SERVER_GET_FILE_FRAGMENT event
FTP_SESSION_SERVER_GET_FOLDER_FRAGMENT	This event is generated to get the next fragment of a folder listing (which may have already been prepared in FTP_SESSION_SERVER_GET_FOLDER handler). The parameter to this event is bt_ftp_server_get_object_params structure. bt_ftp_server_get_object_params::buffer and bt_ftp_server_get_object_params::buffer_len specify the buffer where the app should copy the next portion of the folder listing. The app should set bt_ftp_server_get_object_params::buffer_len to the number of copied to the buffer. If there is no more data to be sent bt_ftp_server_get_object_params::buffer_len should be set to 0.
FTP_SESSION_SERVER_GET_FILE_FRAGMENT	This event is generated to get the next fragment of a file. The parameter to this event is bt_ftp_server_get_object_params structure. bt_ftp_server_get_object_params::buffer and bt_ftp_server_get_object_params::buffer_len specify the buffer where the app should copy the next portion of the file. The app should set bt_ftp_server_get_object_params::buffer_len to the number of copied to the buffer. If there is no more data to be sent bt_ftp_server_get_object_params::buffer_len should be set to 0.
FTP_SESSION_SERVER_GET_FOLDER_COMPLETED	This event is generated to when the last fragment of the folder listing has been sent to the client.
FTP_SESSION_SERVER_GET_FILE_COMPLETED	This event is generated to when the last fragment of the file has been sent to the client.
FTP_SESSION_SERVER_PUT_FILE	This event is generated when an FTP client has sent a request to write a file to the local FTP server. The parameter to this event is bt_ftp_server_put_object_params structure. The name of the file is specified with bt_ftp_server_put_object_params::object_name and bt_ftp_server_put_object_params::object_name_len. The application should try to create or open a file or fail the request if it's not possible by setting bt_ftp_server_put_object_params::reponse_code to one of the OBEX error codes.
FTP_SESSION_SERVER_PUT_FILE_FRAGMENT	This event is generated when the next fragment of the file has been received. The application will write the data to the local file opened in FTP_SESSION_SERVER_PUT_FILE handler.
FTP_SESSION_SERVER_PUT_FILE_COMPLETED	This event is generated after the last fragment of the file has been received. The application will close the local file opened in FTP_SESSION_SERVER_PUT_FILE handler.
FTP_SESSION_SERVER_DELETE_FILE	This event is generated when an FTP client has sent a request to delete a file on the local FTP server. The parameter to this event is bt_ftp_server_put_object_params structure. The name of the file is specified with bt_ftp_server_put_object_params::object_name and bt_ftp_server_put_object_params::object_name_len. The application will delete the file or fail the request by setting setting bt_ftp_server_put_object_params::reponse_code to one of the OBEX error codes.
FTP_SESSION_SERVER_DELETE_FOLDER	This event is generated when an FTP client has sent a request to delete a folder on the local FTP server. The parameter to this event is bt_ftp_server_put_object_params structure. The name of the folder is specified with bt_ftp_server_put_object_params::object_name and bt_ftp_server_put_object_params::object_name_len. The application will delete the folder or fail the request by setting setting bt_ftp_server_put_object_params::reponse_code to one of the OBEX error codes.
FTP_SESSION_SERVER_SETPATH	This event is generated when an FTP client has sent a request to set current path on the local FTP server. The parameter to this event is bt_ftp_server_setpath_params structure. The name of the folder is specified with bt_ftp_server_setpath_params::folder_name and bt_ftp_server_setpath_params::folder_name_len. The action that needs to be taken by the application depends on the values of bt_ftp_server_setpath_params::flags, bt_ftp_server_setpath_params::folder_name and bt_ftp_server_setpath_params::folder_name_len fields. If OBEX_SETPATH_BACKUP_LEVEL is set in bt_ftp_server_setpath_params::flags the current path should be change one level up. bt_ftp_server_setpath_params::folder_name and bt_ftp_server_setpath_params::folder_name_len should be ignored. If bt_ftp_server_setpath_params::folder_name_len is 0 or bt_ftp_server_setpath_params::folder_name is an empty string the current folder should be set to root folder. if bt_ftp_server_setpath_params::folder_name_len is not 0 and bt_ftp_server_setpath_params::folder_name is not empty the current path should be change to this folder. If the action cannot be performed for some reason the request should be failed by setting bt_ftp_server_setpath_params::response_code to the appropriate OBEX error code.
FTP_SESSION_SERVER_GET_FOLDER_ABORTED	This event is generated when an FTP client has sent a request to abort the reading of a folder's listing.
FTP_SESSION_SERVER_GET_FILE_ABORTED	This event is generated when an FTP client has sent a request to abort the reading of a file's content.
FTP_SESSION_SERVER_PUT_FILE_ABORTED	This event is generated when an FTP client has sent a request to abort the writing of a file's content.

Function Documentation

bt_bool bt_ftp_abort ( bt_ftp_session * session )

Abort current operation.

This function aborts ongoing operation. File read or file write can be aborted. If the current operation is file read the stack will send FTP_SESSION_GET_FILE_ABORTED event. If the current operation is file write the stack will send FTP_SESSION_PUT_FILE_ABORTED event.

Parameters

session FTP session.

Returns

TRUE if the function succeeds.
FALSE otherwise. The callback function is not called in this case.

bt_ftp_session* bt_ftp_allocate_session ( void )

Allocate FTP session.

This function allocates new FTP session.

Returns

A pointer to the new FTP session structure if the function succeeds.
NULL otherwise.

bt_bool bt_ftp_connect	(	bt_ftp_session *	session,
		bt_bdaddr_t *	remote_addr,
		bt_uint	header_count,
		bt_obex_header *	headers,
		bt_ftp_session_callback_pf	callback,
		void *	param
	)

Connect to a remote device.

This function establishes a FTP connection with a remote device which is running FTP server. Changes in the session state are reported through a callback function.

Parameters

session	FTP session.
remote_addr	Address of the remote device.
header_count	The number of optional OBEX headers sent with the connect request.
headers	Optional OBEX headers sent with the connect request.
callback	The callback function that will be called when the FTP generates an event.
param	A pointer to arbitrary data to be passed to the `callback` function.

Returns

TRUE if the function succeeds.
FALSE otherwise. The callback function is not called in this case.

bt_bool bt_ftp_delete_file	(	bt_ftp_session *	session,
		bt_byte *	file_name,
		bt_uint	file_name_len
	)

Delete a file from a remote device.

This function deletes a file from a remote FTP server. Once the response from the FTP server is received the stack will send FTP_SESSION_DELETE_OBJECT_COMPLETED event.

Parameters

session	FTP session.
folder_name	The name of the file to write.
folder_name_len	The length of the file's name.

Returns

TRUE if the function succeeds.
FALSE otherwise.

bt_bool bt_ftp_disconnect	(	bt_ftp_session *	session,
		bt_uint	header_count,
		bt_obex_header *	headers
	)

Disconnect from a remote device.

This function closes a FTP connection with a remote device. Changes in the session state are reported through a callback function set in bt_ftp_connect or bt_ftp_listen call.

Parameters

session	FTP session.
header_count	The number of optional OBEX headers sent with the disconnect request.
headers	Optional OBEX headers sent with the disconnect request.

Returns

TRUE if the function succeeds.
FALSE otherwise.

void bt_ftp_free_session ( bt_ftp_session * psess )

Release FTP session.

This function deallocated the specified FTP session. This function does not disconnect the session. It just frees the memory used by the bt_ftp_session structure. The session has to be disconnected by a remote device or by calling bt_ftp_disconnect.

Parameters

session The FTP session to be deallocated.

bt_bool bt_ftp_init ( void )

Initialize the FTP layer.

This function initializes the FTP layer of the stack. It must be called prior to any other FTP function can be called.

bt_bool bt_ftp_listen	(	bt_ftp_session *	session,
		bt_byte	server_channel,
		bt_ftp_session_callback_pf	callback,
		void *	param
	)

Listen for incoming connections.

This function enables incoming connections on the specified FTP session. I.e., the FTP session will act as FTP server. Changes in the session state are reported through a callback function.

Parameters

session	FTP session.
server_channel	An RFCOMM server channel on which the FTP session will be listening.
callback	A callback function that is called when session state changes or data (command or response) is received from the remote party.
callback_param	A pointer to arbitrary data that will be passed to the callback function specified by the `callback` parameter.

Returns

TRUE if the function succeeds.
FALSE otherwise. The callback function is not called in this case.

bt_bool bt_ftp_read_file	(	bt_ftp_session *	session,
		bt_byte *	file_name,
		bt_uint	file_name_len
	)

Read a file from a remote device.

This function requests the contents of a file from a remote FTP server. Depending on the size of the file it may take several OBEX packets to transfer the file. After each fragment the stack will send FTP_SESSION_GET_FILE_FRAGMENT_RECEIVED event. After the last fragment has been received the stack will send FTP_SESSION_GET_FILE_COMPLETED event. At minimum, if the file fits in one packet, the application will receive one FTP_SESSION_GET_FILE_FRAGMENT_RECEIVED followed by FTP_SESSION_GET_FILE_COMPLETED.

Parameters

session	FTP session.
folder_name	The name of the file to read.
folder_name_len	The length of the file's name.

Returns

TRUE if the function succeeds.
FALSE otherwise.

bt_bool bt_ftp_read_folder	(	bt_ftp_session *	session,
		bt_byte *	folder_name,
		bt_uint	folder_name_len
	)

Read a folder on a remote device.

This function requests the contents of a folder from a remote FTP server. Depending on the size of the folder it may take several OBEX packets to transfer the folder. After each fragment the stack will send FTP_SESSION_GET_FOLDER_FRAGMENT_RECEIVED event. After the last fragment has been received the stack will send FTP_SESSION_GET_FOLDER_COMPLETED event. At minimum, if the folder fits in one packet, the application will receive one FTP_SESSION_GET_FOLDER_FRAGMENT_RECEIVED followed by FTP_SESSION_GET_FOLDER_COMPLETED.

Parameters

session	FTP session.
folder_name	The name of the folder to read or NULL to read the current folder.
folder_name_len	The length of the folder's name.

Returns

TRUE if the function succeeds.
FALSE otherwise.

bt_bool bt_ftp_send_file	(	bt_ftp_session *	session,
		bt_byte *	file_name,
		bt_uint	file_name_len
	)

Send a file to a remote device.

This function writes data from a local device to a file on a remote FTP server. Depending on the size of the file it may take several OBEX packets to transfer the file's content. To get the data to be sent the stack will send FTP_SESSION_GET_FILE_FRAGMENT events to the application. The event has 2 parameters - pointer to a buffer where the application has to write the next portion of the data to be sent and a pointer to a bt_uint that contains the size of the buffer. The application will update the value of the bt_uint with the number of bytes it has written to the buffer. If there is no more data to be sent the app will set the bt_uint to 0. Once all the data has been transferred the stack will send FTP_SESSION_PUT_FILE_COMPLETED event.

Parameters

session	FTP session.
folder_name	The name of the file to write.
folder_name_len	The length of the file's name.

Returns

TRUE if the function succeeds.
FALSE otherwise.

bt_bool bt_ftp_setpath	(	bt_ftp_session *	session,
		bt_byte *	folder_name,
		bt_uint	folder_name_len
	)

Set current folder on a remote device.

This function sets current folder on a remote FTP server. The path is set relative to the current folder. The application may go down one level by providing the name of the immediate child of the current folder. Or it can go one level up by setting folder_name parameter to NULL. Once the response from the FTP server is received the stack will send FTP_SESSION_SETPATH_COMPLETED event.

Parameters

session	FTP session.
folder_name	The name of the folder to set path to.
folder_name_len	The length of the folder's name.

Returns

TRUE if the function succeeds.
FALSE otherwise.

Modules

Data Structures

Macros

Functions

Events

Detailed Description

Macro Definition Documentation

Enumeration Type Documentation

Function Documentation