Image fetch

Fetches images from the phone. More...

Data Structures
struct	ImagingRequestHeader
	Image request header, watch to phone. More...
struct	ImagingResponseHeader
	Image response chunk header, phone to watch. More...

Macros
#define	IMAGING_RESPONSE_FLAG_TYPE_MASK   (0xf0)
	Mask of the ImagingImageType a response answers, in bits 4-7 of its flags.
#define	IMAGING_RESPONSE_FLAG_TYPE_SHIFT   (4)
	Shift of the image type in a response's flags.

Typedefs
typedef void(*	ImagingReceivedHandler) (uint8_t token, struct GBitmap *bitmap)
	Called on KernelMain when a requested image has been received.
typedef void(*	ImagingWillReceiveHandler) (uint8_t token)
	Called before the buffers for an incoming image are allocated.
typedef void(*	ImagingTransferFailedHandler) (uint8_t token)
	Called when an image transfer is dropped before delivery.

Enumerations
enum	ImagingCmdID { ImagingCmdIDRequest = 0x01 , ImagingCmdIDResponse = 0x02 , ImagingCmdIDInvalid = 0xff }
	Image-fetch endpoint (0x0035) command identifiers. More...
enum	ImagingImageType { ImagingImageTypeAlbumArt = 0x00 , ImagingImageTypeNotification = 0x01 , ImagingImageTypeCount }
	What an image is for; determines the type-specific parameters of the request. More...
enum	ImagingFormat { ImagingFormat1Bit = 0x00 , ImagingFormat8BitColor = 0x01 , ImagingFormat4BitPalette = 0x02 }
	Pixel encoding requested by the watch, and used by the response. More...
enum	ImagingResponseFlags { ImagingResponseFlagFirst = (1 << 0) , ImagingResponseFlagLast = (1 << 1) , ImagingResponseFlagNoImage = (1 << 2) , ImagingResponseFlagUnsupported = (1 << 3) }
	Flags of an image response chunk. More...

Functions
void	imaging_register_handler (ImagingImageType image_type, ImagingReceivedHandler handler)
	Register the handler for an image type.
void	imaging_register_transfer_handlers (ImagingImageType image_type, ImagingWillReceiveHandler will_receive, ImagingTransferFailedHandler transfer_failed)
	Register the transfer lifecycle handlers for an image type.
bool	imaging_is_type_supported (ImagingImageType image_type)
	Check whether the connected phone can serve an image type.
bool	imaging_request_album_art (uint8_t token, ImagingFormat format, uint16_t width, uint16_t height, const char *title, const char *artist)
	Request the album art of a track.
bool	imaging_request_notification_image (uint8_t token, ImagingFormat format, uint16_t width, uint16_t height, const Uuid *item_id)
	Request the image the phone holds for a timeline item.
void	imaging_protocol_msg_callback (CommSession *session, const uint8_t *msg, size_t length)
	Handle a message received on the image-fetch endpoint.
void	imaging_handle_comm_session_event (const PebbleCommSessionEvent *event)
	Handle a comm session event.

Detailed Description

Fetches images from the phone.

Consumers such as album art ask the phone for an image of a given size and pixel format; the phone streams it back in chunks over the image-fetch endpoint (0x0035) and the reassembled bitmap is passed to the handler registered for the image type. Requests are only sent when the phone advertises image-fetch support.

static void prv_received(uint8_t token, struct GBitmap *bitmap) {
  // bitmap is NULL if the phone has none; otherwise the handler owns it
}
 
imaging_register_handler(ImagingImageTypeAlbumArt, prv_received);
imaging_request_album_art(token, ImagingFormat8BitColor, 144, 144, title, artist);

---

Data Structure Documentation

ImagingRequestHeader

struct ImagingRequestHeader

Image request header, watch to phone.

Type-specific parameters follow:

• For ImagingImageTypeAlbumArt, uint8_t title length, title, uint8_t artist length and artist. The phone returns art for that track, so the request cannot race a track change, or no image.
• For ImagingImageTypeNotification, the 16-byte UUID of the timeline item, as the phone keyed its cache.

Data Fields
uint8_t	cmd	ImagingCmdIDRequest.
uint8_t	format	Requested ImagingFormat.
uint16_t	height	Desired height in pixels.
uint8_t	image_type	ImagingImageType.
uint8_t	token	Opaque value echoed in the response to match it to the request.
uint16_t	width	Desired width in pixels.

ImagingResponseHeader

struct ImagingResponseHeader

Image response chunk header, phone to watch.

chunk_len pixel bytes follow. On the first chunk they are preceded by an image header: uint16_t width, uint16_t height, uint8_t ImagingFormat, uint8_t palette count (1-16 for palette formats, else 0) and that many GColor8 palette entries.

Data Fields
uint16_t	chunk_len	Number of pixel bytes in this chunk.
uint8_t	cmd	ImagingCmdIDResponse.
uint8_t	flags	ImagingResponseFlags and the image type.
uint32_t	offset	Byte offset of this chunk's pixels in the pixel stream.
uint8_t	token	Token of the request.

Macro Definition Documentation

IMAGING_RESPONSE_FLAG_TYPE_MASK

#define IMAGING_RESPONSE_FLAG_TYPE_MASK   (0xf0)

Mask of the ImagingImageType a response answers, in bits 4-7 of its flags.

