liblogging: srAPI.h File Reference

Main Page | Compound List | File List | Compound Members | File Members | Related Pages

# srAPI.h File Reference

The syslog reliable API. More...

Go to the source code of this file.

## Compounds
struct | srAPIObject
| The syslog-reliable API object. More...
## Defines
#define | __LIB3195_SRAPI_H_INCLUDED__ 1
#define | srAPICHECKVALIDOBJECT(x) {assert(x != NULL); assert(x->OID == OIDsrAPI);}
## Typedefs
typedef srAPIObject | srAPIObj
## Functions
srAPIObj * | srAPIInitLib (void)
| Initialize the liblogging library.
srRetVal | srAPIOpenlog (srAPIObj *pThis, char *pszRemotePeer, int iPort)
| Open a log session.
srRetVal | srAPICloseLog (srAPIObj *pThis)
| Close a syslog raw session.
srRetVal | srAPIExitLib (srAPIObj *pThis)
| Exit the liblogging library.
srRetVal | srAPISendLogmsg (srAPIObj *pThis, char *szLogmsg)
| Send a log message to the remote peer.
srRetVal | srAPISendSLMG (srAPIObj *pThis, struct srSLMGObject *pSLMG)
| Send a syslog message object to the remote peer.
srRetVal | srAPISetOption (srAPIObj *pThis, SRoption iOpt, int iOptVal)
| Set an library option.
srRetVal | srAPISetStringOption (srAPIObj *pThis, SRoption iOpt, char *pszOptVal)
srRetVal | srAPIRunListener (srAPIObj *pThis)
| Run the listener process.
srRetVal | srAPIShutdownListener (srAPIObj *pThis)
| Shut down the currently running listener.
srRetVal | srAPISetUsrPointer (srAPIObj *pAPI, void *pUsr)
| Set the user pointer.
srRetVal | srAPIGetUsrPointer (srAPIObj *pAPI, void **ppToStore)
| Return the user pointer.
srRetVal | srAPISetupListener (srAPIObj *pThis, void(*NewHandler)(srAPIObj *, struct srSLMGObject *))
| Setup the listener for this API object.
srRetVal | srAPISetMsgRcvCallback (srAPIObj *pThis, void(*NewHandler)(srAPIObj *, struct srSLMGObject *))
| Set a handler to be called when a syslog message arrives.

## Detailed Description

The syslog reliable API.

This is the transport part of the API. Please be sure to also look at syslogmessage::h for the API on the syslog message itself.

Author:
  Rainer Gerhards <rgerhards@adiscon.com>

Date:
  2003-08-04 0.1 version created.

  2003-10-02 Added a number of library options so that the different listeners can be flexibly configured.

Copyright 2002-2003 Rainer Gerhards and Adiscon GmbH. All Rights Reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

* Neither the name of Adiscon GmbH or Rainer Gerhards nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

## Function Documentation

srRetVal srAPICloseLog | ( | srAPIObj * | pThis | ) |

| Close a syslog raw session. In the method, we have a slightly different error handling. We do NOT return immediately when something goes wrong but rather preserve the error state and try to continue processing. The reasoning behind this is that we can potentially create an even larger memory leak if we do not try to continue. After all, we are here to free things and shutdown the process. The only exception is when we detect that the caller-provided handle is invalid. In this case, we CAN NOT continue processing. When this method returns, the the caller-supplied pointer to the API object is NO LONGER VALID and can not be used for consequtive calls.

srRetVal srAPIExitLib | ( | srAPIObj * | pThis | ) |

| Exit the liblogging library. This method should be called after a higher layer is COMPLETE DONE with liblogging. It does not need to be called after each session close. if srAPIExitLib() is called, the lib can not be used until srAPIInitLib() is called again. The provided pointer to the API object is invalid once this method returns.

srRetVal srAPIGetUsrPointer | ( | srAPIObj * | pAPI,
|  | void ** | ppToStore
| ) |

  | Return the user pointer. Returns whatever is stored in pUsr. Parameters:
  ppToStore | Pointer to a pointer that will receive the user pointer.

srAPIObj* srAPIInitLib | ( | void |  | ) |

  | Initialize the liblogging library. This method must be called before any other method. Return values:
  Pointer | to an API object (aka "handle") or NULL if an error occured.

