1 /*! \file beepprofile.h 2 * \brief The BEEP Profile Object 3 * 4 * \author Rainer Gerhards <rgerhards@adiscon.com> 5 * \date 2003-08-04 6 * 7 * \date 2003-09-04 8 * Updated so that a client can have multiple 9 * profiles. 10 * 11 * Copyright 2002-2014 12 * Rainer Gerhards and Adiscon GmbH. All Rights Reserved. 13 * 14 * Redistribution and use in source and binary forms, with or without 15 * modification, are permitted provided that the following conditions are 16 * met: 17 * 18 * * Redistributions of source code must retain the above copyright 19 * notice, this list of conditions and the following disclaimer. 20 * 21 * * Redistributions in binary form must reproduce the above copyright 22 * notice, this list of conditions and the following disclaimer in 23 * the documentation and/or other materials provided with the 24 * distribution. 25 * 26 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS 27 * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 28 * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A 29 * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER 30 * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 31 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 32 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 33 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 34 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 35 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 36 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 37 */ 38 #ifndef __LIB3195_BEEPPROFILE_H_INCLUDED__ 39 #define __LIB3195_BEEPPROFILE_H_INCLUDED__ 1 40 #define sbProfCHECKVALIDOBJECT(x) {assert(x != NULL); assert(x->OID == OIDsbProf);} 41 42 struct sbMesgObject; 43 struct sbNVTRObject; 44 struct srAPIObject; 45 struct srSLMGObject; 46 47 #if FEATURE_LISTENER == 1 48 /** event handlers */ 49 enum sbProfEvent_ 50 { 51 sbPROFEVENT_ONMESGRECV, 52 sbPROFEVENT_ONCHANCREAT, 53 sbPROFEVENT_UNKNOWN = 0 /**< should never be used, included as saveguard (calloc()!). */ 54 }; 55 typedef enum sbProfEvent_ sbProfEvent; 56 57 #endif 58 59 struct sbProfObject 60 /** The BEEP Profile object. Implemented via \ref beepprofile.h and 61 * \ref beepprofile.c. 62 */ 63 { 64 srObjID OID; /**< object ID */ 65 char* pszProfileURI; /**< pointer to the URI to be used during negotiation */ 66 #if FEATURE_LISTENER == 1 67 int bDestroyOnChanClose; /**< this profile should be destroyed when the channel is closed */ 68 struct srAPIObject *pAPI; /**< pointer to associated API object */ 69 /* now come the event handlers */ 70 /** called, when the channel is initially created. (from the <start> handler). Is responsible 71 ** for sending any profile-specific greeting. 72 **/ 73 srRetVal (*OnChanCreate)(struct sbProfObject *pThis, struct sbSessObject* pSess, struct sbChanObject* pChan); 74 /** called whenever a new complete message arrives. Must reply according to 75 ** profile spec. 76 **/ 77 srRetVal (*OnMesgRecv)(struct sbProfObject *pThis, int* pAbort, struct sbSessObject* pSess, struct sbChanObject* pChan, struct sbMesgObject *pMesg); 78 #endif 79 /* now come client-side event handlers (always present) */ 80 /** method to call if client-side API needs to open a log channel */ 81 srRetVal (*OnClntOpenLogChan)(struct sbChanObject *pChan); 82 /** method to call if client-side API needs to send a syslog message */ 83 srRetVal (*OnClntSendLogMsg)(struct sbChanObject* pChan, char* szLogmsg); 84 /** method to call if client-side API needs to send a srSLMGObj */ 85 srRetVal (*OnClntSendSLMG)(struct sbChanObject* pChan, struct srSLMGObject *pSLMG); 86 /** method to call if client-side API needs to close a log channel */ 87 srRetVal (*OnClntCloseLogChan)(struct sbChanObject* pChan); 88 }; 89 typedef struct sbProfObject sbProfObj; 90 91 /** Constructor to create a sbProf. 92 * 93 * \param ppThis [out] pointer to a buffer that will receive 94 * the pointer to the newly created profile 95 * object. 96 * \param szURI [in] - name of uri to be used in greeting. May 97 * be NULL for a profile, that should not be 98 * advertised (channel 0 is a meaningful sample). 99 * 100 */ 101 srRetVal sbProfConstruct(sbProfObj** ppThis, char *pszURI); 102 103 /** 104 * Return the profile URI. The returned string is read-only. 105 * \retval URI profile string 106 */ 107 char* sbProfGetURI(sbProfObj* pThis); 108 109 /** 110 * Profile Object Destructor. 111 */ 112 void sbProfDestroy(sbProfObj* pThis); 113 114 /** 115 * Set and unset an event handler. A new handler is set 116 * for the specified event. To unset it, provide NULL as 117 * the handler pointer. 118 * 119 * \param iEvent Event ID to be modified 120 * \param handler Pointer to event handler. Must follow the semantics 121 * of this specific event (will not be checked) 122 */ 123 srRetVal sbProfSetEventHandler(struct sbProfObject* pThis, sbProfEvent iEvent, srRetVal (*handler)()); 124 125 /** 126 * Set the associated API object. 127 * \param pAPI - API object to be set. 128 */ 129 srRetVal sbProfSetAPIObj(sbProfObj *pThis, srAPIObj *pAPI); 130 131 /** 132 * Find a matching profile in two lists of profiles. 133 * The matching is done based on the URI. 134 * If a match is found, we return the pointer to it. If it is 135 * not found, we return NULL. The FIRST matching profile 136 * will be returned. It is not tried to find the best match. 137 * 138 * \param pProfListRemote List of remote profiles, created from the 139 * greeting. This are NOT profile objects but 140 * rather URI strings in pszKey. 141 * \param pProfList2 list (sbNVTRObj) of profiles. MAY BE NULL! (which indicates 142 * an empty list of profiles. 143 * \retval Pointer to the first matching entry or NULL, if none 144 * found. 145 */ 146 sbProfObj* sbProfFindProfileMatch(struct sbNVTRObject *pProfListRemote, struct sbNVTRObject *pProfList2); 147 148 /** 149 * Find a profile based on an URI in a list of profiles. 150 * 151 * \param pProfileList Pointer to list of Profiles. May be NULL. 152 * \param pszSearch string to be compared to. Must not be NULL. 153 * \retval Pointer to the profile found or NULL, if none found. 154 */ 155 sbProfObj* sbProfFindProfile(struct sbNVTRObject *pProfList, char* pszSearch); 156 157 /** 158 * Set the 4 mandatory event handlers for client profiles. 159 * As all of them need to be set for the profile to work, 160 * we provide a single call to set them all at once. 161 * 162 * The param names reflect the names of the event handlers. 163 * All event handlers MUST point to actual handlers, none 164 * if them is allowed to be NULL. 165 */ 166 srRetVal sbProfSetClntEventHandlers(sbProfObj *pProf, 167 srRetVal (*OnClntOpenLogChan)(struct sbChanObject *pChan), 168 srRetVal (*OnClntSendLogMsg)(struct sbChanObject* pChan, char* szLogmsg), 169 srRetVal (*OnClntSendSLMG)(struct sbChanObject* pChan, struct srSLMGObject *pSLMG), 170 srRetVal (*OnClntCloseLogChan)(struct sbChanObject* pChan)); 171 172 /** 173 * Take a list of profile objects AND a list 174 * of (remotely supported) profile URIs and 175 * find a match in them. The matching is done 176 * so that the first local profile found in the 177 * remote URI list will be returned. If there 178 * are multiple matches, all other matches will 179 * be IGNORED. 180 * 181 * \param pProfListLocal List of locally supported profile 182 * objects. 183 * 184 * \param pURIListRemote List of remotely supported 185 * profile URIs. 186 * 187 * \retval The matching profile object from the 188 * local profile object. 189 */ 190 sbProfObj* sbProfFindProfileURIMatch(struct sbNVTRObject *pProfListLocal, struct sbNVTRObject *pURIListRemote); 191 192 193 #endif 194