dotstack API Reference  1.10.37
Data Structures | Functions
OPP

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

Data Structures

struct  bt_opp_evt_connected_t
 Parameter to OPP_EVT_SESSION_CONNECTED event. More...
 
struct  bt_opp_evt_get_object_fragment_t
 Parameter to OPP_EVT_SESSION_GET_OBJECT_FRAGMENT event. More...
 
struct  bt_opp_evt_push_object_completed_t
 Parameter to OPP_EVT_SESSION_PUSH_OBJECT_COMPLETED event. More...
 
struct  bt_opp_evt_push_object_aborted_t
 Parameter to OPP_EVT_SESSION_PUSH_OBJECT_ABORTED event. More...
 
struct  bt_opp_evt_pull_object_aborted_t
 Parameter to OPP_EVT_SESSION_PULL_OBJECT_ABORTED event. More...
 
union  bt_opp_event_t
 Parameter to an application callback. More...
 

Functions

bt_bool bt_opp_init (void)
 Initialize the OPP layer. More...
 
bt_opp_session_tbt_opp_allocate_session (bt_opp_session_callback_pf callback, void *param)
 Allocate OPP session. More...
 
void bt_opp_free_session (bt_opp_session_t *session)
 Release OPP session. More...
 
bt_bool bt_opp_listen (bt_opp_session_t *session, bt_byte server_channel, bt_opp_session_callback_pf callback, void *param)
 Listen for incoming connections. More...
 
bt_bool bt_opp_disconnect (bt_opp_session_t *session)
 Disconnect from a remote device. More...
 
bt_bool bt_opp_connect (bt_opp_session_t *session, bt_bdaddr_t *remote_addr, bt_byte server_channel)
 Connect to a remote device. More...
 
bt_bool bt_opp_push_object (bt_opp_session_t *session, bt_bdaddr_t *remote_addr, bt_byte server_channel, bt_byte *type, bt_byte *name, bt_uint name_len, const bt_byte *data, bt_uint data_len)
 Send an object to a remote device. More...
 
bt_bool bt_opp_abort (bt_opp_session_t *session)
 Abort object push. More...
 

Events

The following is a list of events OPP layer generates and can report to the upper layer when it completes executing an operation initiated by either local or remote device.

enum  bt_opp_session_event_enum { ,
  OPP_EVT_SESSION_CONNECT_FAILED, OPP_EVT_SESSION_CONNECTED, OPP_EVT_SESSION_DISCONNECTED, OPP_EVT_SESSION_GET_OBJECT_FRAGMENT,
  OPP_EVT_SESSION_PUSH_OBJECT_COMPLETED, OPP_EVT_SESSION_PUSH_OBJECT_ABORTED, OPP_EVT_SESSION_PULL_OBJECT_COMPLETED, OPP_EVT_SESSION_PULL_OBJECT_ABORTED
}
 

Detailed Description

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

To use OPP client the application should do the following:

Enumeration Type Documentation

Enumerator
OPP_EVT_SESSION_CONNECT_FAILED 

This event is generated when an attempt to establish a connection with a remote device has failed.

OPP_EVT_SESSION_CONNECTED 

This event is generated when a connection with a remote device has been established.

OPP_EVT_SESSION_DISCONNECTED 

This event is generated when a connection with the remote device has been terminated.

OPP_EVT_SESSION_GET_OBJECT_FRAGMENT 

This event is generated when OOP layer requests next object's fragment. See bt_opp_push_object description.

OPP_EVT_SESSION_PUSH_OBJECT_COMPLETED 

This event is generated when an object has been completely transferred to the remote device.

OPP_EVT_SESSION_PUSH_OBJECT_ABORTED 

This event is generated when an object push has been aborted.

OPP_EVT_SESSION_PULL_OBJECT_COMPLETED 

This event is generated when an object has been completely transferred to the remote device.

OPP_EVT_SESSION_PULL_OBJECT_ABORTED 

This event is generated when an object pull has been aborted.

Function Documentation

