UM C API 6.17.1

- Main Page
- Related Pages
- Modules
- Data Structures
- Files

- File List
- Globals

Data Structures | Macros | Typedefs | Functions
lbmht.h File Reference

WARNING: the HyperTopic feature is deprecated and will be removed from a future release. More...

`#include "lbm/lbm.h"`

Go to the source code of this file.

## Data Structures
struct | lbm_delete_cb_info_t_stct
| Structure passed to the lbm_hypertopic_rcv_delete() function so that a deletion callback may be called. More...

## Macros
#define | LBM_HT_BASE_MATCH_LEVEL 0
#define | LBM_HT_TOKEN_GLOBNAME 0
#define | LBM_HT_TOKEN_GLOBPATH 1
#define | LBM_HT_TOKEN_NAME 2
#define | LBM_HT_INIT_BRANCH_SZ 16
#define | LBM_HT_CBVEC_SZ 16
#define | LBM_HT_CBVEC_FLAG_ACTIVE 1
#define | LBM_HT_CBVEC_FLAG_DELETED 2

## Typedefs
typedef struct lbm_hypertopic_rcv_stct | lbm_hypertopic_rcv_t
| HyperTopic receiver object (opaque)
typedef int(* | lbm_hypertopic_rcv_cb_proc) (lbm_hypertopic_rcv_t *hrcv, lbm_msg_t *msg, void *clientd)
| Application callback for messages delivered to HyperTopic receivers. More...
typedef void(* | lbm_delete_cb_proc) (int dispatch_thrd, void *clientd)
| Application callback for lbm_hypertopic_rcv_delete(). More...
typedef struct lbm_delete_cb_info_t_stct | lbm_delete_cb_info_t
| Structure passed to the lbm_hypertopic_rcv_delete() function so that a deletion callback may be called.

## Functions
LBMExpDLL int | lbm_hypertopic_rcv_init (lbm_hypertopic_rcv_t **hrcvp, lbm_context_t *ctx, const char *prefix, lbm_event_queue_t *evq)
| Initialize a HyperTopic receiver. More...
LBMExpDLL int | lbm_hypertopic_rcv_add (lbm_hypertopic_rcv_t *hrcv, const char *pattern, lbm_hypertopic_rcv_cb_proc proc, void *clientd)
| Add a topic pattern to the set of topics being received by a HyperTopic receiver. More...
LBMExpDLL int | lbm_hypertopic_rcv_delete (lbm_hypertopic_rcv_t *hrcv, const char *pattern, lbm_hypertopic_rcv_cb_proc proc, void *clientd, lbm_delete_cb_info_t *cbinfo)
| Delete a previously added topic from a HyperTopic receiver topic set. More...
LBMExpDLL int | lbm_hypertopic_rcv_destroy (lbm_hypertopic_rcv_t *hrcv)
| Clean-up HyperTopic receiver previously created by lbm_hypertopic_rcv_init() More...

## Detailed Description

WARNING: the HyperTopic feature is deprecated and will be removed from a future release.

Informatica recommends using normal wildcard receivers with "PCRE" regular expression pattern matching.

All of the documentation and software included in this and any other Informatica Inc. Ultra Messaging Releases Copyright (C) Informatica Inc. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted only as covered by the terms of a valid software license agreement with Informatica Inc.

(C) Copyright 2006,2025 Informatica Inc. All Rights Reserved.

THE SOFTWARE IS PROVIDED "AS IS" AND INFORMATICA DISCLAIMS ALL WARRANTIES EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION, ANY IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. INFORMATICA DOES NOT WARRANT THAT USE OF THE SOFTWARE WILL BE UNINTERRUPTED OR ERROR-FREE. INFORMATICA SHALL NOT, UNDER ANY CIRCUMSTANCES, BE LIABLE TO LICENSEE FOR LOST PROFITS, CONSEQUENTIAL, INCIDENTAL, SPECIAL OR INDIRECT DAMAGES ARISING OUT OF OR RELATED TO THIS AGREEMENT OR THE TRANSACTIONS CONTEMPLATED HEREUNDER, EVEN IF INFORMATICA HAS BEEN APPRISED OF THE LIKELIHOOD OF SUCH DAMAGES.

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.

## Typedef Documentation

typedef void(* lbm_delete_cb_proc) (int dispatch_thrd, void *clientd)

Application callback for lbm_hypertopic_rcv_delete().

