libisdn
Q931call.h
Go to the documentation of this file.
00001 /*****************************************************************************
00002 
00003   FileName:             Q931call.h
00004 
00005   Contents:             call related api functions.
00006 
00007   License/Copyright:
00008 
00009   Copyright (c) 2008, Stefan Knoblich, axsentis GmbH. All rights reserved.
00010   email: s.knoblich@axsentis.de
00011 
00012   Redistribution and use in source and binary forms, with or without
00013   modification, are permitted provided that the following conditions are
00014   met:
00015 
00016     * Redistributions of source code must retain the above copyright notice,
00017       this list of conditions and the following disclaimer.
00018     * Redistributions in binary form must reproduce the above copyright notice,
00019       this list of conditions and the following disclaimer in the documentation
00020       and/or other materials provided with the distribution.
00021     * Neither the name of the axsentis GmbH nor the names of its contributors
00022       may be used to endorse or promote products derived from this software
00023       without specific prior written permission.
00024 
00025   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
00026   AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
00027   IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
00028   ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
00029   LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
00030   CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
00031   SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
00032   INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
00033   CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
00034   ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
00035   POSSIBILITY OF SUCH DAMAGE.
00036 *****************************************************************************/
00037 
00038 #ifndef _Q931CALL_H_
00039 #define _Q931CALL_H_
00040 
00041 #define Q931_CALL_MAX_EVENTS    3       
00046 enum {
00047         Q931_EVENT_NONE = 0,                    
00049         /* Indications (L3 -> L4) */
00050         Q931_EVENT_SETUP_INDICATION,            
00051         Q931_EVENT_SETUP_CONFIRM,               
00052         Q931_EVENT_SETUP_COMPLETE_INDICATION,   
00053         Q931_EVENT_MORE_INFO_INDICATION,        
00054         Q931_EVENT_REJECT_INDICATION,           
00055         Q931_EVENT_PROCEEDING_INDICATION,       
00056         Q931_EVENT_ALERTING_INDICATION,         
00057         Q931_EVENT_PROGRESS_INDICATION,         
00058         Q931_EVENT_NOTIFY_INDICATION,           
00059         Q931_EVENT_RELEASE_INDICATION,          
00060         Q931_EVENT_RELEASE_CONFIRM,             
00061         Q931_EVENT_SUSPEND_CONFIRM,             
00062         Q931_EVENT_RESUME_CONFIRM,              
00063         Q931_EVENT_DISCONNECT_INDICATION,       
00064         Q931_EVENT_INFORMATION_INDICATION,      
00065         Q931_EVENT_STATUS_INDICATION,           
00066         Q931_EVENT_RESTART_CONFIRM,             
00068         /* Requests (L4 -> L3) (?) */
00069         Q931_EVENT_SETUP_RESPONSE,              
00070         Q931_EVENT_REJECT_REQUEST,              
00071         Q931_EVENT_INFORMATION_REQUEST,         
00072         Q931_EVENT_ALERTING_REQUEST,            
00073         Q931_EVENT_PROGRESS_REQUEST,            
00074         Q931_EVENT_PROCEEDING_REQUEST,          
00075         Q931_EVENT_NOTIFY_REQUEST,              
00076         Q931_EVENT_SUSPEND_REQUEST,             
00077         Q931_EVENT_DISCONNECT_REQUEST,          
00078         Q931_EVENT_RESTART_REQUEST,             
00080         /* Misc events (L2/L3 -> L4) */
00081         Q931_EVENT_TIMEOUT_INDICATION,          
00082         Q931_EVENT_DL_FAILURE_INDICATION,       
00084         /* CRV events */
00085         Q931_EVENT_RELEASE_CRV,                 
00086 };
00087 
00091 enum {
00092         Q931_EVENT_TYPE_NONE = 0,
00093         Q931_EVENT_TYPE_CRV,
00094         Q931_EVENT_TYPE_TIMER,
00095         Q931_EVENT_TYPE_MESSAGE,
00096 };
00097 
00101 struct Q931_CallTimerEvent
00102 {
00103         L3INT id;
00104 };
00105 
00109 struct Q931_CallMessageEvent
00110 {
00111         L3INT           type;
00112         Q931mes_Generic *data;
00113 };
00114 
00118 struct Q931_CallEvent
00119 {
00120         L3INT   id;             
00121         L3INT   type;           
00122         L3BOOL  error;          
00124         /* Additional event data */
00125         union {
00126                 struct Q931_CallTimerEvent      timer;
00127                 struct Q931_CallMessageEvent    message;
00128         } data;
00129 };
00130 
00134 enum {
00135         /* Q.931 User mode states */
00136         Q931_U0  = 0,                   
00137         Q931_U1,                        
00138         Q931_U2,                        
00139         Q931_U3,                        
00140         Q931_U4,                        
00141         Q931_U6  = 6,                   
00142         Q931_U7,                        
00143         Q931_U8,                        
00144         Q931_U9,                        
00145         Q931_U10,                       
00146         Q931_U11,                       
00147         Q931_U12,                       
00148         Q931_U15 = 15,                  
00149         Q931_U17 = 17,                  
00150         Q931_U19 = 19,                  
00151         Q931_U25 = 25,                  
00153         Q931_UANY = 0xff,               
00155         /* Q.931 Network mode states */
00156         Q931_N0  = (0x0100 | 0),        
00157         Q931_N1,                        
00158         Q931_N2,                        
00159         Q931_N3,                        
00160         Q931_N4,                        
00161         Q931_N6  = (0x0100 | 6),        
00162         Q931_N7,                        
00163         Q931_N8,                        
00164         Q931_N9,                        
00165         Q931_N10,                       
00166         Q931_N11,                       
00167         Q931_N12,                       
00168         Q931_N15 = (0x0100 | 15),       
00169         Q931_N17 = (0x0100 | 17),       
00170         Q931_N19 = (0x0100 | 19),       
00171         Q931_N22 = (0x0100 | 22),       
00172         Q931_N25 = (0x0100 | 25),       
00174         Q931_NANY = 0x1ff               
00175 };
00176 
00177 
00181 enum {
00182         Q931_DIRECTION_INBOUND = 0,
00183         Q931_DIRECTION_OUTBOUND
00184 };
00185 
00189 struct Q931_Call
00190 {
00191         L3UCHAR InUse;                  /* Indicate if entry is in use.         */
00192                                         /*  0 = Not in Use                      */
00193                                         /*  1 = Active Call.                    */
00194 
00195         L3UCHAR Tei;                    /* Associated TEI                       */
00196 
00197         L3UCHAR BChan;                  /* Associated B Channel.                */
00198                                         /* 0 - 31 valid B chan                  */
00199                                         /* 255 = Not allocated                  */
00200 
00201         L3UCHAR Direction;              /* Direction of call                    */
00202         L3INT   CRV;                    /* Associated CRV.                      */
00203 
00204         L3UINT  State;                  /* Call State.                          */
00205                                         /*  0 is Idle, but other values are     */
00206                                         /*  defined per dialect.                */
00207                                         /*  Default usage is 1-99 for TE and    */
00208                                         /*  101 - 199 for NT.                   */
00209 
00210         L3ULONG Timer;                  /* Timer in ms. The TimeTick will check */
00211                                         /* if this has exceeded the timeout, and*/
00212                                         /* if so call the timers timeout proc.  */
00213 
00214         L3USHORT TimerID;               /* Timer Identification/State           */
00215                                         /* actual values defined by dialect     */
00216                                         /*  0 : No timer running                */
00217                                         /*  ITU-T Q.931:301 - 322 Timer running */
00218 
00219         L3UCHAR TimerCnt;               /* Counter to track the number of expire events */
00220 
00221 
00222         Q931_TrunkInfo_t *Trunk;        /* Short-cut pointer to access the      */
00223                                         /* associated trunk                     */
00224 
00225         void *pvt;                      /* L4 Private data */
00226 
00227         /*
00228          * Per-call event queue
00229          */
00230         L3INT                   numevents;                      
00231         struct Q931_CallEvent   events[Q931_CALL_MAX_EVENTS];   
00232 };
00233 
00234 typedef struct Q931_Call Q931_Call_t;
00235 
00236 typedef void (*Q931CallEventCB_t) (struct Q931_Call *call, struct Q931_CallEvent *event, void *priv);
00237 
00238 
00239 /*
00240  * Helper functions
00241  */
00242 
00243 void Q931CallSetState(struct Q931_Call *call, const L3INT state);       /* TODO: private? */
00244 Q931_API L3INT Q931CallGetState(const struct Q931_Call *call);
00245 Q931_API const char * Q931CallGetStateName(const struct Q931_Call *call);
00246 Q931_API const char * Q931CallGetEventName(const L3INT event);
00247 Q931_API const char * Q931CallGetTimerName(const L3USHORT timer);
00248 
00249 Q931_API void   Q931CallSetPrivate(struct Q931_Call *call, const void *priv);
00250 Q931_API void * Q931CallGetPrivate(const struct Q931_Call *call);
00251 
00252 Q931_API Q931_TrunkInfo_t * Q931CallGetTrunk(const struct Q931_Call *call);
00253 
00254 Q931_API void Q931SetCallEventCB(Q931_TrunkInfo_t *trunk, const Q931CallEventCB_t cb, const void *priv);
00255 
00256 /*
00257  * Call control
00258  */
00259 
00260 /* *********************************************** */
00261 
00262 struct Q931_Call *Q931CallNew(Q931_TrunkInfo_t *trunk);
00263 L3INT Q931CallRelease(struct Q931_Call *call);
00264 
00265 Q931_API L3INT Q931CallGetCRV(const struct Q931_Call *call);
00266 Q931_API L3INT Q931CallGetDirection(const struct Q931_Call *call);
00267 Q931_API L3BOOL Q931CallIsOutgoing(const struct Q931_Call *call);
00268 Q931_API L3BOOL Q931CallIsGlobal(const struct Q931_Call *call);
00269 
00270 Q931_API L3INT Q931CallEventGetType(const struct Q931_CallEvent *event);
00271 Q931_API L3INT Q931CallEventGetId(const struct Q931_CallEvent *event);
00272 Q931_API void * Q931CallEventGetData(const struct Q931_CallEvent *event);
00273 
00274 Q931_API struct Q931_Call * Q931GetCallByCRV(const Q931_TrunkInfo_t *trunk, const L3INT crv);
00275 Q931_API struct Q931_Call * Q931GetGlobalCall(const Q931_TrunkInfo_t *trunk);
00276 
00277 /*
00278  * Debug
00279  */
00280 Q931_API L3INT Q931CallDump(const struct Q931_Call *call);
00281 Q931_API L3INT Q931DumpAllCalls(const Q931_TrunkInfo_t *trunk);
00282 
00283 /*
00284  * Q.931 Internal
00285  */
00286 #if defined(Q931_PRIVATE)
00287 
00288 void Q931CallInitEvent(struct Q931_CallEvent *event);
00289 void Q931CallSendEvent(const struct Q931_Call *call, const struct Q931_CallEvent *event);
00290 
00291 /* V2 part of the call event api */
00292 struct Q931_CallEvent *Q931CallNewEvent(struct Q931_Call *call);
00293 void Q931CallSendQueuedEvents(struct Q931_Call *call);
00294 void Q931CallQueueEvent(struct Q931_Call *call, struct Q931_CallEvent *event);
00295 void Q931CallFlushEvents(struct Q931_Call *call);
00296 
00297 
00298 struct Q931_Call *Q931CallNewIncoming(Q931_TrunkInfo_t *trunk, const L3INT crv);
00299 struct Q931_Call *Q931GetCallByIndex(const Q931_TrunkInfo_t *trunk, const L3INT callindex);
00300 
00301 void Q931CallStartTimer(struct Q931_Call *call, L3USHORT timer);
00302 void Q931CallRestartTimer(struct Q931_Call *call, L3USHORT timer);
00303 void Q931CallStopTimer(struct Q931_Call *call, L3USHORT timer);
00304 void Q931CallStopAllTimers(struct Q931_Call *call);
00305 Q931_API L3USHORT Q931CallGetTimerID(const struct Q931_Call *call);
00306 Q931_API L3UCHAR Q931CallGetTimerExpireCount(const struct Q931_Call *call);
00307 void Q931CallIncrementTimerExpireCount(struct Q931_Call *call);
00308 
00309 #endif /* Q931_PRIVATE */
00310 
00311 #endif