srRetVal srAPIOpenlog | ( | srAPIObj * | pThis,
|  | char * | pszRemotePeer,
|  | int | iPort
| ) |

  | Open a log session. This API is effectively the initiator side of the RAW profile. This method looks like much code, but most of it is error handling ;) - so we keep it as a single long method. Parameters:
  pszRemotePeer | [in] The Peer to connect to.
  iPort | [in] The port the remote Peer is listening to.
Todo: later, make this depending on the lib option set by the user.

srRetVal srAPIRunListener | ( | srAPIObj * | pThis | ) |

| Run the listener process. Control is only returned if a fatal error inside the listener happens srAPIShutdownListener() has been called As control does not return, please note that srAPIShutdownListener() must be called either from another thread or a signal handler.

srRetVal srAPISendLogmsg | ( | srAPIObj * | pThis,
|  | char * | szLogmsg
| ) |

  | Send a log message to the remote peer. The log message must already be correctly formatted according to RFC 3195. No further formatting (or checks) are applied. Parameters:
  pThis | [in] pointer to a proper srAPI object.
  szLogmsg | [in] message to be sent.

srRetVal srAPISendSLMG | ( | srAPIObj * | pThis,
|  | struct srSLMGObject * | pSLMG
| ) |

  | Send a syslog message object to the remote peer. This method SHOULD be called whenever the caller is already in possesion of a srSLMGObj. Calling srAPISendLogmsg would result in a performance penalty in those cases. In general, you should call this method here whenever you can and use srAPISendLogmsg only in those (rare) cases where you can not avoid it. Parameters:
  pThis | [in] pointer to a proper srAPI object.
  pSLMG | pointer to the syslog message object. This must be a proper object as it will be used as the message source.

srRetVal srAPISetMsgRcvCallback | ( | srAPIObj * | pThis,
|  | void(* | NewHandler)(srAPIObj *, struct srSLMGObject *)
| ) |

  | Set a handler to be called when a syslog message arrives. If this method is called when there already a new handler is set, the previous one is discarded. There can only be a single handler set at a single time. Parameters:
  NewHandler | Pointer to a function with C calling conventions the will receive the syslog message object as soon as it arrives. This may be NULL. In this case, however, no meaningful work is done. Syslog messages arrive but will be discarded because there is no upper-layer peer.

srRetVal srAPISetOption | ( | srAPIObj * | pThis,
|  | SRoption | iOpt,
|  | int | iOptVal
| ) |

  | Set an library option. Library options provide a way to modify library behaviour. For example, once rfc3195 raw and cooked are implemented, you can set an option to set which transport you would like to have. Consequently, it currently looks like the calling sequence is probably always: 1. srAPIInitLib 2. srAPISetOption 3. srAPIOpenlog 4. srAPISendLogmsg 5. srAPICloselog 6. srAPIExitLib Parameters:
  pThis | pointer to the API, as usual. The unusual things is that in this case it may be NULL. If so, global settings will be modified on a per-library basis.
  iOpt | option to set
  iOptVal | value that the option is to be set to. The option value is totally dependent on the respective option.

srRetVal srAPISetupListener | ( | srAPIObj * | pThis,
|  | void(* | NewHandler)(srAPIObj *, struct srSLMGObject *)
| ) |

  | Setup the listener for this API object. The listener is initialized but not running. Only a single listener can be active for a single API object. Parameters:
  NewHandler | Pointer to a function with C calling conventions the will receive the syslog message object as soon as it arrives. This may be NULL. In this case, however, no meaningful work is done. Syslog messages arrive but will be discarded because there is no upper-layer peer.

srRetVal srAPISetUsrPointer | ( | srAPIObj * | pAPI,
|  | void * | pUsr
| ) |

| Set the user pointer. Whatever value the user passes in is accepted and stored. No validation is done (and can be done). Any previously stored information is overwritten.

srRetVal srAPIShutdownListener | ( | srAPIObj * | pThis | ) |

| Shut down the currently running listener. It may take some time to shutdown the listener depending on its current state. The caller should expect a delay of up to 30 seconds.