Endpoints

Handlers of inbound messages, one per endpoint ID. More...

Data Structures
struct	pbl_pp_receiver_api
	Buffers inbound payloads and hands complete messages over. More...
struct	pbl_pp_endpoint
	An endpoint. More...

Macros
#define	PBL_PP_ENDPOINT_DEFINE(_id, _access, _handler)    PBL_PP__ENDPOINT_DEFINE(_id, _access, _handler, NULL, PBL_PP_HANDLER_BG)
	Define an endpoint whose handler runs on KernelBG.
#define	PBL_PP_ENDPOINT_DEFINE_MAIN(_id, _access, _handler)    PBL_PP__ENDPOINT_DEFINE(_id, _access, _handler, NULL, PBL_PP_HANDLER_MAIN)
	Define an endpoint whose handler runs on KernelMain.
#define	PBL_PP_ENDPOINT_DEFINE_RECEIVER(_id, _access, _receiver)    PBL_PP__ENDPOINT_DEFINE(_id, _access, NULL, &(_receiver), PBL_PP_HANDLER_BG)
	Define an endpoint with its own receiver.

Typedefs
typedef void(*	pbl_pp_endpoint_handler_t) (struct pbl_pp_session *session, const uint8_t *data, size_t length)
	Endpoint handler.

Enumerations
enum	pbl_pp_access : uint8_t { PBL_PP_ACCESS_NONE = 0 , PBL_PP_ACCESS_PUBLIC = 1U << 0 , PBL_PP_ACCESS_PRIVATE = 1U << 1 , PBL_PP_ACCESS_ANY = PBL_PP_ACCESS_PUBLIC | PBL_PP_ACCESS_PRIVATE }
	Who may send messages to an endpoint. More...
enum	pbl_pp_handler_task : uint8_t { PBL_PP_HANDLER_BG , PBL_PP_HANDLER_MAIN }
	Task the default receiver runs an endpoint handler on. More...

Variables
const struct pbl_pp_receiver_api	pbl_pp_kernel_receiver
	The default receiver.

Detailed Description

Handlers of inbound messages, one per endpoint ID.

An endpoint is defined next to the code that handles it and collected at link time:

static void prv_ping_handler(struct pbl_pp_session *session, const uint8_t *data,
                             size_t length) {
  ...
}
 
PBL_PP_ENDPOINT_DEFINE(PBL_PP_ENDPOINT_PING, PBL_PP_ACCESS_ANY, prv_ping_handler);

The handler runs on KernelBG once the whole message has arrived, with a copy of the payload on the kernel heap. PBL_PP_ENDPOINT_DEFINE_MAIN() runs it on KernelMain instead, for handlers whose events must stay ordered with the session events. Endpoints that need their own buffering provide a pbl_pp_receiver_api with PBL_PP_ENDPOINT_DEFINE_RECEIVER().

---

Data Structure Documentation

pbl_pp_endpoint

struct pbl_pp_endpoint

An endpoint.

Defined with PBL_PP_ENDPOINT_DEFINE() and its variants.

Data Fields
enum pbl_pp_access	access	Senders allowed to use the endpoint.
pbl_pp_endpoint_handler_t	handler	Handler, used by the default receiver.
uint16_t	id	Endpoint ID.
const struct pbl_pp_receiver_api *	receiver	Receiver, NULL for the default one.
enum pbl_pp_handler_task	task	Task the default receiver runs handler on.

Macro Definition Documentation

PBL_PP_ENDPOINT_DEFINE

#define PBL_PP_ENDPOINT_DEFINE	(		_id,
			_access,
			_handler
	)		PBL_PP__ENDPOINT_DEFINE(_id, _access, _handler, NULL, PBL_PP_HANDLER_BG)

Define an endpoint whose handler runs on KernelBG.

Parameters

_id	Endpoint ID, one of the PBL_PP_ENDPOINT_ macros.
_access	Senders allowed to use the endpoint, a pbl_pp_access.
_handler	Handler, a pbl_pp_endpoint_handler_t.

PBL_PP_ENDPOINT_DEFINE_MAIN

#define PBL_PP_ENDPOINT_DEFINE_MAIN	(		_id,
			_access,
			_handler
	)		PBL_PP__ENDPOINT_DEFINE(_id, _access, _handler, NULL, PBL_PP_HANDLER_MAIN)

Define an endpoint whose handler runs on KernelMain.

Parameters

_id	Endpoint ID, one of the PBL_PP_ENDPOINT_ macros.
_access	Senders allowed to use the endpoint, a pbl_pp_access.
_handler	Handler, a pbl_pp_endpoint_handler_t.

PBL_PP_ENDPOINT_DEFINE_RECEIVER

#define PBL_PP_ENDPOINT_DEFINE_RECEIVER	(		_id,
			_access,
			_receiver
	)		PBL_PP__ENDPOINT_DEFINE(_id, _access, NULL, &(_receiver), PBL_PP_HANDLER_BG)

Define an endpoint with its own receiver.

Parameters

_id	Endpoint ID, one of the PBL_PP_ENDPOINT_ macros.
_access	Senders allowed to use the endpoint, a pbl_pp_access.
_receiver	Receiver, a pbl_pp_receiver_api.

Typedef Documentation

pbl_pp_endpoint_handler_t

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

Endpoint handler.

Parameters

session	Session the message arrived on.
data	Message payload.
length	Length of data in bytes.

Enumeration Type Documentation

pbl_pp_access

enum pbl_pp_access : uint8_t

Who may send messages to an endpoint.

Enumerator
PBL_PP_ACCESS_NONE	No one.
PBL_PP_ACCESS_PUBLIC	Third party phone apps.
PBL_PP_ACCESS_PRIVATE	The Pebble mobile app.
PBL_PP_ACCESS_ANY	Anyone.

pbl_pp_handler_task

enum pbl_pp_handler_task : uint8_t

Task the default receiver runs an endpoint handler on.

Enumerator
PBL_PP_HANDLER_BG	KernelBG.
PBL_PP_HANDLER_MAIN	KernelMain.

Variable Documentation

pbl_pp_kernel_receiver

const struct pbl_pp_receiver_api pbl_pp_kernel_receiver

extern

The default receiver.

Copies the payload to the kernel heap and runs the endpoint's handler on the endpoint's task. Receivers that hand some messages over to a handler can delegate to it.