Dispatch Logo

Purpose

This document is intended to list all of the available functions of Dispatch. Move over to the Dispatch How-To for a comprehensive guide for using Dispatch.

Source code may be found on github.

Basic Functions

This table contains the basic functions which make up the Dispatch library. Most application will use all of these functions in one form or another.

Channel Assignment and Initialization

These functions should only be called at the beginning of program execution.

/* Assigns the function which is used to determine how many bytes are currently 
    readable from the UART RX buffer. */
void DIS_assignChannelReadable(uint16_t (*functPtr)());

/* Assigns the function which is used to determine how many bytes may be written to
    the UART TX buffer. */
void DIS_assignChannelWriteable(uint16_t (*functPtr)());

/* Assigns the function which is used to read from the UART RX buffer. */
void DIS_assignChannelRead(void (*functPtr)(uint8_t* data, uint16_t length));

/* Assigns the function which is used to write to the UART TX buffer. */
void DIS_assignChannelWrite(void (*functPtr)(uint8_t* data, uint16_t length));

/* Initializes Dispatch.  Must be called after the `DIS_assignChannel` functions. */
void DIS_init(void);

Normal Use

Subscribing/Unsubscribing

Subscribing to a topic will likely only occur once during initialization, but it is possible to dynamically subscribe and unsubscribe to topics. The DIS_getElements function is utilized to retrieve data within the subscriber.

/* Subscribes to a topic.  Normally called one time at initialization, but
    may be called at any time during program execution */
void DIS_subscribe(const char* topic, void (*functPtr)());

/* Removes a subscriber from the subscription list.  If the subscriber is not active, then
    there is no action. */
void DIS_unsubscribe(void (*functPtr)());

/* Retrieve data received on the RX. */
uint16_t DIS_getElements(uint16_t element, void* destArray);

Publishing Data

/* Publishes data to a topic.  This is the most generic publish function and has the most
    flexibility. */
void DIS_publish(const char* topic, ...);

Processing Dispatch

/* Processes incoming messages and calls the appropriate subscribers.  Must be called
    periodically.  If this is called infrequently, then any subscriber functions are also called
    infrequently and may be missed. */
void DIS_process(void);

Reduced Memory Publishing

These functions are intended to replace the DIS_publish() function above with a specific variant in order to reduce the program memory footprint of Dispatch in some applications. It is not necessary to utilize any of these functions. All of these could be replaced by an appropriate call to DIS_publish().

These functions are available in releases of Dispatch that are greater than v1.0.

/* Publishes a string to a topic without having to use `stdarg.h`.  If the user only needs to send a
    string using Dispatch, then this will be smaller and faster than `DIS_publish()` */
void DIS_publish_str(const char* topic, char* str);

/* Publishes a single unsigned 8-bit array to the topic without using `stdarg.h`.  If this user only
    needs to send an 8-bit array using Dispatch, then this will be smaller and faster than `DIS_publish()`. */
void DIS_publish_u8(const char* topic, uint8_t* data);

/* Publishes a single signed 8-bit array to the topic without using `stdarg.h`.  If this user only
    needs to send an 8-bit array using Dispatch, then this will be smaller and faster than `DIS_publish()`. */
void DIS_publish_s8(const char* topic, int8_t* data);

/* Publishes two unsigned 8-bit array to the topic without using `stdarg.h`.  If this user only
    needs to send an 8-bit array using Dispatch, then this will be smaller and faster than `DIS_publish()`. */
void DIS_publish_2u8(const char* topic, uint8_t* data0, uint8_t* data1);

/* Publishes two signed 8-bit array to the topic without using `stdarg.h`.  If this user only
    needs to send an 8-bit array using Dispatch, then this will be smaller and faster than `DIS_publish()`. */
void DIS_publish_2s8(const char* topic, int8_t* data0, int8_t* data1);

/* Publishes a single unsigned 16-bit array to the topic without using `stdarg.h`.  If this user only
    needs to send an 8-bit array using Dispatch, then this will be smaller and faster than `DIS_publish()`. */
void DIS_publish_u16(const char* topic, uint16_t* data);

/* Publishes a single signed 16-bit array to the topic without using `stdarg.h`.  If this user only
    needs to send an 8-bit array using Dispatch, then this will be smaller and faster than `DIS_publish()`. */
void DIS_publish_s16(const char* topic, int16_t* data);

/* Publishes a single unsigned 32-bit array to the topic without using `stdarg.h`.  If this user only
    needs to send an 8-bit array using Dispatch, then this will be smaller and faster than `DIS_publish()`. */
void DIS_publish_u32(const char* topic, uint32_t* data);

/* Publishes a single signed 32-bit array to the topic without using `stdarg.h`.  If this user only
    needs to send an 8-bit array using Dispatch, then this will be smaller and faster than `DIS_publish()`. */
void DIS_publish_s32(const char* topic, int32_t* data);


© by Jason R. Jones 2016
My thanks to the Pelican and Python Communities.