1 /*! \file srAPI.h 2 * \brief The syslog reliable API. 3 * 4 * This is the transport part of the API. Please be sure 5 * to also look at \ref syslogmessage.h for the API 6 * on the syslog message itself. 7 * 8 * \author Rainer Gerhards <rgerhards@adiscon.com> 9 * \date 2003-08-04 10 * 0.1 version created. 11 * \date 2003-10-02 12 * Added a number of library options so that the different 13 * listeners can be flexibly configured. 14 * 15 * Copyright 2002-2014 16 * Rainer Gerhards and Adiscon GmbH. All Rights Reserved. 17 * 18 * Redistribution and use in source and binary forms, with or without 19 * modification, are permitted provided that the following conditions are 20 * met: 21 * 22 * * Redistributions of source code must retain the above copyright 23 * notice, this list of conditions and the following disclaimer. 24 * 25 * * Redistributions in binary form must reproduce the above copyright 26 * notice, this list of conditions and the following disclaimer in 27 * the documentation and/or other materials provided with the 28 * distribution. 29 * 30 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS 31 * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 32 * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A 33 * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER 34 * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 35 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 36 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 37 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 38 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 39 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 40 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 41 */ 42 #ifndef __LIB3195_SRAPI_H_INCLUDED__ 43 #define __LIB3195_SRAPI_H_INCLUDED__ 1 44 45 #ifdef __cplusplus 46 extern "C" { 47 #endif 48 49 #define srAPICHECKVALIDOBJECT(x) {assert(x != NULL); assert(x->OID == OIDsrAPI);} 50 struct srSLMGObject; 51 52 struct srAPIObject 53 /** The syslog-reliable API object. Implemented via \ref srAPI.h and 54 * \ref srAPI.c. 55 */ 56 { 57 srObjID OID; /**< object ID */ 58 struct sbChanObject *pChan; /**< The BEEP channel associated with this API instance */ 59 struct sbNVTRObject *pProfsSupported;/**< the supported profiles by this API (initiator only) */ 60 struct sbSessObject *pSess; /**< the associated session */ 61 void *pUsr; /**< for the user's use - not handled in any way in this lib */ 62 /** \todo create the methods for pUsr */ 63 srOPTION3195Profiles iUse3195Profiles; /**< specifies which profiles to use for 3195 */ 64 # if FEATURE_LISTENER == 1 65 int bListenBEEP; /**< TRUE/FALSE - listen to udp? */ 66 int iBEEPListenPort; /**< port to use when listening on BEEP */ 67 void (*OnSyslogMessageRcvd)(struct srAPIObject* pAPI, struct srSLMGObject *pSyslogMesg); 68 struct sbLstnObject *pLstn; /**< pointer to associated listener object */ 69 int bListenUDP; /**< TRUE/FALSE - listen to udp? */ 70 int iUDPListenPort; /**< port to use when listening on UDP */ 71 int bListenUXDOMSOCK; /**< TRUE/FALSE - listen to unix domain socket? */ 72 char *szNameUXDOMSOCK; /**< pointer to c-string with socket name */ 73 # endif 74 }; 75 typedef struct srAPIObject srAPIObj; 76 77 /** 78 * Initialize the liblogging library. This method must be called 79 * before any other method. 80 * 81 * \retval Pointer to an API object (aka "handle") or NULL 82 * if an error occured. 83 */ 84 srAPIObj* srAPIInitLib(void); 85 86 /** Open a log session. 87 * 88 * \param pszRemotePeer [in] The Peer to connect to. 89 * \param iPort [in] The port the remote Peer is listening to. 90 * \retval Pointer to an API object (aka "handle") or NULL 91 * if an error occured. 92 */ 93 srRetVal srAPIOpenlog(srAPIObj *pThis, char* pszRemotePeer, int iPort); 94 95 96 /** 97 * Close a syslog raw session. 98 * In the method, we have a slightly different error handling. We do 99 * NOT return immediately when something goes wrong but rather preserve 100 * the error state and try to continue processing. The reasoning 101 * behind this is that we can potentially create an even larger 102 * memory leak if we do not try to continue. After all, we are 103 * here to free things and shutdown the process. The only exception 104 * is when we detect that the caller-provided handle is invalid. 105 * In this case, we CAN NOT continue processing. 106 * 107 * When this method returns, the the caller-supplied pointer 108 * to the API object is NO LONGER VALID and can not be used 109 * for consequtive calls. 110 */ 111 srRetVal srAPICloseLog(srAPIObj *pThis); 112 113 /** 114 * Exit the liblogging library. This method should be called after 115 * a higher layer is COMPLETE DONE with liblogging. It does not 116 * need to be called after each session close. 117 * 118 * if srAPIExitLib() is called, the lib can not be used 119 * until srAPIInitLib() is called again. 120 * 121 * The provided pointer to the API object is invalid 122 * once this method returns. 123 */ 124 srRetVal srAPIExitLib(srAPIObj *pThis); 125 126 127 128 /** 129 * Send a log message to the remote peer. The log message must 130 * already be correctly formatted according to RFC 3195. No 131 * further formatting (or checks) are applied. 132 * 133 * \param pThis [in] pointer to a proper srAPI object. 134 * \param szLogmsg [in] message to be sent. 135 */ 136 srRetVal srAPISendLogmsg(srAPIObj* pThis, char* szLogmsg); 137 138 /** 139 * Send a syslog message object to the remote peer. This 140 * method SHOULD be called whenever the caller is already 141 * in possesion of a srSLMGObj. Calling srAPISendLogmsg would 142 * result in a performance penalty in those cases. In general, 143 * you should call this method here whenever you can and use 144 * srAPISendLogmsg only in those (rare) cases where you 145 * can not avoid it. 146 * 147 * \param pThis [in] pointer to a proper srAPI object. 148 * \param pSLMG pointer to the syslog message object. This 149 * must be a proper object as it will be 150 * used as the message source. 151 */ 152 srRetVal srAPISendSLMG(srAPIObj* pThis, struct srSLMGObject* pSLMG); 153 154 /** 155 * Close a syslog raw session. 156 * In the method, we have a slightly different error handling. We do 157 * NOT return immediately when something goes wrong but rather preserve 158 * the error state and try to continue processing. The reasoning 159 * behind this is that we can potentially create an even larger 160 * memory leak if we do not try to continue. After all, we are 161 * here to free things and shutdown the process. The only exception 162 * is when we detect that the caller-provided handle is invalid. 163 * In this case, we CAN NOT continue processing. 164 * 165 * When this method returns, the the caller-supplied pointer 166 * to the API object is NO LONGER VALID and can not be used 167 * for consequtive calls. 168 */ 169 srRetVal srAPICloseLog(srAPIObj *pThis); 170 171 172 /** 173 * Set an library option. Library options provide a 174 * way to modify library behaviour. For example, 175 * once rfc3195 raw and cooked are implemented, you can 176 * set an option to set which transport you would like 177 * to have. Consequently, it currently looks like 178 * the calling sequence is probably always: 179 * 180 * 1. srAPIInitLib 181 * 2. srAPISetOption 182 * 3. srAPIOpenlog 183 * 4. srAPISendLogmsg 184 * 5. srAPICloselog 185 * 6. srAPIExitLib 186 * 187 * \param pThis pointer to the API, as usual. The unusual 188 * things is that in this case it may be NULL. If so, 189 * global settings will be modified on a per-library 190 * basis. 191 * \param iOpt option to set 192 * \param iOptVal value that the option is to be set to. 193 * The option value is totally dependent on the 194 * respective option. 195 */ 196 srRetVal srAPISetOption(srAPIObj* pThis, SRoption iOpt, int iOptVal); 197 /* And the same method for string options... */ 198 srRetVal srAPISetStringOption(srAPIObj* pThis, SRoption iOpt, char *pszOptVal); 199 200 /** 201 * Run the listener process. Control is only returned if 202 * - a fatal error inside the listener happens 203 * - srAPIShutdownListener() has been called 204 * 205 * As control does not return, please note that srAPIShutdownListener() 206 * must be called either from another thread or a signal handler. 207 */ 208 srRetVal srAPIRunListener(srAPIObj *pThis); 209 210 /** 211 * Shut down the currently running listener. It 212 * may take some time to shutdown the listener depending 213 * on its current state. The caller should expect a delay of 214 * up to 30 seconds. 215 */ 216 srRetVal srAPIShutdownListener(srAPIObj *pThis); 217 218 /** 219 * Set the user pointer. Whatever value the user 220 * passes in is accepted and stored. No validation 221 * is done (and can be done). Any previously stored 222 * information is overwritten. 223 */ 224 srRetVal srAPISetUsrPointer(srAPIObj *pAPI, void* pUsr); 225 226 /** 227 * Return the user pointer. Returns whatever is stored 228 * in pUsr. 229 * 230 * \param ppToStore Pointer to a pointer that will receive 231 * the user pointer. 232 */ 233 srRetVal srAPIGetUsrPointer(srAPIObj *pAPI, void **ppToStore); 234 235 /** 236 * Setup the listener for this API object. The listener is 237 * initialized but not running. Only a single listener can 238 * be active for a single API object. 239 * 240 * \param NewHandler Pointer to a function with C calling conventions 241 * the will receive the syslog message object as soon as it arrives. 242 * This may be NULL. In this case, however, no meaningful work is done. 243 * Syslog messages arrive but will be discarded because there is 244 * no upper-layer peer. 245 */ 246 srRetVal srAPISetupListener(srAPIObj* pThis, void(*NewHandler)(srAPIObj*, struct srSLMGObject*)); 247 248 /** 249 * Set a handler to be called when a syslog message 250 * arrives. If this method is called when there already a new handler 251 * is set, the previous one is discarded. There can only be a single 252 * handler set at a single time. 253 * 254 * \param NewHandler Pointer to a function with C calling conventions 255 * the will receive the syslog message object as soon as it arrives. 256 * This may be NULL. In this case, however, no meaningful work is done. 257 * Syslog messages arrive but will be discarded because there is 258 * no upper-layer peer. 259 */ 260 srRetVal srAPISetMsgRcvCallback(srAPIObj* pThis, void(*NewHandler)(srAPIObj*, struct srSLMGObject*)); 261 262 /** 263 * Shut down the currently running listener. It 264 * may take some time to shutdown the listener depending 265 * on its current state. The caller should expect a delay of 266 * up to 30 seconds. 267 */ 268 srRetVal srAPIShutdownListener(srAPIObj *pThis); 269 270 271 #ifdef __cplusplus 272 }; 273 #endif 274 275 #endif 276