Subscription Class

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

Subscription()

Subscription class constructor.

Subscription (
const Environment *env );

env

getCallbackContext()

Retrieves the callback context.

void* getCallbackContext() const;

getDatabaseServersCount()

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

unsigned int getDatabaseServersCount();

getDatabaseServerNames()

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

vector<string> getDatabaseServerNames();

getPayload()

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

void* getCPayload() const;

getSubscriptionName()

Retrieves the name of the subscription.

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.

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.

const string& getRecipientName();

getPresentation()

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

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.

Protocol getProtocol();

setCallbackContext()

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

void setCallbackContext(
   void *ctx);

ctx

setDatabaseServerNames()

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

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

dbsrv

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.

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

callback

sub

nr

setNull()

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

void setNull();

setPayload()

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

void setPayload(
   const Bytes& payload);

payload

setPresentation()

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

void setPresentation(
   unsigned int presentation);

presentation

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

void setProtocol(
   Protocol prot);

prot

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

void setSubscriptionName(
   const string& name);

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.

void setSubscriptionNamespace(
   Namespace nameSpace);

nameSpace

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.

void setRecipientName( 
   const string& recipient);

recipient