Subscription Class

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

Table 13-47 Enumerated Values Used by Subscription Class

Attribute	Options
Presentation	`PRES_DEFAULT` indicates that the event notification should be in default format. `PRES_XML` indicates that the event notification should be in XML format.
Protocol	`PROTO_CBK` indicates that the client receives notifications through the default system protocol. `PROTO_MAIL` indicates that the client receives notifications through e-mail, like `xyz@oracle.com`. The database does not check if the e-mail is valid. `PROTO_SERVER` indicates that the client receives notifications through an invoked PL/SQL procedure in the database, like `schema.procedure`. The subscriber must have the appropriate permissions on the procedure. `PROTO_HTTP` indicates that the client receives notifications through an HTTP URL, like `http://www.oracle.com:80`. The database does not check if the URL is valid.
Namespace	`NS_ANONYMOUS` indicates that the registrations are made in an anonymous namespace. `NS_AQ` indicates that the registrations are made in the Oracle Streams Advanced Queuing namespace.

Table 13-48 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.
getNotifyCallback()	Returns the pointer to the registered callback function.
getPayload()	Retrieves the payload that has been set on the `Subscription` object before 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.
isNull()	Determines if the `Subscription` is `NULL`.
operator=()	Assignment operator for `Subscription`.
setCallbackContext()	Registers a callback function for OCI protocol.
setDatabaseServerNames()	Specifies the database server distinguished names from which the client receives 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 receives notifications.
setProtocol()	Specifies the protocol in which the client receives notifications.
setSubscriptionName()	Specifies the name of the subscription.
setSubscriptionNamespace()	Specifies the namespace where the subscription is used.
setRecipientName()	Specifies the name of the recipient of the notification.

Subscription()

Subscription class constructor.

Syntax	Description
Subscription ( const Environment *env );	Creates a `Subscription` within a specified `Environment`.
Subscription( const Subscription& sub);	Copy constructor.

Syntax

Subscription(const Subscription& sub);

Parameter	Description
env	The `Environment`.
sub	The original `Subscription`.

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() const;

getDatabaseServerNames()

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

Syntax

vector<string> getDatabaseServerNames() const;

getNotifyCallback()

Returns the pointer to the callback function registered for this Subscription.

Syntax

unsigned int (*getNotifyCallback() const)(
   Subscription& sub,
   NotifyResult *nr);

Parameter	Description
sub	The `Subscription`.
nr	The `NotifyResult`.

getPayload()

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

Syntax

Bytes getCPayload() const;

getSubscriptionName()

Retrieves the name of the subscription.

Syntax

string getSubscriptionName() const;

getSubscriptionNamespace()

Retrieves the namespace of the subscription. The subscription name must be consistent with its namespace. Valid Namespace values are NS_AQ and NS_ANONYMOUS, as defined in Table 13-47.

Syntax

Namespace getSubscriptionNamespace() const;

getRecipientName()

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

Syntax

string getRecipientName() const;

getPresentation()

Retrieves the presentation mode in which the client receives notifications. Valid Presentation values are defined in Table 13-47.

Syntax

Presentation getPresentation() const;

getProtocol()

Retrieves the protocol in which the client receives notifications. Valid Protocol values are defined in Table 13-47.

Syntax

Protocol getProtocol() const;

isNull()

Returns TRUE if Subscription is NULL or FALSE otherwise.

Syntax

bool isNull() const;

operator=()

Assignment operator for Subscription.

Syntax

void operator=(
   const Subscription& sub);

Parameter	Description
sub	The original `Subscription`.

setCallbackContext()

Registers a notification callback function when the protocol is PROTO_CBK, as defined in Table 13-47. 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 receives 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 must 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()

Sets the presentation mode in which the client receives notifications.

Syntax

void setPresentation(
   Presentation pres);

Parameter	Description
pres	Presentation mode, as defined in Table 13-47.

setProtocol()

Sets the Protocol in which the client receives event notifications, as defined in Table 13-47.

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 where 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 is used, as defined in Table 13-47.

setRecipientName()

Sets the name of the recipient of the notification.

Syntax

void setRecipientName( 
   const string& name);

Parameter	Description
name	Name of the notification recipient.