Correct parameter to dpiConn_newSubscription() as noted in issue #28.…

… There is

no OCI documentation for the registration id attribute and it should not be
exposed.  The parameter is also deprecated and will be removed in version 2.1
of the ODPI-C API.

doc/src/public_functions/dpiConn.rst

@@ -518,7 +518,7 @@ handles.
 
 .. function:: int dpiConn_newSubscription(dpiConn \*conn, \
         dpiSubscrCreateParams \*params, dpiSubscr \**subscr, \
-        uint32_t \*subscrId)
+        uint64_t \*subscrId)
 
     Returns a reference to a subscription which is used for requesting
     notifications of changes on tables or queries that are made in the
@@ -539,7 +539,8 @@ handles.
     created by this function.
 
     **subscrId** [OUT] -- a pointer to the id of the subscription that is
-    created by this function.
+    created by this function, or NULL. This parameter is deprecated and will be
+    removed in version 2.1.
 
 
 .. function:: int dpiConn_newTempLob(dpiConn \*conn, \

include/dpi.h

@@ -759,7 +759,7 @@ int dpiConn_newMsgProps(dpiConn *conn, dpiMsgProps **props);
 
 // create a new subscription for events
 int dpiConn_newSubscription(dpiConn *conn, dpiSubscrCreateParams *params,
-        dpiSubscr **subscr, uint32_t *subscrId);
+        dpiSubscr **subscr, uint64_t *subscrId);
 
 // create a new temporary LOB
 int dpiConn_newTempLob(dpiConn *conn, dpiOracleTypeNum lobType, dpiLob **lob);

samples/TestCQN.c

@@ -76,9 +76,9 @@ void TestCallback(void *context, dpiSubscrMessage *message)
 //-----------------------------------------------------------------------------
 int main(int argc, char **argv)
 {
-    uint32_t subscrId, numQueryColumns, i;
     dpiCommonCreateParams commonParams;
     dpiSubscrCreateParams createParams;
+    uint32_t numQueryColumns, i;
     dpiSampleParams *params;
     dpiSubscr *subscr;
     uint64_t queryId;
@@ -98,7 +98,7 @@ int main(int argc, char **argv)
         return dpiSamples_showError();
     createParams.qos = DPI_SUBSCR_QOS_QUERY | DPI_SUBSCR_QOS_ROWIDS;
     createParams.callback = TestCallback;
-    if (dpiConn_newSubscription(conn, &createParams, &subscr, &subscrId) < 0)
+    if (dpiConn_newSubscription(conn, &createParams, &subscr, NULL) < 0)
         return dpiSamples_showError();
 
     // register query

src/dpiConn.c

@@ -1397,7 +1397,7 @@ int dpiConn_newMsgProps(dpiConn *conn, dpiMsgProps **props)
 //   Create a new subscription and return it.
 //-----------------------------------------------------------------------------
 int dpiConn_newSubscription(dpiConn *conn, dpiSubscrCreateParams *params,
-        dpiSubscr **subscr, uint32_t *subscrId)
+        dpiSubscr **subscr, uint64_t *subscrId)
 {
     dpiSubscr *tempSubscr;
     dpiError error;
@@ -1406,7 +1406,6 @@ int dpiConn_newSubscription(dpiConn *conn, dpiSubscrCreateParams *params,
         return DPI_FAILURE;
     DPI_CHECK_PTR_NOT_NULL(params)
     DPI_CHECK_PTR_NOT_NULL(subscr)
-    DPI_CHECK_PTR_NOT_NULL(subscrId)
     if (dpiGen__allocate(DPI_HTYPE_SUBSCR, conn->env, (void**) &tempSubscr,
             &error) < 0)
         return DPI_FAILURE;

src/dpiImpl.h

@@ -960,7 +960,7 @@ void dpiRowid__free(dpiRowid *rowid, dpiError *error);
 //-----------------------------------------------------------------------------
 void dpiSubscr__free(dpiSubscr *subscr, dpiError *error);
 int dpiSubscr__create(dpiSubscr *subscr, dpiConn *conn,
-        dpiSubscrCreateParams *params, uint32_t *subscrId, dpiError *error);
+        dpiSubscrCreateParams *params, uint64_t *subscrId, dpiError *error);
 
 
 //-----------------------------------------------------------------------------

src/dpiSubscr.c

@@ -64,7 +64,7 @@ static void dpiSubscr__callback(dpiSubscr *subscr, void *handle, void *payload,
 // is returned.
 //-----------------------------------------------------------------------------
 int dpiSubscr__create(dpiSubscr *subscr, dpiConn *conn,
-        dpiSubscrCreateParams *params, uint32_t *subscrId, dpiError *error)
+        dpiSubscrCreateParams *params, uint64_t *subscrId, dpiError *error)
 {
     uint32_t qosFlags;
     int rowids;
@@ -166,10 +166,13 @@ int dpiSubscr__create(dpiSubscr *subscr, dpiConn *conn,
     if (dpiOci__subscriptionRegister(conn, &subscr->handle, error) < 0)
         return DPI_FAILURE;
 
-    // get the registration id
-    return dpiOci__attrGet(subscr->handle, DPI_OCI_HTYPE_SUBSCRIPTION,
+    // get the registration id, if applicable
+    if (subscrId && dpiOci__attrGet(subscr->handle, DPI_OCI_HTYPE_SUBSCRIPTION,
             subscrId, NULL, DPI_OCI_ATTR_SUBSCR_CQ_REGID,
-            "get reigstration id", error);
+            "get registration id", error) < 0)
+        return DPI_FAILURE;
+
+    return DPI_SUCCESS;
 }
 
 

test/TestConn.c

@@ -35,7 +35,6 @@ int dpiTest__callFunctionsWithError(dpiTestCase *testCase,
     dpiEncodingInfo info;
     dpiMsgProps *props;
     dpiSubscr *subscr;
-    uint32_t subscrId;
     int commitNeeded;
     dpiData *data;
     dpiStmt *stmt;
@@ -122,7 +121,7 @@ int dpiTest__callFunctionsWithError(dpiTestCase *testCase,
     if (dpiTestCase_expectError(testCase, expectedError) < 0)
         return DPI_FAILURE;
 
-    dpiConn_newSubscription(conn, &subscrParams, &subscr, &subscrId);
+    dpiConn_newSubscription(conn, &subscrParams, &subscr, NULL);
     if (dpiTestCase_expectError(testCase, expectedError) < 0)
         return DPI_FAILURE;
 

test/TestSubscriptions.c

@@ -30,7 +30,6 @@ int dpiTest_2200_verifyNewSubscriptionWithCallBkNULL(dpiTestCase *testCase,
     dpiSubscrCreateParams subParams;
     dpiContext *context;
     dpiSubscr *subscr;
-    uint32_t subscrId;
     dpiConn *conn;
 
     dpiTestSuite_getContext(&context);
@@ -46,7 +45,7 @@ int dpiTest_2200_verifyNewSubscriptionWithCallBkNULL(dpiTestCase *testCase,
         return dpiTestCase_setFailedFromError(testCase);
     subParams.callback = NULL;
     subParams.protocol = DPI_SUBSCR_PROTO_CALLBACK;
-    dpiConn_newSubscription(conn, &subParams, &subscr, &subscrId);
+    dpiConn_newSubscription(conn, &subParams, &subscr, NULL);
     if (dpiTestCase_expectError(testCase, expectedError) < 0)
         return DPI_FAILURE;
     dpiConn_release(conn);