.. _dpiSubscrCreateParams:

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
:func:`dpiContext_initSubscrCreateParams()` function.

.. member:: dpiSubscrNamespace dpiSubscrCreateParams.subscrNamespace

    Specifies the namespace in which the subscription is created. It is
    expected to be one of the values from the enumeration
    :ref:`dpiSubscrNamespace<dpiSubscrNamespace>`. The default value is
    DPI_SUBSCR_NAMESPACE_DBCHANGE.

.. member:: 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
    :ref:`dpiSubscrProtocol<dpiSubscrProtocol>`. The default value is
    DPI_SUBSCR_PROTO_CALLBACK.

.. member:: 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
    :ref:`dpiSubscrQOS<dpiSubscrQOS>`, OR'ed together. The default value is to
    have no flags set.

.. member:: 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 :ref:`dpiOpCode<dpiOpCode>`, OR'ed together. The
    default value is DPI_OPCODE_ALL_OPS.

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

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

.. member:: 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 :member:`dpiSubscrCreateParams.subscrNamespace` member.
    The default value is NULL.

.. member:: uint32_t dpiSubscrCreateParams.nameLength

    Specifies the length of the :member:`dpiSubscrCreateParams.name` member, in
    bytes. The default value is 0.

.. member:: dpiSubscrCallback dpiSubscrCreateParams.callback

    Specifies the callback that will be called when a notification is sent to
    the subscription, if the :member:`dpiSubscrCreateParams.protocol` member
    is set to DPI_SUBSCR_PROTO_CALLBACK. The callback accepts the following
    arguments:

        **context** -- the value of the
        :member:`dpiSubscrCreateParams.callbackContext` member.

        **message** -- a pointer to the message that is being sent. The message
        is in the form :ref:`dpiSubscrMessage<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
    :ref:`dpiCommonCreateParams<dpiCommonCreateParams>` when creating the
    session pool or standalone connection that will be used in this callback.

.. member:: void* dpiSubscrCreateParams.callbackContext

    Specifies the value that will be used as the first argument to the callback
    specified in the :member:`dpiSubscrCreateParams.callback` member. The
    default value is NULL.

.. member:: const char* dpiSubscrCreateParams.recipientName

    Specifies the name of the recipient to which notifications are sent when
    the :member:`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.

.. member:: uint32_t dpiSubscrCreateParams.recipientNameLength

    Specifies the length of the :member:`dpiSubscrCreateParams.recipientName`
    member, in bytes. The default value is 0.

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

.. member:: uint32_t dpiSubscrCreateParams.ipAddressLength

    Specifies the length of the :member:`dpiSubscrCreateParams.ipAddress`
    member, in bytes. The default value is 0.

.. member:: uint8_t dpiSubscrCreateParams.groupingClass

    Specifies the grouping class to use when grouping events. It should be one
    of the values from the enumeration
    :ref:`dpiSubscrGroupingClass<dpiSubscrGroupingClass>`. The default value is
    0. If this value is 0, the groupingValue and groupingType attributes are
    ignored.

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

.. member:: uint8_t dpiSubscrCreateParams.groupingType

    Specifies the type of grouping to use when grouping events. It should be
    one of the values from the enumeration
    :ref:`dpiSubscrGroupingType<dpiSubscrGroupingType>`. The default value is
    DPI_SUBSCR_GROUPING_TYPE_SUMMARY.

.. member:: 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 :func:`dpiConn_subscribe()`.


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