From 9d780b0fdd07494e89cfd23fbb87b00e66000e1c Mon Sep 17 00:00:00 2001 From: Jeff Hill Date: Tue, 3 Sep 2002 21:26:54 +0000 Subject: [PATCH] documented structures passed by value to callbacks --- src/ca/CAref.html | 156 ++++++++++++++++++++++++++++++---------------- 1 file changed, 102 insertions(+), 54 deletions(-) diff --git a/src/ca/CAref.html b/src/ca/CAref.html index 3b1b46021..3040b2c4c 100644 --- a/src/ca/CAref.html +++ b/src/ca/CAref.html @@ -104,7 +104,8 @@ height="31" width="88">

  • process CA client library background activities
  • flush outstanding requests to the server
    • -
  • replace the default exception handler
    • +
  • replace the default exception + handler

    • Function Call Interface Index

    @@ -127,8 +128,8 @@ height="31" width="88">

  • ca_message
  • ca_name
  • ca_read_access
    • -
  • ca_replace_access_rights_event
    • -
  • ca_replace_printf_handler
    • +
  • ca_replace_access_rights_event
    • +
  • ca_replace_printf_handler
  • ca_pend_event
  • ca_pend_io
  • ca_poll
    • @@ -477,7 +478,7 @@ EPICS_CA_BEACON_PERIOD.

    Interval

    The CA client library will continuously attempt to connect any CA channels -that an application has created until it is successful. The CA client library +that an application has created until it is successful. The library periodically queries the server destination address list described above with name resolution requests for any unresolved channels. Since this address list frequently contains broadcast addresses, and because nonexistent process @@ -494,11 +495,11 @@ operating system - whichever is greater. The number of UDP frames per interval is also dynamically adjusted based on the past success rate.

    If name resolution requests are not responded to, then the client library -doubles the delay between name resolution attempts with each attempt -eventually limited by a maxuimum plateau interval, and it also reduces the -number of requests per interval. After some long interval, if the client -library does not receive any responses it stops sending name resolution -attempts altogether until it sees a beacon anomaly.

    +doubles the delay between name resolution attempts and reduces the number of +requests per interval. The delay between attempts is initially limited by a +maxuimum however, after some long interval, if the client library does not +receive any responses it stops sending name resolution attempts altogether +until it sees a beacon anomaly.

    The CA client library continually estimates the beacon period of all server beacons received. If a particular server's beacon period becomes @@ -972,31 +973,35 @@ int main ( int argc, char ** argv )

    User Supplied Callback Functions

    Certain CA client initiated requests asynchronously execute an application -supplied call back in the client when a response arrives. The functions -ca_put_callback, ca_get_callback, and ca_add_event all request notification -of asynchronous completion via this mechanism. The structure -"event_handler_args" is passed to the application supplied callback. In this -structure the field "dbr" is a void pointer to any data that might be -returned. The field "status" will be set to one of the CA error codes in -caerr.h and will indicate the status of the operation performed in the IOC. -If the status field isn't set to ECA_NORMAL or data isn't normally returned -from the operation (i.e. put call back) then you should expect that the field -"dbr" will be set to NULL. The fields "usr", "chid", and "type" are set to -the values specified when the request was made by the application.

    -
    struct event_handler_args { 
-    void *usr; /* user argument supplied when event added */ 
-    chid chid; /* channel id */ 
-    long type; /* dbr type of the value returned */ 
-    long count; /* element count of the item(s) returned */ 
-    const void *dbr; /* pointer to the value returned */ 
-    int status; /* ECA_XXX status of the op from server */ 
-};
+supplied call back in the client process when a response arrives. The
+functions ca_put_callback, ca_get_callback, and ca_add_event all request
+notification of asynchronous completion via this mechanism. The
+event_handler_args structure is passed by value to the
+application supplied callback. In this structure the dbr field
+is a void pointer to any data that might be returned. The
+status field will be set to one of the CA error
+codes in caerr.h and will indicate the status of the operation performed in
+the IOC. If the status field isn't set to ECA_NORMAL or data isn't normally
+returned from the operation (i.e. put call back) then you should expect that
+the dbr field  will be set to a nill pointer (zero). The fields
+usr, chid, and type are set to the
+values specified when the request was made by the application.
    
