Interface between sessions and the transports that carry them. More...

Data Structures
struct	TransportImplementation
	Callbacks the session uses to drive its transport. More...

Typedefs
typedef struct Transport	Transport
	Opaque transport context, defined by each transport.

typedef void(*	TransportSendNext) (Transport *transport)
	Send data enqueued in the session's send queue.

typedef void(*	TransportClose) (Transport *transport)
	Close the transport.

typedef void(*	TransportReset) (Transport *transport)
	Reset the transport.

typedef void(*	TransportSetConnectionResponsiveness) (Transport *transport, enum pbl_bt_consumer consumer, enum pbl_bt_response_time_state state, uint16_t max_period_secs, pbl_bt_responsiveness_granted_cb_t granted_handler)
	Request a connection response time through the Bluetooth connection manager.

typedef const Uuid (	TransportGetUUID) (Transport *transport)
	Get the UUID of the app the transport connects to.

typedef CommSessionTransportType(*	TransportGetType) (Transport *transport)
	Get the transport type.

typedef bool(*	TransportSchedule) (CommSession *session)
	Schedule a callback that sends data over the transport.

typedef bool(*	TransportScheduleTask) (Transport *transport)
	Check whether the current task is the one TransportSchedule runs callbacks on.

Enumerations
enum	TransportDestination { TransportDestinationSystem , TransportDestinationApp , TransportDestinationHybrid }
	Whose traffic a transport carries. More...

Functions
CommSession *	comm_session_open (Transport transport, const TransportImplementation implementation, TransportDestination destination)
	Open a session on a transport.

void	comm_session_close (CommSession *session, CommSessionCloseReason reason)
	Close a session and release its resources.

void	comm_session_receive_router_write (CommSession session, const uint8_t data, size_t data_size)
	Feed received bytes into the session's receive router.

size_t	comm_session_send_queue_get_length (const CommSession *session)
	Get the total length of all queued outbound data.

size_t	comm_session_send_queue_copy (CommSession session, uint32_t start_offset, size_t length, uint8_t data_out)
	Copy queued outbound data.

size_t	comm_session_send_queue_get_read_pointer (const CommSession session, const uint8_t *data_out)
	Get a pointer to the next contiguous chunk of queued data.

void	comm_session_send_queue_consume (CommSession *session, size_t length)
	Remove sent data from the queue, freeing completed jobs.

void	comm_session_send_next (CommSession *session)
	Schedule a call to the transport's send_next().

Detailed Description

Interface between sessions and the transports that carry them.

Data Structure Documentation

◆ TransportImplementation

struct TransportImplementation

Callbacks the session uses to drive its transport.

Data Fields
TransportClose	close	Close the transport. NULL if it cannot be closed from the watch (iAP).
TransportGetType	get_type	Get the transport type.
TransportGetUUID	get_uuid	Get the connected app UUID. NULL if the transport is not UUID-aware.
TransportScheduleTask	is_current_task_schedule_task	Check whether the current task runs schedule callbacks.
TransportReset	reset	Reset the transport.
TransportSchedule	schedule	Schedule a send callback. When NULL, pbl_bt_comm_schedule_send_next_job() is used. Requires is_current_task_schedule_task when set.
TransportSendNext	send_next	Send newly enqueued data. Called with bt_lock() held; must cope with an empty send queue (it may flush other data, e.g. acks).
TransportSetConnectionResponsiveness	set_connection_responsiveness	Set the connection response time.

Typedef Documentation

◆ Transport

typedef struct Transport Transport

Opaque transport context, defined by each transport.

◆ TransportClose

typedef void(* TransportClose) (Transport *transport)

Close the transport.

Called when another transport opens a system session; the older one is closed. The transport must call comm_session_close() before returning.

Parameters

transport Transport context.

◆ TransportGetType

typedef CommSessionTransportType(* TransportGetType) (Transport *transport)

Get the transport type.

Parameters

transport Transport context.

Returns: Transport type.

◆ TransportGetUUID

typedef const Uuid *(* TransportGetUUID) (Transport *transport)

Get the UUID of the app the transport connects to.

Parameters

transport Transport context.

Returns: App UUID, or NULL if not known.

◆ TransportReset

typedef void(* TransportReset) (Transport *transport)

Reset the transport.

Parameters

transport Transport context.

◆ TransportSchedule

typedef bool(* TransportSchedule) (CommSession *session)

Schedule a callback that sends data over the transport.

Parameters

session Session with data to send.

Returns: True if the callback was scheduled.

◆ TransportScheduleTask

typedef bool(* TransportScheduleTask) (Transport *transport)

Check whether the current task is the one TransportSchedule runs callbacks on.

Parameters

transport Transport context.

Returns: True if called from that task.

◆ TransportSendNext

