The LBM HyperTopic API provides a mechanism to enable the efficient reception of messages sent over any LBM transport (especially an immediate messaging transport) where the message topic conforms to a simple hierarchical wildcard topic structure.

The hierarchical topic supported by this API has a BNF grammar as follows:

<ht-topic> ::= <ht-prefix> <ht-topic-comps> 
             | <ht-topic-comps>
<ht-topic-comps> ::= <ht-topic-comp> "/" <ht-topic-comps>
                   | <ht-topic-comp> "/>"
                       | <ht-topic-comp>
                   | ">"
<ht-topic-comp> ::= <text>
                  | "*"
                  | ""
<ht-prefix> ::= <text>

The "*" token in the above grammar will match any sequence of characters excluding a "/". The ">" token will match any sequence of characters including a "/" (until the end of the topic string).

The grammar supports a prefix string that can be applied to effectively implement a namespace for each instance of a HyperTopic receiver.

A HyperTopic receiver is initialized using the lbm_hypertopic_rcv_init() API function. This function sets the HyperTopic namespace prefix and an optional event queue to be used for messages received on all topics which are part of the HyperTopic namespace.

The lbm_hypertopic_rcv_add() and lbm_hypertopic_rcv_delete() functions are used to add and remove topic patterns to the HyperTopic namespace. Unlike non-HyperTopic receiver creation and deletion functions, these functions take the same set of arguments which include a pointer to the HyperTopic receiver object, the topic pattern, received message callback function and client data pointer (passed with message to the callback function. The lbm_hypertopic_rcv_delete() API function also accepts an optional designation for a callback function to be called once all message callbacks for the topic being deleted have completed.

The lbm_hypertopic_rcv_destroy() API function should be called to de-initialize and clean-up the HyperTopic receiver after all topics added to the HyperTopic namespace have been deleted.