+
    typedef struct event_handler_args {
+    void            *usr;   /* user argument supplied with request */
+    chanId          chid;   /* channel id */
+    long            type;   /* the type of the item returned */ 
+    long            count;  /* the element count of the item returned */
+    const void      *dbr;   /* a pointer to the item returned */
+    int             status; /* ECA_XXX status of the requested op from the server */
+} evargs;
 
 void myCallback ( struct event_handler_args args )
 {
-    if ( type == DBR_TIME_DOUBLE ) {
-        const struct dbr_time_double * pTD = 
-            ( const struct dbr_time_double * ) args.dbr;
+    if ( args.status != ECA_NOEMAL ) {
+    }
+    if ( args.type == DBR_TIME_DOUBLE ) {
+         const struct dbr_time_double * pTD =
+              ( const struct dbr_time_double * ) args.dbr;
     }
 }
    
 
@@ -1141,6 +1146,11 @@ int ca_context_create ( enum ca_preemptive_callback_select SELECT );
    This function should be called once prior to making any of the other channel access calls.

    +

    If ca_disable_preemptive_callback is specified then +additional threads are not allowed to join the CA context using +ca_context_attach() because allowing other threads to join implies that CA +callbacks will be called preemptively from more than one thread.

    +

    Arguments

    SELECT
    @@ -1239,11 +1249,6 @@ are made by the application can't be guaranteed, and application programs may need to be prepared for a connected channel to enter a disconnected state at any time.

    -

    If ca_disable_preemptive_callback is specified then -additional threads are not allowed to join the CA context using -ca_context_attach() because allowing other threads to join implies that CA -callbacks will be called preemptively from more than one thread.

    -

    Example

    See caExample.c in the example application created by makeBaseApp.pl.

    @@ -1263,7 +1268,19 @@ callbacks will be called preemptively from more than one thread.

    Optional address of the user's call back function to be run when the connection state changes. Casual users of channel access may decide to set this field to nil or 0 if they do not need to have a call back - function run in response to each connection state change event.
    + function run in response to each connection state change event. +

    The following structure is passed by value to the user's + connection connection callback function. The op field will + be set by the CA client library to CA_OP_CONN_UP when the + channel connects, and to CA_OP_CONN_DOWN when the channel + disconnects. See ca_puser if the + PUSER argument is required in your callback + handler.

    + 
    struct  ca_connection_handler_args { 
+    chanId  chid;  /* channel id */   
+    long    op;    /* one of CA_OP_CONN_UP or CA_OP_CONN_DOWN */ 
+};
    +
    PUSER
    @@ -1399,8 +1416,8 @@ This allows several requests to be efficiently combined into one message.

    PFUNC
    -
    address of user supplied function to be run when the requested - operation completes
    +
    address of user supplied callback function to be + run when the requested operation completes
    USERARG
    @@ -1494,8 +1511,8 @@ in one message.

    USERFUNC
    -
    Address of user supplied function to be run when the requested - operation completes.
    +
    Address of user supplied callback function to be + run when the requested operation completes.
    USERARG
    @@ -1603,8 +1620,8 @@ least
    USRERFUNC
    -
    Address of user supplied callback function to be invoked with each - subscription update
    +
    The address of user supplied callback function to + be invoked with each subscription update.
    USERARG
    @@ -1874,7 +1891,8 @@ int ca_add_exception_event ( pCallback USERFUNC, void *USERARG );

    Description

    -

    Replace the currently installed exception handler call back.

    +

    Replace the currently installed CA context global exception handler call +back.

    When an error occurs in the server asynchronous to the clients thread then information about this type of error is passed from the server to the client @@ -1892,9 +1910,25 @@ field should not be used.

    Arguments

    USERFUNC
    -
    Addressof usercall back functionto beexecuted when exceptions occur. - Passing a nil value causes the default exception handler to be - reinstalled.
    +
    Address of user callback function to be executed when an exceptions + occur. Passing a nil value causes the default exception handler to be + reinstalled. The following structure is passed by value to the user's + callback function. Currently, the op field can be one of + CA_OP_GET, CA_OP_PUT, CA_OP_CREATE_CHANNEL, CA_OP_ADD_EVENT, + CA_OP_CLEAR_EVENT, or CA_OP_OTHER. + 
    struct exception_handler_args {
+    void            *usr;   /* user argument supplied when installed */
+    chanId          chid;   /* channel id (may be nill) */
+    long            type;   /* type requested */
+    long            count;  /* count requested */
+    void            *addr;  /* user's address to write results of CA_OP_GET */
+    long            stat;   /* channel access ECA_XXXX status code */
+    long            op;     /* CA_OP_GET, CA_OP_PUT, ..., CA_OP_OTHER */
+    const char      *ctx;   /* a character string containing context info */
+    sonst char      *pFile; /* source file name (may be NULL) */
+    unsigned        lineNo; /* source file line number (may be zero) */
+};
    +
    USERARG
    @@ -1927,7 +1961,8 @@ ca_add_exception_event ( ca_exception_handler , 0 );

    ECA_NORMAL - Normal successful completion

    -

    ca_replace_printf_handler ()

    +

    ca_replace_printf_handler +()

    #include <cadef.h>
 typedef int caPrintfFunc ( const char *pFromat, va_list args );
 int ca_replace_printf_handler ( caPrintfFunc *PFUNC );
    @@ -1958,17 +1993,18 @@ SEVCHK ( status, "failed to install my printf handler" );

    ECA_NORMAL - Normal successful completion

    -

    ca_replace_access_rights_event()

    +

    ca_replace_access_rights_event()

    #include <cadef.h>
 typedef void ( *pCallBack )( struct access_rights_handler_args );
-int ca_replace_access_rights_event ( chid CHAN, pCallBack PFUNC );
    +int ca_replace ( chid CHAN, pCallBack PFUNC );

    Description

    -

    Install or replace the access rights state change call back handler for -the specified channel.

    +

    Install or replace the access rights state change callback handler for the +specified channel.

    -

    The call back handler is called in the following situations.

    +

    The callback handler is called in the following situations.

    • whenever CA connects the channel immediately before the channel's connection handler is called
      • @@ -1988,7 +2024,19 @@ the specified channel.

      PFUNC
      Address of user supplied call back function. A nil pointer uninstalls - the current handler.
      + the current handler. The following arguments atre passed by + value to the supplied callback handler. + 
      typedef struct ca_access_rights {
+    unsigned    read_access:1;
+    unsigned    write_access:1;
+} caar;
+
+/* arguments passed to user access rights handlers */
+struct  access_rights_handler_args {
+    chanId  chid;   /* channel id */
+    caar    ar;     /* new access rights state */
+};
      +

      Returns