Skip Headers
Oracle® C++ Call Interface Programmer's Guide
10g Release 2 (10.2)

Part Number B14294-02
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

Subscription Class

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

Table 12-46 Enumerated Values Used by Subscription Class

Attribute Options
Presentation
  • PRES_DEFAULT indicates that the event notification shold be in default format.

  • PRES_XML indicates that the event notification should be in XML format.

Protocol
  • PROTO_CBK indicates that the client will receive notifications through the default system protocol.

  • PROTO_MAIL indicates that the client will receive 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 will receive 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 will receive 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 will be made in an anonymous namespace.

  • NS_AQ indicates that the registrations will be made in the Oracle Streams Advanced Queuing namespace.


Table 12-47 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 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.

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 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.

setSubscriptionName()


Specifiess 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 prior to 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 12-46.

Syntax

Namespace getSubscriptionNamespace() const;


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

string getRecipientName() const;


getPresentation()

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

Syntax

Presentation getPresentation() const;


getProtocol()

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

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 12-46. 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()

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

Syntax

void setPresentation(
   Presentation pres);
Parameter Description
pres
Presentation mode, as defined in Table 12-46.


setProtocol()

Sets the Protocol in which the client will receive event notifications, as defined in Table 12-46.

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:

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 12-46.


setRecipientName()

Sets the name of the recipient of the notification.

Syntax

void setRecipientName( 
   const string& name);
Parameter Description
name
Name of the notification recipient.