NAME    [Toc]    [Back]

       EvmConnSubscribe,    EvmConnRegistrationGet,   EvmConnTemplateScan
 - Establishes a subscription for event notification

SYNOPSIS    [Toc]    [Back]

       #include <evm/evm.h>

       EvmStatus_t EvmConnSubscribe(
               EvmConnection_t connection,
               void *unused,
               EvmString_t  filter_string  ); EvmStatus_t EvmConnRegistrationGet(

               EvmConnection_t connection,
               const EvmString_t event_class,
               EvmPointer_t user_arg );  EvmStatus_t  EvmConnTemplateScan(

               EvmConnection_t connection,
               const EvmString_t filter_string,
               EvmPointer_t user_arg );

OPERANDS    [Toc]    [Back]

       The  connection  established to listen for events. See the
       EvmConnCreate(3) reference page.  This parameter  must  be
       specified  as  NULL.   A  string  specifying the events of
       interest. For a formal description of the  syntax  of  the
       filter_string,  see  the  EvmFilter(5) reference page.  An
       event name string having at least one component. An  event
       class  cannot contain wildcard characters.  The value supplied
 in this parameter is returned in the callback  function's
 extended callback structure, and can be used by the
       calling code to match the callback  with  the  originating
       request.

DESCRIPTION    [Toc]    [Back]

       To  receive  notification of events as they happen, a program
 must establish a listening connection to the EVM daemon,
  using the EvmConnCreate(3) routine. The program must
       then call EvmConnSubscribe() to associate  a  filter  with
       the  connection.  Whenever  the  daemon  receives an event
       matching the filter, it delivers the  event  to  the  subscriber.
  The subscriber must handle incoming events using
       the API routines described in the EvmConnWait(3) reference
       page.

       The  EvmConnSubscribe()  routine  passes the supplied filter_string
 to the EVM daemon, to select a  set  of  events
       for  subscription. The routine returns immediately if preliminary
 validation fails; otherwise it passes the request
       to  the daemon, and the daemon's response will be returned
       through the connection's callback function, with a  reason
       code  of  EvmREASON_SUBSCRIBE_COMPLETE.  The  caller  must
       watch for  the  response  using  EvmConnWait()  (3)  or  a
       related function, and then invoke EvmConnDispatch() (3) to
       handle it.

       The EvmConnRegistrationGet() routine asks  the  daemon  to
       return  the  event  template corresponding to the supplied
       event_class,  if  the  event  is  registered.  The  daemon
       responds  by  returning the event template, in the form of
       an EVM event, through the connection's callback  function,
       with a reason code of EvmREASON_TEMPLATE_INFO_DELIVERED.

       If  the  event class is registered, the event field in the
       extended callback data structure  holds  an  event  corresponding
  to the template, which the caller must handle as
       if it were an incoming event. If the event  class  is  not
       registered,  the  callback  status  code  is set to EvmERROR_NOT_PRESENT,
 and the event handle in the structure  is
       set to NULL.

       The  EvmConnTemplateScan()  routine  asks  the  daemon  to
       return a series of event templates that match the supplied
       filter_string. The daemon responds by returning event templates,
 in the form of EVM  events,  through  the  connection's
  callback  function,  with a reason code of EvmREASON_TEMPLATE_INFO_DELIVERED.


       The first time the function is called a single event  template
  is  returned,  if  one  is available. On subsequent
       calls that have the filter_string parameter set  to  NULL,
       the  next  matching  template  is returned, until all templates
 that match the  original  filter_string  have  been
       returned.

       If  it is necessary to match individual callback responses
       with their original requests, the caller should  supply  a
       different user_arg for each request in the cycle, and verify
 that each incoming template relates  to  the  expected
       request.

NOTES    [Toc]    [Back]

       The  daemon  does  not return templates for which the user
       does not have access authorization.

       To avoid missing incoming templates you should not issue a
       stream  of  EvmConnRegistrationGet()  or EvmConnTemplateScan()
 requests before taking any callbacks, but work in  a
       request/callback/request cycle.

RETURN VALUES    [Toc]    [Back]

       The  operation  was  completed  without error.  One of the
       arguments to the function  was  invalid.   A  value  in  a
       structure  member is invalid.  An operation failed because
       an attempt to acquire heap memory failed.  For the EvmConnRegistrationGet()
 routine the requested event template is
       not registered.

              For the EvmConnTemplateScan() routine, there is  no
              match  for the specified filter_string, or the template
 list is exhausted.   A  read  error  occurred
              while  reading  from  the EVM daemon connection.  A
              write error occurred while writing to the EVM  daemon
 connection.

ERRORS    [Toc]    [Back]

       None

LIBRARY    [Toc]    [Back]

       EVM Support Library (libevm.so, libevm.a)

FILES    [Toc]    [Back]

       None

SEE ALSO    [Toc]    [Back]

       Routines:   EvmConnCreate(3),  EvmConnDestroy(3),  EvmConnWait(3), EvmStatusTextGet(3)

       Files: evm.auth(4), kevm(7)

       Event Management: EVM(5)

       Event Callback: EvmCallback(5)

       Event Connection: EvmConnection(5)

       Event Filter: EvmFilter(5)



                                              EvmConnSubscribe(3)