typedef void(* TransportSendNext) (Transport *transport)

Send data enqueued in the session's send queue.

Parameters

transport Transport context.

◆ TransportSetConnectionResponsiveness

typedef void(* TransportSetConnectionResponsiveness) (Transport *transport, enum pbl_bt_consumer consumer, enum pbl_bt_response_time_state state, uint16_t max_period_secs, pbl_bt_responsiveness_granted_cb_t granted_handler)

Request a connection response time through the Bluetooth connection manager.

Parameters

transport	Transport context.
consumer	Consumer making the request.
state	Requested response time state.
max_period_secs	Maximum time to stay in `state`.
granted_handler	Called once the state is granted. May be NULL.

Enumeration Type Documentation

◆ TransportDestination

enum TransportDestination

Whose traffic a transport carries.

Enumerator

TransportDestinationSystem

Only the system, e.g.

iAP with the Pebble iOS app.

TransportDestinationApp

Only one Pebble app, e.g.

iAP with a third party iOS app using PebbleKit iOS.

TransportDestinationHybrid

Both system and apps, e.g.

plain SPP with the Pebble Android app.

Function Documentation

◆ comm_session_close()

void comm_session_close	(	CommSession *	session,
		CommSessionCloseReason	reason
	)

Close a session and release its resources.

The caller must hold bt_lock().

Parameters

session	Session to close.
reason	Close reason, for analytics.

◆ comm_session_open()

CommSession * comm_session_open	(	Transport *	transport,
		const TransportImplementation *	implementation,
		TransportDestination	destination
	)

Open a session on a transport.

Opening a system or hybrid session closes an existing system session, unless either is PULSE. The caller must hold bt_lock().

Parameters

transport	Transport context.
implementation	Transport callbacks.
destination	Whose traffic the transport carries.

Returns: The new session, or NULL on failure (out of memory, or an existing system session that cannot be closed).

◆ comm_session_receive_router_write()

void comm_session_receive_router_write	(	CommSession *	session,
		const uint8_t *	data,
		size_t	data_size
	)

Feed received bytes into the session's receive router.

The caller must hold bt_lock().

Parameters

session	Receiving session.
data	Received bytes.
data_size	Length of `data` in bytes.

◆ comm_session_send_next()

void comm_session_send_next ( CommSession * session )

Schedule a call to the transport's send_next().

No-op if a call is already pending. The caller must hold bt_lock().

Parameters

session Session with data to send.

◆ comm_session_send_queue_consume()

void comm_session_send_queue_consume	(	CommSession *	session,
		size_t	length
	)

Remove sent data from the queue, freeing completed jobs.

The caller must hold bt_lock().

Parameters

session	Session whose queue to consume.
length	Number of bytes sent.

◆ comm_session_send_queue_copy()

size_t comm_session_send_queue_copy	(	CommSession *	session,
		uint32_t	start_offset,
		size_t	length,
		uint8_t *	data_out
	)

Copy queued outbound data.

The caller must ensure enough data is queued (see comm_session_send_queue_get_length()) and hold bt_lock(). comm_session_send_queue_get_read_pointer() avoids the copy.

Parameters

	session	Session to read from.
	start_offset	Offset into the queued data.
	length	Number of bytes to copy.
[out]	data_out	Destination buffer.

Returns: Number of bytes copied.

◆ comm_session_send_queue_get_length()

size_t comm_session_send_queue_get_length ( const CommSession * session )

Get the total length of all queued outbound data.

The caller must hold bt_lock().

Parameters

session Session to query.

Returns: Length in bytes.

◆ comm_session_send_queue_get_read_pointer()

size_t comm_session_send_queue_get_read_pointer	(	const CommSession *	session,
		const uint8_t **	data_out
	)

Get a pointer to the next contiguous chunk of queued data.

The queue is not contiguous: call this and comm_session_send_queue_consume() repeatedly until it returns 0 to access all data.

Parameters

	session	Session to read from.
[out]	data_out	Read pointer.

Returns: Number of bytes readable at data_out.

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Data Structure Documentation

◆ TransportImplementation

Typedef Documentation

◆ Transport

◆ TransportClose

◆ TransportGetType

◆ TransportGetUUID

◆ TransportReset

◆ TransportSchedule

◆ TransportScheduleTask

◆ TransportSendNext

◆ TransportSetConnectionResponsiveness

Enumeration Type Documentation

◆ TransportDestination

Function Documentation

◆ comm_session_close()

◆ comm_session_open()

◆ comm_session_receive_router_write()

◆ comm_session_send_next()

◆ comm_session_send_queue_consume()

◆ comm_session_send_queue_copy()

◆ comm_session_send_queue_get_length()

◆ comm_session_send_queue_get_read_pointer()