libram Files

libram(3)                      libram Reference                      libram(3)



NAME
       libram - remote analysis and modification library


SYNOPSIS
       #include <libram.h>


DESCRIPTION
       libram  is a library for remote analysis and modification.  libram does
       not contain any real analysis or filter components.   But  instead,  it
       offers  an  extendable module interface where analysis and modification
       modules can be added. These modules are  called  backend  modules.  The
       modules  need to be loaded befor they are used. Loading modules is per-
       formed with libram_load(3).

       The interface allows both local and remote modules. Local  modules  can
       be implemented with shared libraries, that run within the process space
       of the calling process. Remote modules can  run  on  separate  machines
       using remote procedure calls.

       To  avoid  network latencies in remote modules, libram is using a asyn-
       chronous mode by default. That means that libram can do  libram  calls,
       but  does not have to wait for the result. Instead it can continue with
       useful work and collect the results later.

       Local modules does not suffer network latency. Thus it is possible  for
       them  to  return the analysis result immediate. To allow a uniform pro-
       gramming api for both synchronous and asynchronous modules.   libram(3)
       contains a wrapper that makes synchronous modules behave asynchronous.

       The  libram  client  can  negotiate  the  use  of synchronous mode with
       libram_init(3). If the libram client sets the  flag  LIBRAM_SYNCHRONOUS
       in  libram_init,  it requests synchronous mode. If the backend does not
       support synchrnous mode, it clears this flag.  The libram client has to
       check  this  flag  after the call to libram_init(3) before switching to
       synchronous mode.

       If the client wants to use asynchronous  mode,  the  LIBRAM_SYNCHRONOUS
       should  not  be  set.  The backend can still set the LIBRAM_SYNCHRONOUS
       flag, but the client does not need to honor this flag, since libram  is
       able  to  offer  the asynchronous api to asynchronous backends. This is
       the wrapper that is mentioned above.

       See libram-synchronous(3) for a description of  synchronous  api  calls
       and libram-asynchronous(3) for a description of asynchronous api calls.

       libram  offers  two different interfaces. The first interface makes use
       of structures defined in <libram-xdr.h>. This file  is  generated  from
       the  xdr  representation  of  the  communication protocol, and needs to
       include <rpc/rpc.h>.

       The functions uses in this interface are:

       libram_open(3)
              open connection

       libram_data(3)
              handle data on connection

       libram_close(3)
              close connection


       To use this interface, inclusion of <libram-xdr.h> is necessary.

       To avoid possible name conflicts with symbols defined  in  <rpc/rpc.h>.
       libram  offers  an  alternative interface. The difference between these
       interfaces is, that the normal libram interface passed data  in  struc-
       tures,   that   are   defined   in  <libram-xdr.h>,  and  thus  require
       <rpc/rpc.h>.

       The second libram interface does not include  <libram-xdr.h>  and  does
       not use the structures defined in <libram-xdr.h>, but splits the struc-
       tures into components. The network related components are replaced with
       struct  sockaddr  * parameters.  The data related parameters are passed
       in separate arguments.

       The functions used in this second interface are:

       libram_sopen(3)
              open connection

       libram_sdata(3)
              handle data on connection

       libram_sclose(3)
              close connection The s stands for sockaddr or second interface.


       Both interfaces use the libram_process(3) function to get the result in
       asynchronous mode.

       The  return  value for libram_open(3), libram_data(3), libram_close(3),
       libram_sopen(3), libram_sdata(3),  libram_sclose(3)  and  the  function
       libram_process(3)  for  asynchronous  request is a reply structure, see
       reply(3) for details. The reply structure is defined in <libram-xdr.h>.
       The functions can return special reply values to indicate errors:

       LIBRAM_REPLY_UNAVAILABLE
              The result is not yet available, either because the asynchronous
              request is still pending, or the LIBRAM_DISCARD_RESULT  flag  is
              set.   If  the LIBRAM_DISCARD_RESULT flag is not set, the client
              uses libram_process - (3) to request the result later.

       LIBRAM_REPLY_FAILURE
              There was an error condition that could  not  be  solved.  Error
              conditions are either memory errors, or the connection to exter-
              nal modules were interrupted.  The result will not be  available
              later,  so  the client must not use libram_process - (3) to wait
              for the result of the current request.

              To access the contents of the reply structure without  including
              <libram-xdr.h> one can use the access function:

       libram_reply_get_action(3)
              get action type

       libram_reply_get_id(3)
              get id

       libram_reply_get_processed(3)
              get processed bytes

       libram_reply_get_replace_direction(3)
              get replace_direction

       libram_reply_get_replace_len(3)
              get replace_len

       libram_reply_get_replace_val(3)
              get replace_val


       libram(3) also offers a simple callback managment framework that insert
       callbacks for pending replies on a callback list. The callback list  is
       initialized  with  libram_cb_init(3)  and freed with libram_cb_exit(3).
       libram_cb_register(3) is used to add  callbacks  to  this  list,  while
       libram_cb_dispatch(3) activates the callbacks when a response is avail-
       able. See libram-cb(3) for further details.


SEE ALSO
       libram-install(3),  libram_flags(3),  libram_load(3),   libram_init(3),
       libram_exit(3),    libram_open(3),   libram_data(3),   libram_close(3),
       libram_sopen(3),           libram_sdata(3),           libram_sclose(3),
       libram_reply_get_action(3),                     libram_reply_get_id(3),
       libram_reply_get_processed(3),   libram_reply_get_replace_direction(3),
       libram_reply_get_replace_len(3),       libram_reply_get_replace_val(3),
       libram-synchronous(3), libram-asynchronous(3), libram-cb(3), reply(3)



libram                           Sep 18, 2013                        libram(3)