Subscription Class

The subscription class encapsulates the information and operations necessary for registering a subscriber for notification.

Table 10-40 Summary of Subscription Methods

Method	Summary
Subscription()	`Subscription` class constructor.
getCallbackContext()	Retrieves the callback context.
getDatabaseServersCount()	Retrieves the number of database servers in which the client is interested for the registration.
getDatabaseServerNames()	Returns the names of all the database servers where the client registered an interest for notification.
getPayload()	Retrieves the payload that has been set on the `Subscription` object prior to posting.
getSubscriptionName()	Retrieves the name of the `Subscription`.
getSubscriptionNamespace()	Retrieves the namespace of the `Subscription`.
getRecipientName()	Retrieves the name of the `Subscription` recipient.
getPresentation()	Retrieves the notification presentation mode.
getProtocol()	Retrieves the notification protocol.
setCallbackContext()	Registers a callback function for OCI protocol.
setDatabaseServerNames()	Specifies the database server distinguished names from which the client will receive notifications.
setNotifyCallback()	Specifies the context passed to user callbacks
setNull()	Specifies the `Subscription` object to `NULL` and frees the memory associated with the object.
setSubscriptionName()	Specifies the name of the subscription.
setSubscriptionNamespace()	Specifies the namespace in which the subscription is used.
setPayload()	Specifies the buffer content of the notification.
setRecipientName()	Specifies the name of the recipient of the notification.
setPresentation()	Specifies the presentation mode in which the client will receive notifications.
setProtocol()	Specifies the protocol in which the client will receive notifications.

Subscription()

Subscription class constructor.

Syntax

Subscription (
const Environment *env );

Parameter	Description
env	The `Environment`.

getCallbackContext()

Retrieves the callback context.

Syntax

void* getCallbackContext() const;

getDatabaseServersCount()

Returns the number of database servers in which the client is interested for the registration.

Syntax

unsigned int getDatabaseServersCount();

getDatabaseServerNames()

Returns the names of all the database servers where the client registered an interest for notification.

Syntax

vector<string> getDatabaseServerNames();

getPayload()

Retrieves the payload that has been set on the Subscription object prior to posting.

Syntax

void* getCPayload() const;

getSubscriptionName()

Retrieves the name of the subscription.

Syntax

const string& getSubscriptionName();

getSubscriptionNamespace()

Retrieves the namespace of the subscription. The subscription name must be consistent with its namespace; currently supports Subscription::NS_AQ and Subscription::NS_Anonymous.

Syntax

Namespace getSubscriptionNamespace();

getRecipientName()

Retrieves the name of the recipient of the notification. Possible return values are email address, the HTTP url and the PL/SQL procedure, depending on the protocol.

Syntax

const string& getRecipientName();

getPresentation()

Retrieves the presentation mode in which the client receives notifications. Valid values are PRES_DEFAULT and PRES_XML.

Syntax

unsigned int getPresentation();

getProtocol()

Retrieves the protocol in which the client receives notifications. Valid values are PROTO_CBK, PROTO_MAIL, PROTO_HTTP, and PROTO_SERVER.

Syntax

Protocol getProtocol();

setCallbackContext()

Registers a notification callback function when the protocol is set to PROTO_CBK. Context registration is also included in this call.

Syntax

void setCallbackContext(
   void *ctx);

Parameter	Description
ctx	The context set.

setDatabaseServerNames()

Specifies the list of database server distinguished names from which the client will receive notifications.

Syntax

void setDatabaseServerNames(
   const vector<string>& dbsrv);

Parameter	Description
dbsrv	The list of database distinguished names

setNotifyCallback()

Sets the context that the client wants to get passed to the user callback. If the protocol is set to PROTO_CBK or not specified, this attribute needs to be set before registering the subscription handle.

Syntax

void setNotifyCallback( 
   unsigned int (*callback)(
                    Subscription& sub,
                    NotifyResult *nr));

Parameter	Description
callback	The user callback function.
sub	The `Subscription` object.
nr	The `NotifyResult` object.

setNull()

Sets the Subscription object to NULL and frees the memory associated with the object.

Syntax

void setNull();

setPayload()

Sets the buffer content that corresponds to the payload to be posted to the Subscription.

Syntax

void setPayload(
   const Bytes& payload);

Parameter	Description
payload	Content of the notification.

setPresentation()

Set the presentation mode in which the client will receive notifications.

Syntax

void setPresentation(
   unsigned int presentation);

Parameter	Description
presentation	Presentation mode: `PRES_DEFAULT` `PRES_XML`

setProtocol()

Sets the protocol in which the client will receive event notifications:

PROTO_CBK (default)
PROTO_MAIL -- through e-mail
PROTO_SERVER -- through an invoked PL/SQL procedeure in the database
PROTO_HTTP -- through an HTTP URL

Syntax

void setProtocol(
   Protocol prot);

Parameter	Description
prot	Protocol mode

setSubscriptionName()

Sets the name of the subscription. All subscriptions are identified by a subscription name, which consists of a sequence of bytes of specified length.

If the namespace is NS_AQ, the subscription name is:

SCHEMA.QUEUE when registering on a single consumer queue
SCHEMA.QUEUE:CONSUMER_NAME when registering on a multiconsumer queue

Syntax

void setSubscriptionName(
   const string& name);

Parameter	Description
name	Subscription name.

setSubscriptionNamespace()

Sets the namespace in which the subscription is used. The subscription name must be consistent with its namespace. Default value is NS_AQ.

Syntax

void setSubscriptionNamespace(
   Namespace nameSpace);

Parameter	Description
nameSpace	Namespace in which the subscription handle is used. Valid values include `Subscription::NS_AQ` and `Subscription::NS_Anonymous`.

setRecipientName()

Sets the name of the recipient of the notification.

For PROTO_HTTP, this is the HTTP URL to which the notification is sent, like http://www.oracle.com:80. The database does not check if the URL is valid.
For PROTO_MAIL, this is the e-mail address to which the notification is sent, like xyz@oracle.com. The database does not check if the e-mail is valid.
For PROTO_SERVER, this is the database procedure invoked by the notification, like schema.procedure. The subscriber must have the appropriate permissions on the procedure.

Syntax

void setRecipientName( 
   const string& recipient);

Parameter	Description
recipient	Name of the notification recipient.