Classes
struct	SmartstrapHandlers
	Handlers which are passed to smartstrap_subscribe. More...

Macros
#define	SMARTSTRAP_TIMEOUT_DEFAULT 250
	The default request timeout in milliseconds (see smartstrap_set_timeout).

#define	SMARTSTRAP_RAW_DATA_SERVICE_ID 0
	The service_id to specify in order to read/write raw data to the smartstrap.

#define	SMARTSTRAP_RAW_DATA_ATTRIBUTE_ID 0
	The attribute_id to specify in order to read/write raw data to the smartstrap.

#define	PBL_IF_SMARTSTRAP_ELSE(if_true, if_false) (if_true)

Typedefs
typedef uint16_t	SmartstrapServiceId
	A type representing a smartstrap ServiceId.

typedef uint16_t	SmartstrapAttributeId
	A type representing a smartstrap AttributeId.

typedef struct SmartstrapAttribute	SmartstrapAttribute

typedef void(*	SmartstrapServiceAvailabilityHandler) (SmartstrapServiceId service_id, bool is_available)

typedef void(*	SmartstrapReadHandler) (SmartstrapAttribute attribute, SmartstrapResult result, const uint8_t data, size_t length)

typedef void(*	SmartstrapWriteHandler) (SmartstrapAttribute *attribute, SmartstrapResult result)

typedef void(*	SmartstrapNotifyHandler) (SmartstrapAttribute *attribute)

Enumerations
enum	SmartstrapResult { SmartstrapResultOk = 0, SmartstrapResultInvalidArgs, SmartstrapResultNotPresent, SmartstrapResultBusy, SmartstrapResultServiceUnavailable, SmartstrapResultAttributeUnsupported, SmartstrapResultTimeOut }
	Error values which may be returned from the smartstrap APIs. More...

Functions
SmartstrapResult	smartstrap_subscribe (SmartstrapHandlers handlers)

void	smartstrap_unsubscribe (void)

void	smartstrap_set_timeout (uint16_t timeout_ms)

SmartstrapAttribute *	smartstrap_attribute_create (SmartstrapServiceId service_id, SmartstrapAttributeId attribute_id, size_t buffer_length)

void	smartstrap_attribute_destroy (SmartstrapAttribute *attribute)

bool	smartstrap_service_is_available (SmartstrapServiceId service_id)

SmartstrapServiceId	smartstrap_attribute_get_service_id (SmartstrapAttribute *attribute)

SmartstrapAttributeId	smartstrap_attribute_get_attribute_id (SmartstrapAttribute *attribute)

SmartstrapResult	smartstrap_attribute_read (SmartstrapAttribute *attribute)

SmartstrapResult	smartstrap_attribute_begin_write (SmartstrapAttribute attribute, uint8_t buffer, size_t buffer_length)

SmartstrapResult	smartstrap_attribute_end_write (SmartstrapAttribute *attribute, size_t write_length, bool request_read)

Detailed Description

Macro Definition Documentation

◆ PBL_IF_SMARTSTRAP_ELSE

#define PBL_IF_SMARTSTRAP_ELSE	(	if_true,
		if_false
	)	(if_true)

Convenience macro to switch between two expressions depending on smartstrap support. On platforms with a smartstrap the first expression will be chosen, the second otherwise.

Typedef Documentation

◆ SmartstrapAttribute

typedef struct SmartstrapAttribute SmartstrapAttribute

A type representing an attribute of a service provided by a smartstrap. This type is used when issuing requests to the smartstrap.

◆ SmartstrapNotifyHandler

typedef void(* SmartstrapNotifyHandler) (SmartstrapAttribute *attribute)

The type of function which can be called when the smartstrap sends a notification to the watch

Parameters

attribute The attribute which the notification came from.

◆ SmartstrapReadHandler

typedef void(* SmartstrapReadHandler) (SmartstrapAttribute *attribute, SmartstrapResult result, const uint8_t *data, size_t length)

The type of function which can be called when a read request is completed.

