Transports

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

Modules
	Console transport
	Pebble protocol over serial console frames, for development tools.
	GATT transport
	Pebble protocol over GATT (PPoGATT), a client of the phone's PPoGATT service.
	QEMU transport
	Pebble protocol over the emulator's serial link, emulating the phone connection.

Data Structures
struct	pbl_pp_transport
	A transport. More...

Enumerations
enum	pbl_pp_destination : uint8_t { PBL_PP_DESTINATION_SYSTEM , PBL_PP_DESTINATION_APP , PBL_PP_DESTINATION_HYBRID }
	Whose traffic a session carries. More...

Functions
struct pbl_pp_session *	pbl_pp_session_open (const struct pbl_pp_transport *transport, enum pbl_pp_destination destination, const Uuid *app_uuid)
	Open a session.
void	pbl_pp_session_close (struct pbl_pp_session *session)
	Close a session and release its resources, dropping any queued data.
void	pbl_pp_session_set_capabilities (struct pbl_pp_session *session, uint32_t capabilities)
	Set the capabilities of a session.
void	pbl_pp_session_receive (struct pbl_pp_session *session, const uint8_t *data, size_t length)
	Feed received bytes to a session.
void	pbl_pp_session_send_next (struct pbl_pp_session *session)
	Schedule a call to the transport's pbl_pp_transport::send_next.
size_t	pbl_pp_session_send_queue_length (const struct pbl_pp_session *session)
	Get the number of bytes queued for sending.
size_t	pbl_pp_session_send_queue_copy (struct pbl_pp_session *session, size_t offset, size_t length, uint8_t *data_out)
	Copy queued bytes without removing them.
size_t	pbl_pp_session_send_queue_peek (const struct pbl_pp_session *session, const uint8_t **data_out)
	Get the next contiguous queued bytes without copying them.
void	pbl_pp_session_send_queue_consume (struct pbl_pp_session *session, size_t length)
	Remove sent bytes from the queue.

Detailed Description

Interface between sessions and the links that carry them.

A transport opens a session once its link is up, feeds it the received bytes, drains its send queue when asked to, and closes it when the link goes down. Each transport serializes these calls with its own lock, which it may hold while calling into the session; the session never holds its lock while calling the transport.

The callbacks may therefore race with the transport closing the session. They receive the session, not the transport's context: a transport looks the session up among its own under its own lock, and ignores the call if it no longer owns it.

Enumeration Type Documentation

pbl_pp_destination

enum pbl_pp_destination : uint8_t

Whose traffic a session carries.

Enumerator
PBL_PP_DESTINATION_SYSTEM	Only the system, i.e. the Pebble mobile app.
PBL_PP_DESTINATION_APP	Only one phone app, e.g. a third party app using PebbleKit iOS.
PBL_PP_DESTINATION_HYBRID	Both the system and PebbleKit apps, e.g. the Pebble Android app.

Function Documentation

pbl_pp_session_close()

void pbl_pp_session_close

(

struct pbl_pp_session *

session

)

Close a session and release its resources, dropping any queued data.

Parameters

session

Session, open on the calling transport.

pbl_pp_session_open()

struct pbl_pp_session * pbl_pp_session_open	(	const struct pbl_pp_transport *	transport,
		enum pbl_pp_destination	destination,
		const Uuid *	app_uuid
	)

Open a session.

A system or hybrid session closes the existing system session, see pbl_pp_transport::shared.

Parameters

transport	Transport carrying the session.
destination	Whose traffic the session carries.
app_uuid	UUID of the phone app's watch app counterpart for app sessions, or NULL if unknown.

Returns

The session, or NULL if out of memory or the existing system session cannot be closed.

pbl_pp_session_receive()

void pbl_pp_session_receive	(	struct pbl_pp_session *	session,
		const uint8_t *	data,
		size_t	length
	)

Feed received bytes to a session.

Bytes may be split anywhere; complete messages are dispatched to their endpoints.

Parameters

session	Receiving session, open on the calling transport.
data	Received bytes.
length	Length of data in bytes.

pbl_pp_session_send_next()

void pbl_pp_session_send_next

(

struct pbl_pp_session *

session

)

Schedule a call to the transport's pbl_pp_transport::send_next.

No-op if a call is already pending.

Parameters

session

Session.

pbl_pp_session_send_queue_consume()

void pbl_pp_session_send_queue_consume	(	struct pbl_pp_session *	session,
		size_t	length
	)

Remove sent bytes from the queue.

Parameters

session	Session.
length	Number of bytes sent.

pbl_pp_session_send_queue_copy()

size_t pbl_pp_session_send_queue_copy	(	struct pbl_pp_session *	session,
		size_t	offset,
		size_t	length,
		uint8_t *	data_out
	)

Copy queued bytes without removing them.

Parameters

	session	Session.
	offset	Offset into the queued bytes.
	length	Maximum number of bytes to copy.
[out]	data_out	Destination.

Returns

Number of bytes copied.

pbl_pp_session_send_queue_length()

size_t pbl_pp_session_send_queue_length

(

const struct pbl_pp_session *

session

)

Get the number of bytes queued for sending.

Parameters

session

Session.

Returns

Length in bytes.

pbl_pp_session_send_queue_peek()

size_t pbl_pp_session_send_queue_peek	(	const struct pbl_pp_session *	session,
		const uint8_t **	data_out
	)

Get the next contiguous queued bytes without copying them.

The queue is not contiguous: alternate with pbl_pp_session_send_queue_consume() until it returns 0 to read everything.

Parameters

	session	Session.
[out]	data_out	Read pointer, valid until the next consume.

Returns

Number of bytes readable at data_out.

pbl_pp_session_set_capabilities()

void pbl_pp_session_set_capabilities	(	struct pbl_pp_session *	session,
		uint32_t	capabilities
	)

Set the capabilities of a session.

Used by transports that know their peer's capabilities up front. Otherwise the session asks the phone once it opens.

Parameters

session	Session.
capabilities	Capability bits, see pbl_pp_capability.