Several consumers can have a request outstanding at once, and the token alone does not tell which one a response is for.

IMAGING_RESPONSE_FLAG_TYPE_SHIFT

#define IMAGING_RESPONSE_FLAG_TYPE_SHIFT   (4)

Shift of the image type in a response's flags.

Typedef Documentation

ImagingReceivedHandler

typedef void(* ImagingReceivedHandler) (uint8_t token, struct GBitmap *bitmap)

Called on KernelMain when a requested image has been received.

Parameters

token	Token of the request.
bitmap	Received image, or NULL if the phone has none (ImagingResponseFlagNoImage). Ownership of a non-NULL bitmap and its pixel and palette buffers passes to the handler.

ImagingTransferFailedHandler

typedef void(* ImagingTransferFailedHandler) (uint8_t token)

Called when an image transfer is dropped before delivery.

Parameters

token

Token of the request.

ImagingWillReceiveHandler

typedef void(* ImagingWillReceiveHandler) (uint8_t token)

Called before the buffers for an incoming image are allocated.

Parameters

token

Token of the request.

Enumeration Type Documentation

ImagingCmdID

enum ImagingCmdID

Image-fetch endpoint (0x0035) command identifiers.

Enumerator
ImagingCmdIDRequest	Image request, watch to phone.
ImagingCmdIDResponse	Image response chunk, phone to watch.
ImagingCmdIDInvalid	Invalid command.

ImagingFormat

enum ImagingFormat

Pixel encoding requested by the watch, and used by the response.

Enumerator
ImagingFormat1Bit	1-bpp black and white.
ImagingFormat8BitColor	8-bpp GColor8.
ImagingFormat4BitPalette	4-bpp palettized GColor8, up to 16 colors.

ImagingImageType

enum ImagingImageType

What an image is for; determines the type-specific parameters of the request.

Enumerator
ImagingImageTypeAlbumArt	Album art of a music track.
ImagingImageTypeNotification	Image attached to a notification.
ImagingImageTypeCount	Number of image types.

ImagingResponseFlags

enum ImagingResponseFlags

Flags of an image response chunk.

Enumerator
ImagingResponseFlagFirst	First chunk; the image header precedes the pixels.
ImagingResponseFlagLast	Last chunk of the transfer.
ImagingResponseFlagNoImage	The phone has no image; no pixels follow.
ImagingResponseFlagUnsupported	The phone cannot serve this image type; no pixels follow. The watch stops requesting the type for the rest of the connection.

Function Documentation

imaging_handle_comm_session_event()

void imaging_handle_comm_session_event

(

const PebbleCommSessionEvent *

event

)

Handle a comm session event.

Called from the shell event loop. When the system session closes, frees a partially received image and forgets the image types the phone reported as unsupported.

Parameters

event

Comm session event.

imaging_is_type_supported()

bool imaging_is_type_supported

(

ImagingImageType

image_type

)

Check whether the connected phone can serve an image type.

Parameters

image_type

Image type.

Returns

true if the phone advertises image-fetch support and has not answered with ImagingResponseFlagUnsupported for this type since it connected.

imaging_protocol_msg_callback()

void imaging_protocol_msg_callback	(	CommSession *	session,
		const uint8_t *	msg,
		size_t	length
	)

Handle a message received on the image-fetch endpoint.

Registered in the protocol endpoints table.

Parameters

session	Session the message was received on.
msg	Message.
length	Length of msg in bytes.

imaging_register_handler()

void imaging_register_handler	(	ImagingImageType	image_type,
		ImagingReceivedHandler	handler
	)

Register the handler for an image type.

One handler per type; replaces any previous one. Images without a handler are freed.

Parameters

image_type	Image type.
handler	Handler, or NULL.

imaging_register_transfer_handlers()

void imaging_register_transfer_handlers	(	ImagingImageType	image_type,
		ImagingWillReceiveHandler	will_receive,
		ImagingTransferFailedHandler	transfer_failed
	)

Register the transfer lifecycle handlers for an image type.

Parameters

image_type	Image type.
will_receive	Called before buffers are allocated, or NULL.
transfer_failed	Called when a transfer is dropped, or NULL.

imaging_request_album_art()

bool imaging_request_album_art	(	uint8_t	token,
		ImagingFormat	format,
		uint16_t	width,
		uint16_t	height,
		const char *	title,
		const char *	artist
	)

Request the album art of a track.

The handler of ImagingImageTypeAlbumArt is called when the transfer completes.

Parameters

token	Opaque value passed back to the handlers.
format	Pixel format.
width	Width in pixels.
height	Height in pixels.
title	Track title, truncated to 255 bytes, or NULL.
artist	Track artist, truncated to 255 bytes, or NULL.

Returns

true if the request was sent, false if the type is unsupported.

imaging_request_notification_image()

bool imaging_request_notification_image	(	uint8_t	token,
		ImagingFormat	format,
		uint16_t	width,
		uint16_t	height,
		const Uuid *	item_id
	)

Request the image the phone holds for a timeline item.

The handler of ImagingImageTypeNotification is called when the transfer completes.

Parameters

token	Opaque value passed back to the handlers.
format	Pixel format.
width	Width in pixels.
height	Height in pixels.
item_id	UUID of the timeline item.

Returns

true if the request was sent, false if item_id is NULL or the type is unsupported.