pebble-events

pebble-events
=============

pebble-events fixes the Pebble SDK's event system, supporting multiple
independent subscriptions to a single event, and providing a context parameter
to those that didn't already have one.

Everyone should use it!

Note: This library depends on Pebble SDK 3.14 or greater for the PBL_API_EXISTS
macro.

Installation
------------

``
pebble package install pebble-events
`

You must be using a new-style project; install the latest pebble tool and SDK
and run pebble convert-project on your app if you aren't.

Usage
-----

Usage mirrors the Pebble SDK, but with events_ prefixing all the function
names. Subscription functions have the same signature as the SDK functions of
the same name, except that they return an EventHandle that can be passed to
the corresponding unsubscribe function.

To support usage where some data needs to be passed to the callback (for
instance, a layer component that needs to subscribe to the tick service might
need to pass a pointer to itself to that callback), you can use the _context
variants. These have a signature similar to the non-context versions, but with
a final void *context argument at the end.

$3

Wrapping the SDK AppFocusService,
with the same behaviour.

`c
EventHandle events_app_focus_service_subscribe_handlers(AppFocusHandlers handlers);
EventHandle events_app_focus_service_subscribe_handlers_context(EventFocusHandlers handlers, void *context);
EventHandle events_app_focus_service_subscribe(AppFocusHandler handler);
EventHandle events_app_focus_service_subscribe_context(EventFocusHandler handler, void *context);
void events_app_focus_service_unsubscribe(EventHandle handle);
`

$3

Wrapping the SDK BatteryStateService,
with the same behaviour.

`c
EventHandle events_battery_state_service_subscribe(BatteryStateHandler handler);
EventHandle events_battery_state_service_subscribe_context(EventBatteryStateHandler handler, void *context);
void events_battery_state_service_unsubscribe(EventHandle handle);
`

$3

Wrapping the SDK ConnectionService,
with the same behaviour. Note that the deprecated BluetoothConnectionService is not implemented.

`c
EventHandle events_connection_service_subscribe(ConnectionHandlers conn_handlers);
EventHandle events_connection_service_subscribe_context(EventConnectionHandlers conn_handlers, void *context);
void events_connection_service_unsubscribe(EventHandle handle);
`

$3

Wrapping the SDK HealthService,
with the same behaviour. Note that no _context variant is provided because the
native version already has a context parameter.

`c
EventHandle events_health_service_events_subscribe(HealthEventHandler handler, void *context);
bool events_health_service_events_unsubscribe(EventHandle handle);
`

$3

Wrapping the SDK TickTimerService,
with similar behaviour. Unlike the TickTimerService, however, we will not
necessarily call your handler immediately after subscription. We also may
spuriously call your handler as a result of internal subscription management.
However, in most cases we will call your handlers only on the requested time
units. We will subscribe to the lowest-resolution time unit that permits this.

`c
EventHandle events_tick_timer_service_subscribe(TimeUnits units, TickHandler handler);
EventHandle events_tick_timer_service_subscribe_context(TimeUnits units, EventTickHandler handler, void *context);
void events_tick_timer_service_unsubscribe(EventHandle handle);
`

$3

The appmessage service is more complex than other services because once we open
appmessage, we cannot change the inbox size. Therefore, to use the appmessage
service, you must call events_app_message_request_inbox_size with your
desired inbox size and events_app_message_request_outbox_size with your
desired outbox size (if you don't send messages in one direction you don't need)
to call it in that direction. The consumer app, and _only_ the app, should call
events_app_message_open once all libraries have been initialised. After this
point, the two request functions will no longer work. If you are building a
library, this may require you to add a library_prepare() method or similar to
be called at app initialisation.

To subscribe to more than one appmessage callback at once, you can use
events_app_message_subscribe_handlers. Otherwise, analogues to the SDK's
standard appmessage functions are also available.

Keep in mind that you will receive all appmessages, even if you did not expect
them. Check for a key that your code sends to ensure it is intended for you.
If you could have multiple instances that should not all process a given
message, include some means of determining which instance should handle it (e.g. if
it's a request/response, a pointer cast to a uint32 could work).

`c
typedef struct EventAppMessageHandlers {
AppMessageOutboxSent sent;
AppMessageOutboxFailed failed;
AppMessageInboxReceived received;
AppMessageInboxDropped dropped;
} EventAppMessageHandlers;
void events_app_message_request_inbox_size(uint32_t size);
void events_app_message_request_outbox_size(uint32_t size);
AppMessageResult events_app_message_open(void);
EventHandle events_app_message_subscribe_handlers(EventAppMessageHandlers handlers, void *context);
void events_app_message_unsubscribe(EventHandle handle);

// For consistency with the SDK.
EventHandle events_app_message_register_outbox_sent(AppMessageOutboxSent sent_callback, void *context);
EventHandle events_app_message_register_outbox_failed(AppMessageOutboxFailed failed_callback, void *context);
EventHandle events_app_message_register_inbox_received(AppMessageInboxReceived received_callback, void *context);
EventHandle events_app_message_register_inbox_dropped(AppMessageInboxDropped dropped_callback, void *context);
`

$3

Wrapping the _Tap_ part of the SDK AccelerometerService,
with the same behaviour.

`c
EventHandle events_accel_tap_service_subscribe(AccelTapHandler handler);
EventHandle events_accel_tap_service_subscribe_context(EventAccelTapHandler handler, void *context);
void events_accel_tap_service_unsubscribe(EventHandle handle);
`

$3

Wrapping the SDK UnobstructedAreaService,
with the same behaviour. Note that no _context variant is provided because the
native version already has a context parameter.

`c
EventHandle events_unobstructed_area_service_subscribe(UnobstructedAreaHandlers handlers, void *context);
void events_unobstructed_area_service_unsubscribe(EventHandle handle);
``