The StructuredPullSupplier Interface

TheStructuredPullSupplierinterface supports operations which enable suppliers to transmit Structured Events by the pull model. It also defines an operation which can be invoked to disconnect the pull supplier from its associated consumer. In addition, the

StructuredPullSupplierinterface inherits theNotifySubscribeinterface described above, enabling a notification consumer to inform an instance supporting this interface whenever there is a change to the types of events it is interested in receiving.

Note that an object supporting theStructuredPullSupplierinterface can transmit events which can potentially be received by any consumer connected to the channel, including those which consume events in a form other than a Structured Event. How events supplied to the channel in the form of a Structured Event are internally mapped into different forms for delivery to consumers which receive events in a form other than the Structured Event is summarized in Table 2-2 on page 2-9.

3.3.9.1 pull_structured_event

Thepull_structured_eventoperation takes no input parameters, and returns a value of typeStructured Eventas defined in theCosNotificationmodule. Upon invocation, the operation will block until an event is available for transmission, at which time it will return an instance of a Structured Event, which contains the event being delivered to its connected consumer. If invoked upon a

StructuredPullSupplierthat is not currently connected to the consumer of the event, theDisconnectedexception will be raised. Note that the condition that a proxy consumer believes it is actively connected to a supplier, while the supplier believes it is

disconnected is an invalid state. Thus, if the invocation ofpull_structured_event

upon aStructuredPullSupplierinstance by aStructuredProxyPullConsumer

instance results in theDisconnectedexception being raised, the

StructuredProxyPullConsumerwill invoke its own

disconnect_structured_pull_consumeroperation, resulting in the destruction of thatStructuredProxyPullConsumerinstance.

In reality there are two types of objects that will support theStructuredPullSupplier

interface: an object representing an application which transmits Structured Events, and aStructuredProxyPullSupplier(defined in theCosNotifyChannelAdmin

module) associated with an event channel which transmits events to a pull style consumer on behalf of the channel. For the first type of object, the implementation of thepull_structured_eventoperation is application specific, and is intended to be supplied by application developers. The application specific implementation of this operation should construct a structured event, and return it within aStructuredEvent

data structure. For the second type of object, the behavior of the operation is tightly linked to the implementation of the event channel. Basically, it is responsible for forwarding a structured event, within aStructuredEventdata structure, as the return value to the consumer it is connected to upon the availability of an event which passes the filter(s) associated with theStructuredProxyPullSupplier. Note that the operation will block until such an event is available to return.

3.3.9.2 try_pull_structured_event

Thetry_pull_structured_eventoperation takes no input parameters, and returns a value of typeStructuredEventas defined in theCosNotificationmodule. It also returns an output parameter of type boolean which indicates whether or not the return value actually contains an event. Upon invocation, the operation will return an instance of a Structured Event which contains the event being delivered to its connected consumer, if such an event is available for delivery at the time the operation was invoked. If an event is available for delivery and thus returned as the result, the output parameter of the operation will be set to TRUE. If no event is available to return upon invocation, the operation will return immediately with the value of the output

parameter set to FALSE. In this case, the return value will not contain a valid event. If invoked upon aStructuredPullSupplierthat is not currently connected to the consumer of the event, theDisconnectedexception will be raised. Note that the condition that a proxy consumer believes it is actively connected to a supplier, while the supplier believes it is disconnected is an invalid state. Thus, if the invocation of

try_pull_structured_eventupon aStructuredPullSupplierinstance by a

StructuredProxyPullConsumerinstance results in theDisconnectedexception being raised, theStructuredProxyPullConsumerwill invoke its own

disconnect_structured_pull_consumeroperation, resulting in the destruction of thatStructuredProxyPullConsumerinstance.

In reality there are two types of objects that will support theStructuredPullSupplier

interface: an object representing an application which transmits Structured Events, and aStructuredProxyPullSupplier(defined within theCosNotifyChannelAdmin

module) associated with an event channel which transmits events to a PullConsumer on behalf of the channel. For the first type of object, the implementation of the

try_pull_structured_eventoperation is application specific, and is intended to be supplied by application developers. If an event is available to be returned upon invocation of this operation, the application specific implementation of this operation should construct a Structured Event, and return it within aStructuredEventdata structure along with setting the value of the output parameter to TRUE. Otherwise, the operation should return immediately after setting the value of the output parameter to FALSE. For the second type of object, the behavior of the operation is tightly linked to the implementation of the event channel. Basically, if an event is available to be returned upon invocation of this operation, it is responsible for forwarding it, within a

StructuredEventdata structure, as the return value to the consumer it is connected to, in addition to setting the output parameter to FALSE. If no event is available to return to the consumer upon invocation of this operation, it will immediately return with the output parameter to set to FALSE, and the return value not containing a valid event.

3.3.9.3 disconnect_structured_pull_supplier

Thedisconnect_structured_pull_supplieroperation is invoked to terminate a connection between the targetStructuredPullSupplier, and its associated consumer. This operation takes no input parameters and returns no values. The result of this operation is that the targetStructuredPullSupplierwill release all resources it had allocated to support the connection, and dispose its own object reference.