7.26. ODPI-C Structure dpiSubscrCreateParams
This structure is used for creating subscriptions to messages sent for object
change notification, query change notification or advanced queuing. All members
are initialized to default values using the
dpiContext_initSubscrCreateParams()
function.
-
dpiSubscrNamespace dpiSubscrCreateParams.subscrNamespace
Specifies the namespace in which the subscription is created. It is expected to be one of the values from the enumeration dpiSubscrNamespace. The default value is DPI_SUBSCR_NAMESPACE_DBCHANGE.
-
dpiSubscrProtocol dpiSubscrCreateParams.protocol
Specifies the protocol used for sending notifications for the subscription. It is expected to be one of the values from the enumeration dpiSubscrProtocol. The default value is DPI_SUBSCR_PROTO_CALLBACK.
-
dpiSubscrQOS dpiSubscrCreateParams.qos
Specifies the quality of service flags to use with the subscription. It is expected to be one or more of the values from the enumeration dpiSubscrQOS, OR’ed together. The default value is to have no flags set.
-
dpiOpCode dpiSubscrCreateParams.operations
Specifies which operations on the registered tables or queries should result in notifications. It is expected to be one or more of the values from the enumeration dpiOpCode, OR’ed together. The default value is DPI_OPCODE_ALL_OPS.
-
uint32_t dpiSubscrCreateParams.portNumber
Specifies the port number on which to receive notifications. The default value is 0, which means that a port number will be selected by the Oracle client.
-
uint32_t dpiSubscrCreateParams.timeout
Specifies the length of time, in seconds, before the subscription is unregistered. If the value is 0, the subscription remains active until explicitly unregistered. The default value is 0.
-
const char *dpiSubscrCreateParams.name
Specifies the name of the subscription, as a byte string in the encoding used for CHAR data. This name must be consistent with the namespace identified in the
dpiSubscrCreateParams.subscrNamespace
member. The default value is NULL.
-
uint32_t dpiSubscrCreateParams.nameLength
Specifies the length of the
dpiSubscrCreateParams.name
member, in bytes. The default value is 0.
-
dpiSubscrCallback dpiSubscrCreateParams.callback
Specifies the callback that will be called when a notification is sent to the subscription, if the
dpiSubscrCreateParams.protocol
member is set to DPI_SUBSCR_PROTO_CALLBACK. The callback accepts the following arguments:context – the value of the
dpiSubscrCreateParams.callbackContext
member.message – a pointer to the message that is being sent. The message is in the form dpiSubscrMessage.
The default value is NULL. If a callback is specified and a notification is sent, this will be performed on a separate thread. If database operations are going to take place, ensure that the create mode DPI_MODE_CREATE_THREADED is set in the structure dpiCommonCreateParams when creating the session pool or standalone connection that will be used in this callback.
-
void *dpiSubscrCreateParams.callbackContext
Specifies the value that will be used as the first argument to the callback specified in the
dpiSubscrCreateParams.callback
member. The default value is NULL.
-
const char *dpiSubscrCreateParams.recipientName
Specifies the name of the recipient to which notifications are sent when the
dpiSubscrCreateParams.protocol
member is not set to DPI_SUBSCR_PROTO_CALLBACK. The value is expected to be a byte string in the encoding used for CHAR data. The default value is NULL.
-
uint32_t dpiSubscrCreateParams.recipientNameLength
Specifies the length of the
dpiSubscrCreateParams.recipientName
member, in bytes. The default value is 0.
-
const char *dpiSubscrCreateParams.ipAddress
Specifies the IP address on which the subscription listens to receive notifications. The IP address can be an IPv4 address in dotted decimal format such as 192.1.2.34 or an IPv6 address in hexadecimal format such as 2001:0db8:0000:0000:0217:f2ff:fe4b:4ced. The default value is NULL which means that an IP address will be selected by the Oracle client.
-
uint32_t dpiSubscrCreateParams.ipAddressLength
Specifies the length of the
dpiSubscrCreateParams.ipAddress
member, in bytes. The default value is 0.
-
uint8_t dpiSubscrCreateParams.groupingClass
Specifies the grouping class to use when grouping events. It should be one of the values from the enumeration dpiSubscrGroupingClass. The default value is 0. If this value is 0, the groupingValue and groupingType attributes are ignored.
-
uint32_t dpiSubscrCreateParams.groupingValue
Specifies the value to be used in grouping. The meaning of this value depends on the value of the groupingClass attribute. For time based grouping this value refers to the number of seconds during which events will be grouped together. The default value is 0.
-
uint8_t dpiSubscrCreateParams.groupingType
Specifies the type of grouping to use when grouping events. It should be one of the values from the enumeration dpiSubscrGroupingType. The default value is DPI_SUBSCR_GROUPING_TYPE_SUMMARY.
-
uint64_t dpiSubscrCreateParams.outRegId
Specifies the registration id of the subscription that corresponds to the REG_ID column in the USER_SUBSCR_REGISTRATIONS and DBA_SUBSCR_REGISTRATIONS views in the database. It will be populated for CQN registrations after a successful call to
dpiConn_subscribe()
.
-
int dpiSubscrCreateParams.clientInitiated
Specifies whether a client initiated connection should be created (1) or a server initiated connection should be created (0). The default value is 0. This feature is only available when Oracle Client 19.4 and Oracle Database 19.4 or higher are being used.