Send buffers

Build an outbound message piecemeal in a kernel-heap buffer. More...

Typedefs
typedef struct SendBuffer	SendBuffer
	Opaque buffer holding one outbound message.

Functions
size_t	comm_session_send_buffer_get_max_payload_length (const CommSession *session)
	Get the largest payload a send buffer can hold.
SendBuffer *	comm_session_send_buffer_begin_write (CommSession *session, uint16_t endpoint_id, size_t required_free_length, uint32_t timeout_ms)
	Allocate a kernel-heap buffer for an outbound message.
bool	comm_session_send_buffer_write (SendBuffer *send_buffer, const uint8_t *data, size_t length)
	Append payload data to a send buffer.
void	comm_session_send_buffer_end_write (SendBuffer *send_buffer)
	Finish a message and queue it for sending.

Detailed Description

Build an outbound message piecemeal in a kernel-heap buffer.

SendBuffer *sb = comm_session_send_buffer_begin_write(session, endpoint_id, sizeof(hdr) + len,
                                                      COMM_SESSION_DEFAULT_TIMEOUT);
if (sb) {
  comm_session_send_buffer_write(sb, (const uint8_t *)&hdr, sizeof(hdr));
  comm_session_send_buffer_write(sb, body, len);
  comm_session_send_buffer_end_write(sb);
}

Typedef Documentation

SendBuffer

typedef struct SendBuffer SendBuffer

Opaque buffer holding one outbound message.

Function Documentation

comm_session_send_buffer_begin_write()

SendBuffer * comm_session_send_buffer_begin_write	(	CommSession *	session,
		uint16_t	endpoint_id,
		size_t	required_free_length,
		uint32_t	timeout_ms
	)

Allocate a kernel-heap buffer for an outbound message.

Blocks until enough space is available or the timeout expires. Must be followed by comm_session_send_buffer_end_write(). bt_lock() must not be held. Use comm_session_send_queue_add_job() to avoid the kernel-heap allocation, or comm_session_send_data() to send a message in one call.

Parameters

session	Destination session.
endpoint_id	Pebble Protocol endpoint ID.
required_free_length	Payload space in bytes guaranteed to be available on success.
timeout_ms	Maximum time to wait for the space.

Returns

Send buffer, or NULL on timeout, if the length exceeds the maximum payload, or if session is not valid.

comm_session_send_buffer_end_write()

void comm_session_send_buffer_end_write

(

SendBuffer *

send_buffer

)

Finish a message and queue it for sending.

Ownership of send_buffer passes to the send queue. bt_lock() may be held.

Parameters

send_buffer

Buffer from comm_session_send_buffer_begin_write().

comm_session_send_buffer_get_max_payload_length()

size_t comm_session_send_buffer_get_max_payload_length

(

const CommSession *

session

)

Get the largest payload a send buffer can hold.

Parameters

session

Destination session.

Returns

Maximum payload length in bytes, or 0 if session is not valid.

comm_session_send_buffer_write()

bool comm_session_send_buffer_write	(	SendBuffer *	send_buffer,
		const uint8_t *	data,
		size_t	length
	)

Append payload data to a send buffer.

bt_lock() may be held.

Parameters

send_buffer	Buffer from comm_session_send_buffer_begin_write().
data	Data to append.
length	Length of data in bytes.

Returns

True if appended; false if it does not fit. Writes within the required_free_length passed to comm_session_send_buffer_begin_write() always fit.