bt_bool bt_opp_abort ( bt_opp_session_t session)

Abort object push.

This function aborts ongoing push operation.

Parameters
sessionOPP session.
Returns
  • TRUE if the function succeeds.
  • FALSE otherwise. The callback function is not called in this case.
bt_opp_session_t* bt_opp_allocate_session ( bt_opp_session_callback_pf  callback,
void *  param 
)

Allocate OPP session.

This function allocates new OPP session.

Parameters
callbackPointer to a callback function used to notify about OPP session events. Cannot be NULL.
paramAn arbitrary pointer that is passed as a parameter to the callback function.
Returns
  • A pointer to the new OPP session structure if the function succeeds.
  • NULL otherwise.
bt_bool bt_opp_connect ( bt_opp_session_t session,
bt_bdaddr_t *  remote_addr,
bt_byte  server_channel 
)

Connect to a remote device.

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

Parameters
sessionOPP session.
remote_addrAddress of the remote device.
server_channelAn RFCOMM server channel of the remote OPP server.
Returns
  • TRUE if the function succeeds.
  • FALSE otherwise. The callback function is not called in this case.
bt_bool bt_opp_disconnect ( bt_opp_session_t session)

Disconnect from a remote device.

This function closes a OPP connection with a remote device. Changes in the session state are reported through a callback function set in bt_opp_allocate_session or bt_opp_listen call.

Parameters
sessionOPP session.
Returns
  • TRUE if the function succeeds.
  • FALSE otherwise.
void bt_opp_free_session ( bt_opp_session_t session)

Release OPP session.

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

Parameters
sessionThe OPP session to be deallocated.
bt_bool bt_opp_init ( void  )

Initialize the OPP layer.

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

bt_bool bt_opp_listen ( bt_opp_session_t session,
bt_byte  server_channel,
bt_opp_session_callback_pf  callback,
void *  param 
)

Listen for incoming connections.

This function enables incoming connections on the specified OPP session. Changes in the session state are reported through a callback function.

Parameters
sessionOPP session.
server_channelAn RFCOMM server channel on which the OPP session will be listening.
callbackA callback function that is called when session state changes or data (command or response) is received from the remote party.
callback_paramAn arbitrary data pointer 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_opp_push_object ( bt_opp_session_t session,
bt_bdaddr_t *  remote_addr,
bt_byte  server_channel,
bt_byte *  type,
bt_byte *  name,
bt_uint  name_len,
const bt_byte *  data,
bt_uint  data_len 
)

Send an object to a remote device.

This function sends an object to a OPP server specified by the remote_addr and server_channel parameters. If there is no connection between the local and remote device it will be created.

Parameters
sessionOPP session.
remote_addrAddress of the remote device.
server_channelAn RFCOMM server channel of the remote OPP server.
typeType of the object being sent. May be NULL.
nameName of the object being sent.
name_lenThe length of the object's name.
dataThe object's content. If the object is not very large and fits entirely into a memory buffer the application can provide a pointer to that buffer. The buffer has to be valid until OPP_EVT_SESSION_PUSH_OBJECT_COMPLETED event is received. I.e., the buffer cannot be allocated on the stack. If the object is large, the application may set data parameter to NULL. In this case the OOP layer will request the application to provide the object's content by sending OPP_EVT_SESSION_GET_OBJECT_FRAGMENT events. When the application receives this event it will set bt_opp_evt_get_object_fragment_t::buffer and bt_opp_evt_get_object_fragment_t::buffer_len to specify the location and the length of the next object's fragment to be sent. After the last fragment has been sent and the application receives OPP_EVT_SESSION_GET_OBJECT_FRAGMENT it will set bt_opp_evt_get_object_fragment_t::buffer to NULL to complete the object push. This will be followed by OPP_EVT_SESSION_PUSH_OBJECT_COMPLETED event.
data_lenThe length of the object's content.
Returns
  • TRUE if the function succeeds.
  • FALSE otherwise. The callback function is not called in this case.