Set by lbm_hypertopic_rcv_delete(). Note: This application callback can be made from the context thread, and is therefore, limited in the LBM API calls that it can make. The application is called after all events associated with the delete are completed.

See also
  lbm_delete_cb_info_t

Parameters

  dispatch_thrd | Indicates from where the callback is being called. This can be useful to the application to avoid deadlock. 1 - Called by the dispatch thread (after the call to lbm_hypertopic_rcv_delete() returns). 0 - Called directly by the lbm_hypertopic_rcv_delete() function.
  clientd | Client data pointer supplied in the lbm_delete_cb_info_t passed to lbm_hypertopic_rcv_delete().

Returns
  0 always.

typedef int(* lbm_hypertopic_rcv_cb_proc) (lbm_hypertopic_rcv_t *hrcv, lbm_msg_t *msg, void *clientd)

Application callback for messages delivered to HyperTopic receivers.

Set by lbm_hypertopic_rcv_add(). If this application callback is set on an HyperTopic receiver that has been initialized without an event queue, it is called from the context thread and is therefore, limited in the API calls that it can make.

After the callback returns, the message object msg is deleted and the application must not refer to it. This behavior can be overridden by calling lbm_msg_retain() from the receive callback before it returns. It then becomes the application's responsibility to delete the message object by calling lbm_msg_delete() after the application no longer needs to refer to the message structure or its contents.

Note
  For received application messages, be aware that LBM does not guarantee any alignment of that data.

Parameters

  hrcv | HyperTopic receiver object generating the event.
  msg | Message object containing the receiver event.
  clientd | Client data pointer supplied in lbm_hypertopic_rcv_add().

Returns
  0 always.

## Function Documentation

LBMExpDLL int lbm_hypertopic_rcv_add | ( | lbm_hypertopic_rcv_t * | hrcv,
|  | const char * | pattern,
|  | lbm_hypertopic_rcv_cb_proc | proc,
|  | void * | clientd
| ) |  |

Add a topic pattern to the set of topics being received by a HyperTopic receiver.

Parameters

  hrcv | HyperTopic object created by lbm_hypertopic_rcv_init()
  pattern | Hierarchical topic pattern to add to the HyperTopic group.
  proc | Pointer to a function to call when messages arrive on a topic matched by pattern.
  clientd | Pointer to client data that is passed to proc when data arrives on the topic matched by pattern.

Returns
  0 for success, -1 on failure

LBMExpDLL int lbm_hypertopic_rcv_delete | ( | lbm_hypertopic_rcv_t * | hrcv,
|  | const char * | pattern,
|  | lbm_hypertopic_rcv_cb_proc | proc,
|  | void * | clientd,
|  | lbm_delete_cb_info_t * | cbinfo
| ) |  |

Delete a previously added topic from a HyperTopic receiver topic set.

Parameters

  hrcv | HyperTopic object created by lbm_hypertopic_rcv_init()
  pattern | Hierarchical topic pattern to delete from the HyperTopic group.
  proc | Pointer to a function being called when messages arrive from the given pattern.
  clientd | Pointer to client data that is being passed to proc when data arrives on a topic matched by pattern.
  cbinfo | Pointer to callback informatin structure specifying a function to be called when the deletion is complete.

Returns
  0 for success, -1 on failure

LBMExpDLL int lbm_hypertopic_rcv_destroy | ( | lbm_hypertopic_rcv_t * | hrcv | ) |

Clean-up HyperTopic receiver previously created by lbm_hypertopic_rcv_init()

Parameters

  hrcv | HyperTopic receiver to be destroyed.

Returns
  0 for success, -1 on failure

LBMExpDLL int lbm_hypertopic_rcv_init | ( | lbm_hypertopic_rcv_t ** | hrcvp,
|  | lbm_context_t * | ctx,
|  | const char * | prefix,
|  | lbm_event_queue_t * | evq
| ) |  |

Initialize a HyperTopic receiver.

Parameters

  hrcvp | Pointer to location where the lbm_hypertopic_rcv_t object will be returned.
  ctx | Pointer to the LBM context object associated with the receiver.
  prefix | Namespace prefix for the HyperTopic receiver. The prefix string constrains the topic namespace to topics that begin with the specified prefix only. This parameter may be set to NULL if no prefix is to be defined for this HyperTopic namespace.
  evq | Optional Event Queue to place message events on when they arrive. If NULL, all messages will be delivered from the context thread.

Returns
  0 for success, -1 on failure