Note: Any write request made to the same attribute within this function will fail with SmartstrapResultBusy.

Parameters

attribute	The attribute which was read.
result	The result of the read.
data	The data read from the smartstrap or NULL if the read was not successful.
length	The length of the data or 0 if the read was not successful.

◆ SmartstrapServiceAvailabilityHandler

typedef void(* SmartstrapServiceAvailabilityHandler) (SmartstrapServiceId service_id, bool is_available)

The type of function which is called after the smartstrap connection status changes.

Parameters

service_id	The ServiceId for which the availability changed.
is_available	Whether or not this service is now available.

◆ SmartstrapWriteHandler

typedef void(* SmartstrapWriteHandler) (SmartstrapAttribute *attribute, SmartstrapResult result)

The type of function which can be called when a write request is completed.

Parameters

attribute	The attribute which was written.
result	The result of the write.

Enumeration Type Documentation

◆ SmartstrapResult

enum SmartstrapResult

Error values which may be returned from the smartstrap APIs.

Enumerator
SmartstrapResultOk	No error occured.
SmartstrapResultInvalidArgs	Invalid function arguments were supplied.
SmartstrapResultNotPresent	The smartstrap port is not present on this watch.
SmartstrapResultBusy	A request is already pending on the specified attribute.
SmartstrapResultServiceUnavailable	Either a smartstrap is not connected or the connected smartstrap does not support the specified service.
SmartstrapResultAttributeUnsupported	The smartstrap reported that it does not support the requested attribute.
SmartstrapResultTimeOut	A time-out occured during the request.

Function Documentation

◆ smartstrap_attribute_begin_write()

SmartstrapResult smartstrap_attribute_begin_write	(	SmartstrapAttribute *	attribute,
		uint8_t **	buffer,
		size_t *	buffer_length
	)

Begins a write request for the specified attribute and returns a buffer into which the app should write the data before calling smartstrap_attribute_end_write.

Note: The buffer must not be used after smartstrap_attribute_end_write is called.

Parameters

[in]	attribute	The attribute to begin writing for.
[out]	buffer	The buffer to write the data into.
[out]	buffer_length	The length of the buffer in bytes.

Returns: SmartstrapResultOk if a write operation was started and the buffer and buffer_length parameters were set, or an error otherwise.

◆ smartstrap_attribute_create()

SmartstrapAttribute* smartstrap_attribute_create	(	SmartstrapServiceId	service_id,
		SmartstrapAttributeId	attribute_id,
		size_t	buffer_length
	)

Creates and returns a SmartstrapAttribute for the specified service and attribute. This API will allocate an internal buffer of the requested length on the app's heap.

