Open topic with navigation

TIBCO Rendezvous® 8.8.0

# tibrvEvent_CreateListener()

Function

## Declaration

    tibrv_status tibrvEvent_CreateListener(
        tibrvEvent*            event,
        tibrvQueue             queue,
        tibrvEventCallback     callback,
        tibrvTransport         transport,
        const char*            subject,
        const void*            closure);

## Purpose

Listen for inbound messages.

Parameter | Description
`event` | For each inbound message, place this event on the event queue. The program supplies a location, and the function stores the new event in that location. The event object remains valid until the program explicitly destroys it.
`queue` | For each inbound message, place the event on this event queue.
`callback` | On dispatch, process the event with this callback function.
`transport` | Listen for inbound messages on this transport.
`subject` | Listen for inbound messages with subjects that match this specification. Wildcard subjects are permitted. The empty string is not a legal subject name.
`closure` | Store this closure data in the event object.

## Activation and Dispatch

Inbound messages on the transport that match the subject trigger the event.

This function creates a listener event object, and activates the event—that is, it begins listening for all inbound messages with matching subjects. When a message arrives, Rendezvous software places the event object and message on its event queue. Dispatch removes the event object from the queue, and runs the callback function to process the message. (To stop receiving inbound messages on the subject, destroy the event object; this action cancels all messages already queued for the listener event; see also tibrvEvent_Destroy().)

Listener Activation and Dispatch illustrates that Rendezvous software does not deactivate the listener when it places new message events on the queue (in contrast to I/O events, which are temporarily deactivated). Consequently, several messages can accumulate in the queue while the callback function is processing.

Figure 180: Listener Activation and Dispatch

When the callback function is I/O-bound, messages can arrive faster than the callback function can process them, and the queue can grow unacceptably long. In applications where a delay in processing messages is unacceptable, consider dispatching from several threads to process messages concurrently.

## Listening for Advisory Messages

Use this function to listen for advisory subjects. We recommend sending advisory message events to the default queue.

## Inbox Listener

To receive unicast (point-to-point) messages, listen to an inbox subject name. First call tibrvTransport_CreateInbox() to create the unique inbox name; then call tibrvEvent_CreateListener() to begin listening. Remember that other programs have no information about an inbox until the listening program uses it as a reply subject in an outbound message. See also, Inbox Names in TIBCO Rendezvous Concepts.

## See Also

tibrvEvent_GetListenerSubject()

tibrvTransport_CreateInbox()

Did you find this helpful?

Yes No
Great!
Thanks for taking the time to give us some feedback.
Sorry about that

Why wasn't this helpful? (check all that apply)

Could not find what I was looking for
Instructions confusing or unclear
Instructions did not work

Want to tell us more?

Please select at least one option or provide details about the issue!!

Error occurred while submitting feedback.

Error2 occurred while submitting feedback.

TIBCO Rendezvous®

Copyright © 1997-2025. Cloud Software Group, Inc. All Rights Reserved.