1 /*! \file liblogging.h 2 * \brief global objects and defines 3 * 4 * Include this header in your application! 5 * 6 * \author Rainer Gerhards <rgerhards@adiscon.com> 7 * \date 2003-08-04 8 * 0.1 version created. 9 * 10 * Copyright 2002-2014 11 * Rainer Gerhards and Adiscon GmbH. All Rights Reserved. 12 * 13 * Redistribution and use in source and binary forms, with or without 14 * modification, are permitted provided that the following conditions are 15 * met: 16 * 17 * * Redistributions of source code must retain the above copyright 18 * notice, this list of conditions and the following disclaimer. 19 * 20 * * Redistributions in binary form must reproduce the above copyright 21 * notice, this list of conditions and the following disclaimer in 22 * the documentation and/or other materials provided with the 23 * distribution. 24 * 25 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS 26 * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27 * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A 28 * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER 29 * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 30 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 31 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 32 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 33 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 34 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 35 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 36 */ 37 #ifndef __LIB3195_LIBLOGGING_H_INCLUDED__ 38 #define __LIB3195_LIBLOGGING_H_INCLUDED__ 1 39 #include <stdio.h> /* debug only */ 40 41 #include "settings.h" 42 #ifdef __cplusplus 43 extern "C" { 44 #endif 45 46 /** Version of this library. Just a plain integer, incremented each time there 47 * is notable change in the API or functionality. 48 * 49 * NOTE: we leave this at the level of the last revison of liblogging-rfc3195. 50 * This is to be incremented only when the interface really changes. 51 * 52 * In general, these macros are deprecated, but given the state of 53 * liblogging-rfc3195, where no future development is expected, we do 54 * not try to break the interface just to clean up things. 55 */ 56 #define LIBLOGGING_VERSION_MAJOR 0 57 #define LIBLOGGING_VERSION_MINOR 6 58 #define LIBLOGGING_VERSION_SUBMINOR 0 59 60 61 enum srRetVal_ /** return value. All methods return this if not specified otherwise */ 62 { 63 SR_RET_ERR = -1, /**< error occured, call error handler for details */ 64 SR_RET_REMAIN_WIN_TOO_SMALL = -2, /**< can't send, because not enough octets left in RFC3081 window --> wait for SEQ */ 65 SR_RET_INVALID_HANDLE = -3, /**< caller provided an invalid handle, e.g. NULL pointer or pointer to wrong object. 66 * This is only checked on the API layer. Internally, all functions check this via 67 * assert(), so protection is only available during debugging. This is a performance 68 * decision. 69 */ 70 SR_RET_INVALID_DESTRUCTOR = -4, /**< used, when the caller must provide a pointer to a destructor function but does not */ 71 SR_RET_NOT_FOUND = - 5, /**< a requested element was not found. May not be an error depending on what operation was 72 ** to be carried out... */ 73 SR_RET_OUT_OF_MEMORY = -6, /**< memory allocation failed */ 74 SR_RET_XML_INVALID_PARAMTAG = -7, /**< malformed tag parameter, most probably quotes are missing before value or intervening space */ 75 SR_RET_XML_INVALID_TERMINATOR = -8, /**< missing terminator sequence, e.g. a "param='no_terminator" - notice the missing closing quote */ 76 SR_RET_XML_MALFORMED = -9, /**< the XML is malformed (no specific reason given) */ 77 SR_RET_MISSING_CLOSE_BRACE = -10, /**< closing brace in <tag /> missing */ 78 SR_RET_XML_MISSING_CLOSETAG = -11, /**< close tag is missing or syntax invalid <tag>...</closetag> */ 79 SR_RET_XML_MISSING_OPENTAG = -12, /**< open tag is missing, e.g <tag />othertag> */ 80 SR_RET_XML_TAG_MISMATCH = -13, /**< start and close tag name do not match (<tag>...</othertag>) */ 81 SR_RET_XML_INVALID_CDATA_HDR = -14, /**< invalid start of CDATA, e.g. <![CDTA... */ 82 SR_RET_XML_INVALID_CDATA_TRAIL = -14, /**< invalid CDATA trailer, , e.g. "<![CDATA[test]>" (one ] missing) */ 83 SR_RET_PEER_NONOK_RESPONSE = -15, /**< was waiting for a BEEP peer to respond "ok", but received other response */ 84 SR_RET_PEER_INVALID_PROFILE = -16, /**< BEEP Peer did either not support the profile or did not return the correct on in response to a start message */ 85 SR_RET_PEER_NO_URI = -17, /**< BEEP peer did not inclulde a mandatory URI element in its xml response */ 86 SR_RET_PEER_NO_PROFILE = -18,/**< BEEP peer did not include a mandatory PROFILE element in its XML reponse */ 87 SR_RET_PEER_NO_GREETING = -19, /**< BEEP peer did not send a (correctly formatted) greeting message */ 88 SR_RET_PEER_DOESNT_SUPPORT_PROFILE = -20, /**< the reqeusted profile is not part of the peers profile set (from greeting message) */ 89 SR_RET_INVALID_FRAME_STATE = -21, /**< a frame object has an invalid frame state (pFram->iState) */ 90 SR_RET_PROFILE_ALREADY_SET = -22, /**< a profile should be assgined to a channel which already has one */ 91 SR_RET_INVALID_CHAN_STATE = -23, /**< a channel object has an invalid or unexpected (at this point) channel state */ 92 SR_RET_INVALID_GREETING = -24, /**< greeting message is (somehow) invalid, e.g. does not start with RPY) */ 93 SR_RET_INVALID_CHAN0_MESG = -25, /**< channel 0 received an invalid or out-of-sequence message */ 94 SR_RET_START_MISSING_NUMBER = -26, /**< a start message is missing the "number=" parameter */ 95 SR_RET_START_INVALID_NUMBER = -27, /**< a start message's "number=" parameter specifies an invalid number */ 96 SR_RET_START_EXISTING_NUMBER = -28, /**< a start message's "number=" parameter specifies a channel number which already exisits! */ 97 SR_RET_NO_VALUE = -29, /**< a linked list was asked to provide an uValue, but there was none. Not necessarily an error, depends on caller's needs. */ 98 SR_RET_START_EVEN_NUMBER = -30, /**< an initiator sent a even-numbered start number, which is invalid as of rfc 3080 2.3.1.2 */ 99 SR_RET_NO_PROFILE_RQSTD = -31, /**< no profile at all was requested in a start message (may be caused by invalid format) */ 100 SR_RET_WARNING_START_NO_PROFMATCH = -32,/**< WARNING only (no error) - during a start, no matching profile was found and the beep peer has been sent such an ERR frame */ 101 SR_RET_ERR_EVENT_HANDLER_MISSING = -33,/**< a required (profile) event handler is missing */ 102 SR_RET_ACKNO_ZERO = -34, /**< caller-provided ackno is zero. This can not be by design. */ 103 SR_RET_CHAN_DOESNT_EXIST = -35, /**< a chanel specified does not exist */ 104 SR_RET_ALREADY_LISTENING = -36, /**< caller tried to start an listener on the API object, but it is already one running */ 105 SR_RET_INVALID_OPTVAL = -37, /**< invalid option value was provided to srAPISetOption() (param 2) */ 106 SR_RET_INVALID_LIB_OPTION = -38, /**< invalid option was provided to srAPISetOption() (param 1) */ 107 SR_RET_NULL_POINTER_PROVIDED = -39, /**< the caller has provided a NULL-Pointer where none were expected/allowed */ 108 SR_RET_PROPERTY_NOT_AVAILABLE = -40,/**< a property asked for is not available, e.g. the TIMESTAMP in a not-wellformed message */ 109 SR_RET_UNSUPPORTED_FORMAT = -41, /**< a non-supported format was requested by the caller */ 110 SR_RET_UNALLOCATABLE_BUFFER = -42, /**< the operation can not be completed because a buffer that is under user control would need to be deallocated */ 111 SR_RET_PRIO_OUT_OF_RANGE = -43, /**< a priority value is outside the allowed range */ 112 SR_RET_FACIL_OUT_OF_RANGE = -44, /**< a facility value is outside the allowed range */ 113 SR_RET_INVALID_TAG = -45, /**< a syslog TAG value (string) provided was invalid, e.g. over 32 chars or included invalid chars */ 114 SR_RET_NULL_MSG_PROVIDED = -46, /**< caller provided a NULL pointer where a pointer to a MSG was expected */ 115 SR_RET_ERR_RECEIVE = -47, /**< an error occured during message receive. no more detail is available */ 116 SR_RET_UNEXPECTED_HDRCMD = -48, /**< an invalid HDR Command was received (e.g. an "MSG" in response to another "MSG") */ 117 SR_RET_PEER_INDICATED_ERROR = -49, /**< the PEER send an error response */ 118 SR_RET_PROVIDED_BUFFER_TOO_SMALL = -50,/**< the caller provided a buffer, but the called function sees the size of this buffer is too small - operation not carried out */ 119 SR_RET_INVALID_PARAM = -51, /**< an invalid parameter was provided to a method */ 120 121 /* socket error codes */ 122 SR_RET_SOCKET_ERR = -1001, /**< generic error generated by socket subsystem */ 123 SR_RET_CANT_BIND_SOCKET = -1002, /**< socket bind() operation failed */ 124 SR_RET_INVALID_SOCKET = -1003, /**< invalid socket */ 125 SR_RET_CONNECTION_CLOSED = -1004, /**< the remote peer closed the connection */ 126 SR_RET_INVALID_OS_SOCKETS_VERSION = -1005,/**< the operating system socket subsystem version is inappropriate (this error will most probably occur under Win32, only) */ 127 SR_RET_CAN_NOT_INIT_SOCKET = -1006, /**< socket() failed for whatever reason... */ 128 SR_RET_UXDOMSOCK_CHMOD_ERR = -1007, /**< chmod() failed on Unix Domain Socket */ 129 130 /* BEEP frame format & other errors */ 131 SR_RET_INVALID_HDRCMD = -2001, /**< invalid HDRCMD (e.g. "MSG", "RPY",...) */ 132 SR_RET_INVALID_WAITING_SP_CHAN = -2002, /**< invalid SP before channo */ 133 SR_RET_INVALID_CHANNO = -2003, /**< invalid channo */ 134 SR_RET_INVALID_WAITING_SP_MSGNO = -2004,/**< now the space before the next header */ 135 SR_RET_INVALID_IN_MSGNO = -2005, /**< and the next (numeric) header */ 136 SR_RET_INVALID_WAITING_SP_MORE = -2006, /**< now the space before the next header */ 137 SR_RET_INVALID_IN_MORE = -2007, /**< and the next (char) header */ 138 SR_RET_INVALID_WAITING_SP_SEQNO = -2008,/**< now the space before the next header */ 139 SR_RET_INVALID_IN_SEQNO = -2009, /**< and the next (numeric) header */ 140 SR_RET_INVALID_WAITING_SP_SIZE = -2010, /**< now the space before the next header */ 141 SR_RET_INVALID_IN_SIZE = -2011, /**< and the next (numeric) header */ 142 SR_RET_INVALID_WAITING_SP_ANSNO = -2012,/**< now the space before the next header */ 143 SR_RET_INVALID_IN_ANSNO = -2013, /**< and the next (numeric) header */ 144 SR_RET_INVALID_WAITING_HDRCR = -2014, /**< awaiting the HDR's CR */ 145 SR_RET_INVALID_WAITING_HDRLF = -2015, /**< awaiting the HDR's LF */ 146 SR_RET_INVALID_IN_PAYLOAD = -2016, /**< reading payload area */ 147 SR_RET_INVALID_WAITING_END1 = -2017, /**< waiting for the 1st HDR character */ 148 SR_RET_INVALID_WAITING_END2 = -2018, /**< waiting for the 2nd HDR character */ 149 SR_RET_INVALID_WAITING_END3 = -2019, /**< waiting for the 3rd HDR character */ 150 SR_RET_INVALID_WAITING_END4 = -2020, /**< waiting for the 4th HDR character */ 151 SR_RET_INVALID_WAITING_END5 = -2021, /**< waiting for the 5th HDR character */ 152 SR_RET_INVALID_WAITING_SP_ACKNO = -2022,/**< now the space before the next header */ 153 SR_RET_INVALID_WAITING_SP_WINDOW = -2023,/**< now the space before the next header */ 154 SR_RET_INAPROPRIATE_HDRCMD = -2024, /**< the beep header was syntactically correct, but could not be used semantically */ 155 SR_RET_OVERSIZED_FRAME = -2025, /**< the frame's "size" field specifies a size that does not fit into the current windows. Eventually malicous. */ 156 157 /* and finally the OK state... */ 158 SR_RET_OK = 0 /**< operation successful */ 159 }; 160 /** friendly type for global return value */ 161 typedef enum srRetVal_ srRetVal; 162 163 164 typedef unsigned SBchannel; /**< our own type for channel numbers */ 165 typedef unsigned SBseqno; /**< our own type for sequence numbers */ 166 typedef unsigned SBansno; /**< our own type for answer numbers */ 167 typedef unsigned SBsize; /**< our own type for frame size */ 168 typedef unsigned SBmsgno; /**< our own type for message numbers */ 169 typedef unsigned SBackno; /**< our own type for acknowledgment numbers */ 170 typedef unsigned SBwindow; /**< our own type for window sizes*/ 171 172 173 /** Object ID. These are for internal checking. Each 174 * object is assigned a specific ID. This is contained in 175 * all Object structs (just like C++ RTTI). We can use 176 * this field to see if we have been passed a correct ID. 177 * Other than that, there is currently no other use for 178 * the object id. 179 */ 180 enum srObjectID 181 { 182 OID_Freed = -1, /**< assigned, when an object is freed. If this 183 * is seen during a method call, this is an 184 * invalid object pointer! 185 */ 186 OID_Invalid = 0, /**< value created by calloc(), so do not use ;) */ 187 /* The 0xCDAB is a debug aid. It helps us find object IDs in memory 188 * dumps (on X86, this is ABCD in the dump ;) 189 * If you are on an embedded device and you would like to save space 190 * make them 1 byte only. 191 */ 192 OIDsbFram = 0xCDAB0001, 193 OIDsbChan = 0xCDAB0002, 194 OIDsbMesg = 0xCDAB0003, 195 OIDsbSess = 0xCDAB0004, 196 OIDsbSock = 0xCDAB0005, 197 OIDsbProf = 0xCDAB0006, 198 OIDsrAPI = 0xCDAB0007, 199 OIDsrSLMG = 0xCDAB0008, 200 OIDsbNVTR = 0xCDAB0009, 201 OIDsbNVTE = 0xCDAB000A, 202 OIDsbStrB = 0xCDAB000B, 203 OIDsbLstn = 0xCDAB000C, 204 OIDsbPSSR = 0xCDAB000D, 205 OIDsbPSRC = 0xCDAB000E 206 }; 207 typedef enum srObjectID srObjID; 208 209 210 /** 211 * Allowed options for 3195 client profile 212 * selection. 213 */ 214 enum srOPTION3195Profiles_ 215 { 216 USE_3195_PROFILE_ANY = 1, 217 USE_3195_PROFILE_RAW_ONLY = 2, 218 USE_3195_PROFILE_COOKED_ONLY = 3 219 }; 220 typedef enum srOPTION3195Profiles_ srOPTION3195Profiles; 221 222 /** 223 * Library options. Modify library behaviour. 224 * Currently, no options are defined. 225 */ 226 enum srOPTION 227 { 228 srOPTION_INVALID = 0, /**< invalid option, if seen, caller made an error */ 229 /** 230 * This option tells the library if it should instruct the 231 * socket parts of it to call the OS socket initialiser. 232 * Under Win32, for example, this is only allowed once per 233 * process. So if the lib is integrated into a process that 234 * already uses sockets, the sockets initializer (WSAStartup() 235 * in this case) should not be called. 236 * This is a global setting that NEEDS TO BE SET BEFORE the API 237 * object is created!!!! 238 */ 239 srOPTION_CALL_OS_SOCKET_INITIALIZER = 1, 240 /** 241 * This option tells the library which RFC 3195 Profile 242 * should be used when talking to the remote peer. This 243 * option so far is only used in the client parts of 244 * liblogging. See \ref srOPTION3195Profiles for 245 * allowed values. 246 */ 247 srOPTION_3195_ALLOWED_CLIENT_PROFILES = 2, 248 /** 249 * This options tells the lib if a UDP listener should 250 * be started. Option value must be TRUE or FALSE. 251 */ 252 srOPTION_LISTEN_UDP = 3, 253 /** 254 * Sets the UDP listener port. Is only used if the 255 * UDP listener is activated. 256 */ 257 srOPTION_UPD_LISTENPORT = 4, 258 /** 259 * This option tells the lib if a UNIX domain socket 260 * listener should be started. Supported values are 261 * TRUE and FALSE. 262 */ 263 srOPTION_LISTEN_UXDOMSOCK = 5, 264 /** 265 * Provides a pointer to the UNIX domain socket that 266 * should be listened to (if listening is enabled). 267 */ 268 srOPTION_UXDOMSOCK_LISTENAME = 6, 269 /** 270 * This option tells the lib if a BEEP 271 * listener should be started. Supported values are 272 * TRUE and FALSE. 273 * TODO: The current version of the library *ALWAYS* starts 274 * the BEEP listener, so this option is defunct currently! 275 */ 276 srOPTION_LISTEN_BEEP = 7, 277 /** 278 * Sets the BEEP listener port. Is only used if the 279 * UDP listener is activated. 280 */ 281 srOPTION_BEEP_LISTENPORT = 8 282 }; 283 typedef enum srOPTION SRoption; 284 285 /** 286 * This macro should be used to free objects. 287 * Microsoft VC automatically sets _DEBUG if compiling 288 * with debug settings. For other environments, you may 289 * want to add this to a debug makefile. 290 */ 291 #if DEBUGLEVEL > 0 292 #define SRFREEOBJ(x) {(x)->OID = OID_Freed; free(x);} 293 #else 294 #define SRFREEOBJ(x) free(x) 295 #endif 296 297 /** 298 * Integer values for the various supported 299 * BEEP headers. 300 */ 301 enum BEEPHdrID_ 302 { 303 BEEPHDR_UNKNOWN = 0, 304 BEEPHDR_ANS, 305 BEEPHDR_ERR, 306 BEEPHDR_MSG, 307 BEEPHDR_NUL, 308 BEEPHDR_RPY, 309 BEEPHDR_SEQ 310 }; 311 typedef enum BEEPHdrID_ BEEPHdrID; 312 313 314 #define BEEP_DEFAULT_MIME_HDR "Content-type: application/beep+xml\r\n" 315 316 #ifdef __cplusplus 317 } 318 #endif 319 #include "srAPI.h" 320 321 #endif 322