Note: Creating an attribute will result in power being applied to the smartstrap port (if it isn't already) and connection establishment to begin.

Parameters

service_id	The ServiceId to create the attribute for.
attribute_id	The AttributeId to create the attribute for.
buffer_length	The length of the internal buffer which will be used to store the read and write requests for this attribute.

Returns: The newly created SmartstrapAttribute or NULL if an internal error occured or if the specified length is greater than SMARTSTRAP_ATTRIBUTE_LENGTH_MAXIMUM.

◆ smartstrap_attribute_destroy()

void smartstrap_attribute_destroy ( SmartstrapAttribute * attribute )

Destroys a SmartstrapAttribute. No further handlers will be called for this attribute and it may not be used for any future requests.

Parameters

[in] attribute The SmartstrapAttribute which should be destroyed.

Note: If power was being applied to the smartstrap port, no availability_did_change handler is subscribed, and the last attribute is being destroyed, this will cause the smartstrap power to be turned off.

◆ smartstrap_attribute_end_write()

SmartstrapResult smartstrap_attribute_end_write	(	SmartstrapAttribute *	attribute,
		size_t	write_length,
		bool	request_read
	)

This should be called by the app when it is done writing to the buffer provided by smartstrap_begin_write and the data is ready to be sent to the smartstrap.

Parameters

[in]	attribute	The attribute to begin writing for.
	write_length	The length of the data to be written, in bytes.
	request_read	Whether or not a read request on this attribute should be automatically triggered following a successful write request.

Returns: SmartstrapResultOk if a write operation was queued to be sent to the smartstrap. The did_write handler will be called when the request is written to the smartstrap, and if request_read was set to true, the did_read handler will be called when the read is complete.

◆ smartstrap_attribute_get_attribute_id()

SmartstrapAttributeId smartstrap_attribute_get_attribute_id ( SmartstrapAttribute * attribute )

Gets the AttributeId which the attribute was created for (see smartstrap_attribute_create).

Parameters

attribute The SmartstrapAttribute for which to obtain the attribute ID.

Returns: The SmartstrapAttributeId which the attribute was created with.

◆ smartstrap_attribute_get_service_id()

SmartstrapServiceId smartstrap_attribute_get_service_id ( SmartstrapAttribute * attribute )

Returns the ServiceId which the attribute was created for (see smartstrap_attribute_create).

Parameters

attribute The SmartstrapAttribute for which to obtain the service ID.

Returns: The SmartstrapServiceId which the attribute was created with.

◆ smartstrap_attribute_read()

SmartstrapResult smartstrap_attribute_read ( SmartstrapAttribute * attribute )

Performs a read request for the specified attribute. The did_read callback will be called when the response is received from the smartstrap or when an error occurs.

Parameters

attribute The attribute to be perform the read request on.

Returns: SmartstrapResultOk if the read operation was started. The did_read callback will be called once the read request has been completed.

◆ smartstrap_service_is_available()

bool smartstrap_service_is_available ( SmartstrapServiceId service_id )

Checks whether or not the specified service is currently supported by a connected smartstrap.

Parameters

service_id The SmartstrapServiceId of the service to check for availability.

Returns: Whether or not the service is available.

◆ smartstrap_set_timeout()

void smartstrap_set_timeout ( uint16_t timeout_ms )

Changes the value of the timeout which is used for smartstrap requests. This timeout is started after the request is completely sent to the smartstrap and will be canceled only if the entire response is received before it triggers. The new timeout value will take affect only for requests made after this API is called.

Parameters

timeout_ms The duration of the timeout to set, in milliseconds.

Note: The maximum allowed timeout is currently 1000ms. If a larger value is passed, it will be internally lowered to the maximum.

See also: SMARTSTRAP_TIMEOUT_DEFAULT

◆ smartstrap_subscribe()

SmartstrapResult smartstrap_subscribe ( SmartstrapHandlers handlers )

Subscribes handlers to be called after certain smartstrap events occur.

Note: Registering an availability_did_change handler will cause power to be applied to the smartstrap port and connection establishment to begin.

See also: smartstrap_unsubscribe

Returns: SmartstrapResultNotPresent if the watch does not have a smartstrap port or SmartstrapResultOk otherwise.

◆ smartstrap_unsubscribe()

void smartstrap_unsubscribe ( void )

Unsubscribes the handlers. The handlers will no longer be called, but in-flight requests will otherwise be unaffected.

Note: If power was being applied to the smartstrap port and there are no attributes have been created (or they have all been destroyed), this will cause the smartstrap power to be turned off.

Classes

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ PBL_IF_SMARTSTRAP_ELSE

Typedef Documentation

◆ SmartstrapAttribute

◆ SmartstrapNotifyHandler

◆ SmartstrapReadHandler

◆ SmartstrapServiceAvailabilityHandler

◆ SmartstrapWriteHandler

Enumeration Type Documentation

◆ SmartstrapResult

Function Documentation

◆ smartstrap_attribute_begin_write()

◆ smartstrap_attribute_create()

◆ smartstrap_attribute_destroy()

◆ smartstrap_attribute_end_write()

◆ smartstrap_attribute_get_attribute_id()

◆ smartstrap_attribute_get_service_id()

◆ smartstrap_attribute_read()

◆ smartstrap_service_is_available()

◆ smartstrap_set_timeout()

◆ smartstrap_subscribe()

◆ smartstrap_unsubscribe()