1 /*! \file syslogmessage.h 2 * \brief The syslog message API. 3 * 4 * This file describes the syslog message object. This 5 * object is also part of the liblogging API and as such 6 * a upper-layer caller may directly invoke all public 7 * methods of this object. 8 * 9 * The syslog message object (srSLMGObj) is the container 10 * wrapping the actual syslog message. It wraps any message, 11 * be it plain RFC 3164, 3195, -sign or whatever is to come. 12 * The message object contains properties used by any and all 13 * syslog protocols. The idea is to have the message object 14 * independent from the transport (which is taken care of by 15 * \ref srAPI.h). 16 * 17 * \note This object supports 8-bit syslog message. When sending, 18 * the object looks at its settings to see how non-US-ASCII 19 * messages should be processed. Idially, it uses syslog-international 20 * (which, of course, is not available at the time of this writing). 21 * 22 * \author Rainer Gerhards <rgerhards@adiscon.com> 23 * \date 2003-09-01 24 * coding begun. 25 * 26 * Copyright 2002-2014 27 * Rainer Gerhards and Adiscon GmbH. All Rights Reserved. 28 * 29 * Redistribution and use in source and binary forms, with or without 30 * modification, are permitted provided that the following conditions are 31 * met: 32 * 33 * * Redistributions of source code must retain the above copyright 34 * notice, this list of conditions and the following disclaimer. 35 * 36 * * Redistributions in binary form must reproduce the above copyright 37 * notice, this list of conditions and the following disclaimer in 38 * the documentation and/or other materials provided with the 39 * distribution. 40 * 41 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS 42 * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 43 * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A 44 * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER 45 * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 46 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 47 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 48 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 49 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 50 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 51 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 52 */ 53 #ifndef __LIB3195_SYSLOGMESSAGE_H_INCLUDED__ 54 #define __LIB3195_SYSLOGMESSAGE_H_INCLUDED__ 1 55 56 #ifdef __cplusplus 57 extern "C" { 58 #endif 59 60 #define srSLMGCHECKVALIDOBJECT_API(x) {if((x) == NULL) return SR_RET_NULL_POINTER_PROVIDED; if((x)->OID != OIDsrSLMG) return SR_RET_INVALID_HANDLE;} 61 #define srSLMGCHECKVALIDOBJECT(x) {assert((x) != NULL);assert((x)->OID == OIDsrSLMG);} 62 63 #if (FEATURE_LISTENER == 1) || (FEATURE_MSGAPI == 1) 64 65 enum srSLMGFormat_ 66 { 67 srSLMGFmt_Invalid = 0, /**< should never occur, probaly indicates leftover from calloc() 68 ** If a message is in this format, nothing but the raw message 69 ** and the facility and priority is valid 70 **/ 71 srSLMGFmt_3164RAW = 100, /**< message seems to be 3164 format, but not wellformed */ 72 srSLMGFmt_3164WELLFORMED = 101, /**< message seems to be 3164 format and is wellformed */ 73 srSLMGFmt_SIGN_12 = 200 /**< message seems to be ID sign-12 format */ 74 }; 75 typedef enum srSLMGFormat_ srSLMGFormat; 76 77 enum srSLMGTimStampType_ 78 { 79 srSLMG_TimStamp_INVALID = 0, /**< should never be used, value from calloc() */ 80 srSLMG_TimStamp_3164 = 1, 81 srSLMG_TimStamp_3339 = 2 82 }; 83 typedef enum srSLMGTimStampType_ srSLMGTimStampType; 84 85 enum srSLMGSource_ 86 { 87 srSLMG_Source_INVALID = 0, /**< should never be used, value from calloc() */ 88 srSLMG_Source_OWNGenerated = 1, 89 srSLMG_Source_BEEPRAW = 2, 90 srSLMG_Source_BEEPCOOKED = 3, 91 srSLMG_Source_UDP = 4, 92 srSLMG_Source_UX_DFLT_DOMSOCK = 5, 93 }; 94 typedef enum srSLMGSource_ srSLMGSource; 95 96 /** 97 * The syslog message object used by the listener 98 * callback and probably (later) other parts of the 99 * API). 100 */ 101 struct srSLMGObject 102 { 103 srObjID OID; /**< object ID */ 104 unsigned char *pszRawMsg; /**< the raw message provided by the sender */ 105 int bOwnRawMsgBuf; /**< TRUE pszRawMsg owned by us & must be freed on destroy */ 106 unsigned char *pszRemoteHost; /**< remote host we received the message from (from socket layer, NOT message) */ 107 int bOwnRemoteHostBuf; /**< TRUE pszRemoteHost owned by us & must be freed on destroy */ 108 srSLMGFormat iFormat; /**< the format this message (most probably) is in */ 109 srSLMGSource iSource; /**< the source this syslog message was received from */ 110 # if FEATURE_MSGAPI == 1 111 int iFacility; /**< the facility of the syslog message */ 112 int iSeverity; /**< the priority of the syslog message */ 113 unsigned char* pszHostname; /**< name of the remote host (from the syslog message itself) */ 114 unsigned char* pszTag; /**< pointer to the tag value of the syslog message */ 115 unsigned char* pszMsg; /**< the MSG part of the syslog message */ 116 int bOwnMsg; /**< TRUE pszMsg owned by us & must be freed on destroy */ 117 unsigned char* pszLanguage; /**< language used inside the message (NULL, if unknown) */ 118 119 /* The timestamp is split through several fields, because this makes it less 120 * ambigious and is (hopefully) more portable. 121 */ 122 srSLMGTimStampType iTimStampType; 123 int iTimStampYear; 124 int iTimStampMonth; 125 int iTimStampDay; 126 int iTimStampHour; 127 int iTimStampMinute; 128 int iTimStampSecond; 129 int iTimStampSecFrac; 130 int iTimStampSecFracPrecision; /**< the precision of timefrac in nmbr of digits (e.g. to differentiate ".1" from ".001" ;)) */ 131 int iTimStampOffsetHour; 132 int iTimStampOffsetMinute; 133 char cTimStampOffsetMode; /* '+'/'-' */ 134 int bTimStampIncludesTZ; /**< indicates if the message timestamp included timezone information (TRUE=yes) */ 135 char *pszTimeStamp; /**< the timestamp in string format */ 136 137 # endif 138 }; 139 typedef struct srSLMGObject srSLMGObj; 140 141 142 /** 143 * Construct a srSLMGObj. This is a utility for the lower 144 * layers. 145 * 146 * \param ppThis pointer to a pointer that will receive the 147 * address of the newly constructed object (or NULL, if an 148 * error occured). 149 */ 150 srRetVal srSLMGConstruct(srSLMGObj **ppThis); 151 152 /** 153 * Destroy an SRLSMGObj. 154 */ 155 void srSLMGDestroy(srSLMGObj *pThis); 156 157 /** 158 * Provide the caller back with the priority of this syslog message. 159 * 160 * \param piPrio Pointer to integer to receive the priority. 161 */ 162 srRetVal srSLMGGetPriority(srSLMGObj *pThis, int *piPrio); 163 164 /** 165 * Provide the caller back with the facility of this syslog message. 166 * 167 * \param piFac Pointer to integer to receive the facility. 168 */ 169 srRetVal srSLMGGetFacility(srSLMGObj *pThis, int *piFac); 170 171 /** 172 * Provide the caller back with the remote host that sent 173 * us this syslog message. Please note that this is the 174 * socket layer peer. It is not necessarily the same host 175 * that is specified as originator in the syslog message 176 * itself. If the message is relayed, these two are definitely 177 * different. 178 * 179 * \note The returned string is read-only. It is valid 180 * only until the srSLMGObj is destroyed. If the caller intends 181 * to use it for a prolonged period of time, it needs to 182 * copy it! 183 * 184 * \param ppsz Pointer to Pointer to unsigned char to 185 * receive the return string. 186 * 187 * \note If the message originated via inter-process communiction on 188 * the same machine (e.g. UNIX /dev/log), the returned 189 * pointer is NULL. The caller needs to check for this! 190 */ 191 srRetVal srSLMGGetRemoteHost(srSLMGObj *pThis, char**ppsz); 192 193 /** 194 * Provide the caller back with the message sender name 195 * from the syslog message. Please note that this is NOT 196 * necessarily the same host that physically send the 197 * message to us. See \ref srSLMGSenderName for details. 198 * 199 * \note The returned string is read-only. It is valid 200 * only until the srSLMGObj is destroyed. If the caller intends 201 * to use it for a prolonged period of time, it needs to 202 * copy it! 203 * 204 * \param ppsz Pointer to Pointer to unsigned char to 205 * receive the return string. 206 */ 207 srRetVal srSLMGGetHostname(srSLMGObj *pThis, char**ppsz); 208 209 /** 210 * Provide the caller back with the message's tag. 211 * Please note that the TAG is not necessarily available, 212 * e.g. it is not if we have a "raw" (non-wellformed) 213 * 3164 message. SR_RET_PROPERTY_NOT_AVAILABLE is 214 * returned in this case. 215 * 216 * \note The returned string is read-only. It is valid 217 * only until the srSLMGObj is destroyed. If the caller intends 218 * to use it for a prolonged period of time, it needs to 219 * copy it! 220 * 221 * \param ppsz Pointer to Pointer to unsigned char to 222 * receive the return string. 223 */ 224 srRetVal srSLMGGetTag(srSLMGObj *pThis, unsigned char**ppsz); 225 226 /** 227 * Provide the caller back with the message's MSG. 228 * Please note that the MSG is not necessarily available, 229 * e.g. it is not if we have a "raw" (non-wellformed) 230 * 3164 message. SR_RET_PROPERTY_NOT_AVAILABLE is 231 * returned in this case. Use the RawMessage in this case. 232 * 233 * \note The returned string is read-only. It is valid 234 * only until the srSLMGObj is destroyed. If the caller intends 235 * to use it for a prolonged period of time, it needs to 236 * copy it! 237 * 238 * \param ppsz Pointer to Pointer to unsigned char to 239 * receive the return string. 240 */ 241 srRetVal srSLMGGetMSG(srSLMGObj *pThis, unsigned char**ppsz); 242 243 /** 244 * Parse a syslog message into its fields. The syslog message 245 * must already be stored in pszRawMesg. All other parts 246 * will be extracted and brought to their own buffers. 247 */ 248 srRetVal srSLMGParseMesg(srSLMGObj *pThis); 249 250 /** 251 * Provide the caller back with the raw message. 252 * 253 * This is especially useful for syslog-sign, where the 254 * raw message must be stored in order to keep the sig 255 * intact! 256 * 257 * \note The returned string is read-only. It is valid 258 * only until the srSLMGObj is destroyed. If the caller intends 259 * to use it for a prolonged period of time, it needs to 260 * copy it! 261 * 262 * \param ppsz Pointer to Pointer to unsigned char to 263 * receive the return string. 264 */ 265 srRetVal srSLMGGetRawMSG(srSLMGObj *pThis, unsigned char**ppsz); 266 267 /** 268 * Set the Remote Host address, in this case to an IP address. 269 * Any previously set value is replaced. 270 * 271 * \param pszRemHostIP String pointing to the IP address of the remote 272 * host. 273 * \param bCopyRemHost TRUE = copy the string, will own the copy 274 * (and need to free it), FALSE, do not copy 275 * caller owns & frees string. Must keep srSLMGObj 276 * alive long enough so that all methods can access 277 * it without danger. 278 */ 279 srRetVal srSLMGSetRemoteHostIP(srSLMGObj *pThis, char *pszRemHostIP, int bCopyRemHost); 280 281 /** 282 * Set the raw message text. Any previously set value is replaced. 283 * 284 * \param pszRawMsg String with the raw message text. 285 * \param bCopyRawMsg TRUE = copy the string, will own the copy 286 * (and need to free it), FALSE, do not copy 287 * caller owns & frees string. Must keep srSLMGObj 288 * alive long enough so that all methods can access 289 * it without danger. 290 */ 291 srRetVal srSLMGSetRawMsg(srSLMGObj *pThis, char *pszRawMsg, int bCopyRawMsg); 292 293 /** 294 * Set the MSG text. Any previously set value is replaced. 295 * 296 * \param pszMsg String with the MSG text. 297 * \param bCopyMSG TRUE = copy the string, will own the copy 298 * (and need to free it), FALSE, do not copy 299 * caller owns & frees string. Must keep srSLMGObj 300 * alive long enough so that all methods can access 301 * it without danger. 302 */ 303 srRetVal srSLMGSetMSG(srSLMGObj *pThis, char *pszMSG, int bCopyMSG); 304 305 /** 306 * Set the TIMESTAMP to the current system time. 307 */ 308 srRetVal srSLMGSetTIMESTAMPtoCurrent(srSLMGObj *pThis); 309 310 /** 311 * Set the HOSTNAME to the current hostname. 312 */ 313 srRetVal srSLMGSetHOSTNAMEtoCurrent(srSLMGObj* pThis); 314 315 /** 316 * Format a raw syslog message. This object's properties are 317 * used to format the message. It will be placed in the raw 318 * message buffer and after that is ready for transmittal. 319 * 320 * If a raw message is already stored, the new raw message 321 * overwrites the previous one. If the previous message resides 322 * in user-allocated memory, it can not be replaced and an 323 * error condition is returned. In this case, remove the link 324 * to the user-supplied buffer first and then retry the operation. 325 * 326 * \param IFmtToUse The format to be used for this message. It 327 * must be one of the well-known formats. 328 */ 329 srRetVal srSLMGFormatRawMsg(srSLMGObj *pThis, srSLMGFormat iFmtToUse); 330 331 /** 332 * Set the priority for the current message. Any 333 * previously stored priority code is overwritten. 334 */ 335 srRetVal srSLMGSetSeverity(srSLMGObj* pThis, int iNewVal); 336 337 /** 338 * Set the facility for the current message. Any 339 * previously stored facility code is overwritten. 340 */ 341 srRetVal srSLMGSetFacility(srSLMGObj* pThis, int iNewVal); 342 343 /** 344 * Set the TAG string in the syslog message. The 345 * caller provided string buffer is copied to our 346 * own local copy. 347 * 348 * \param pszNewTag New tag value (string). MUST 349 * not be NULL. MUST be a valid tag. 350 */ 351 srRetVal srSLMGSetTAG(srSLMGObj* pThis, char* pszNewTag); 352 353 354 #endif /* #if (FEATURE_LISTENER == 1) || (FEATURE_MSGAPI == 1) */ 355 356 #ifdef __cplusplus 357 }; 358 #endif 359 360 #endif 361