libisdn
Q931.h
Go to the documentation of this file.
00001 /******************************************************************************
00002 
00003   FileName:         Q931.h
00004 
00005   Contents:         Header and definition for the ITU-T Q.931 stack. The
00006                     header contents the following parts:
00007 
00008                     - Definition of codes
00009                     - Definition of information elements (Q931ie_).
00010                     - Definition of messages (Q931mes_).
00011                     - Definitian of variables (var_).
00012                     - Function prototypes.
00013 
00014   Description:          The Q.931 stack provided here covers ITU-T Q.931 w/Q.932
00015                     supplementary services for both PRI, BRI and variants.
00016                     The stack is generic and designed to deal with variants as
00017                     needed.
00018 
00019                     The stack uses the following interface functions:
00020 
00021                     - Q931Initialize    Initialize the Q.931 stack.
00022                     - Q931Rx23                  Receive a message from layer 2
00023                     - Q931Tx32                  Send a message to layer 2
00024                     - Q931Rx43                  Receive a message from layer 4 or above.
00025                     - Q931Tx34                  Send a message to layer 4 or above.
00026                     - Q931TimeTick              Periodical timer processing.
00027                     - Q931ErrorProc             Callback for stack error message.
00028 
00029                     The protocol is a module with no external dependencies and
00030                     can easely be ported to any operating system like Windows,
00031                     Linux, rtos and others.
00032 
00033   Related Files:        Q931.h                          Q.931 Definitions
00034                     Q931.c                              Q.931 Interface Functions.
00035                     Q931api.c                   Low level L4 API functions.
00036 
00037                     Q932.h                              Q.932 Suplementary Services
00038                     Q932mes.c                   Q.932 encoders/coders
00039 
00040                     Q931mes.c                   Q.931 Message encoders/coders
00041                     Q931ie.c                    Q.931 IE encoders/coders
00042                     Q931StateTE.c               Generic Q.931 TE State Engine
00043                     Q931StateNT.c               Generic Q.931 NT State Engine
00044 
00045   Design Note 1:        For each variant please add separate files starting with
00046                     the variant short-name as follows:
00047 
00048                     <variant>.h                 Spesific headers needed.
00049                     <variant>mes.c              Message encoders/decores.
00050                     <variant>ie.c               IE encoders/decoders.
00051                     <variant>StateTE.c  TE side state engine.
00052                     <variant>StateNT.c  NT side state engine.
00053 
00054   Design Note 2:        The stack is deliberatly made non-threading. Use 1
00055                     thread per Trunk, but lock access from the timertick
00056                     and rx, tx functions. And make sure the callbacks only
00057                     dump messages to a queue, no time-consuming processing
00058                     inside stack processing.
00059 
00060                     All stack processing is async 'fire and forget', meaning
00061                     that there are not, and should not be any time-consuming
00062                     processing within the stack-time. The best way to thread
00063                     a stack is to use one single thread that signal 5 queues.
00064 
00065                     - Incoming L2 queue.
00066                     - Incoming L4 queue.
00067                     - Outgoing L2 queue.
00068                     - Outgoing L4 queue.
00069                     - Error/Trace queue.
00070 
00071   Design Note 3:        DSP optimization. The L3 (Rx23) can be called directly
00072                     from a HDLC receiver without usage of queues for optimized
00073                     processing. But keep in mind that Q.931 calls Tx34 or Tx32
00074                     as part     of receiving a message from Layer 2.
00075 
00076   License/Copyright:
00077 
00078   Copyright (c) 2007, Jan Vidar Berger, Case Labs, Ltd. All rights reserved.
00079   email:janvb@caselaboratories.com
00080 
00081   Redistribution and use in source and binary forms, with or without
00082   modification, are permitted provided that the following conditions are
00083   met:
00084 
00085     * Redistributions of source code must retain the above copyright notice,
00086           this list of conditions and the following disclaimer.
00087     * Redistributions in binary form must reproduce the above copyright notice,
00088           this list of conditions and the following disclaimer in the documentation
00089           and/or other materials provided with the distribution.
00090     * Neither the name of the Case Labs, Ltd nor the names of its contributors
00091           may be used to endorse or promote products derived from this software
00092           without specific prior written permission.
00093 
00094   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
00095   AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
00096   IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
00097   ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
00098   LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
00099   CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
00100   SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
00101   INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
00102   CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
00103   ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
00104   POSSIBILITY OF SUCH DAMAGE.
00105 ******************************************************************************/
00106 
00107 #ifndef _Q931_H_
00108 #define _Q931_H_
00109 
00110 #include "Q9XXplatform.h"
00111 
00112 /*****************************************************************************
00113 
00114   Error Codes
00115 
00116 *****************************************************************************/
00117 /* hmmm... */
00118 typedef enum {
00119         Q931E_NO_ERROR              = 0,
00120 
00121         Q931E_UNKNOWN_MESSAGE       = -3001,
00122         Q931E_ILLEGAL_IE            = -3002,
00123         Q931E_UNKNOWN_IE            = -3003,
00124         Q931E_BEARERCAP             = -3004,
00125         Q931E_HLCOMP                = -3005,
00126         Q931E_LLCOMP                = -3006,
00127         Q931E_INTERNAL              = -3007,
00128         Q931E_MISSING_CB            = -3008,
00129         Q931E_UNEXPECTED_MESSAGE    = -3009,
00130         Q931E_ILLEGAL_MESSAGE       = -3010,
00131         Q931E_TOMANYCALLS           = -3011,
00132         Q931E_INVALID_CRV           = -3012,
00133         Q931E_CALLID                = -3013,
00134         Q931E_CALLSTATE             = -3014,
00135         Q931E_CALLEDSUB             = -3015,
00136         Q931E_CALLEDNUM             = -3016,
00137         Q931E_CALLINGNUM            = -3017,
00138         Q931E_CALLINGSUB            = -3018,
00139         Q931E_CAUSE                 = -3019,
00140         Q931E_CHANID                = -3020,
00141         Q931E_DATETIME              = -3021,
00142         Q931E_DISPLAY               = -3022,
00143         Q931E_KEYPADFAC             = -3023,
00144         Q931E_NETFAC                = -3024,
00145         Q931E_NOTIFIND              = -3025,
00146         Q931E_PROGIND               = -3026,
00147         Q931E_RESTARTIND            = -3027,
00148         Q931E_SEGMENT               = -3028,
00149         Q931E_SIGNAL                = -3029,
00150         Q931E_GENERIC_DIGITS        = -3030,
00151         Q931E_MANDATORY_IE_MISSING  = -3031,
00152         Q931E_UNRECOGNIZED_MESSAGE  = -3032,
00153 } q931_error_t;
00154 
00155 /* The q931_error_t enum should be kept in sync with the q931_error_names array in Q931.c */
00156 
00157 Q931_API const char *q931_error_to_name(q931_error_t error);
00158 
00159 /*****************************************************************************
00160 
00161         Some speed optimization can be achieved by changing all variables to the
00162         word size of your processor. A 32 bit processor has to do a lot of extra
00163         work to read a packed 8 bit integer. Changing all fields to 32 bit integer
00164         will result in usage of some extra space, but will speed up the stack.
00165 
00166         The stack has been designed to allow L3UCHAR etc. to be any size of 8 bit
00167         or larger.
00168 
00169 *****************************************************************************/
00170 /* public */
00171 #define L3CHAR   char                   /* Min 8 bit */
00172 #define L3UCHAR  unsigned char          /* Min 8 bit */
00173 #define L3USHORT unsigned short         /* Min 16 bit unsigned */
00174 #define L3UINT   unsigned int           /* Min 16 bit unsigned */
00175 #define L3INT    int                    /* Min 16 bit signed */
00176 #define L3ULONG  unsigned long          /* Min 32 bit */
00177 #define L3BOOL   char                   /* Min 1 bit, valuse 0 & 1 only */
00178 
00179 #define L3TRUE  1
00180 #define L3FALSE 0
00181 
00182 /*****************************************************************************
00183 
00184   Global defines.
00185 
00186 *****************************************************************************/
00187 /* public */
00188 typedef L3USHORT ie;                /* Special data type to hold a dynamic  */
00189                                     /* or optional information element as   */
00190                                     /* part of a message struct. MSB = 1    */
00191                                     /* indicate that the ie is present, the */
00192                                     /* last 15 bits is an offset ( or the   */
00193                                     /* value for single octet ) to the      */
00194                                     /* struct holding the ie. Offset = 0    */
00195                                     /* is buf[1] etc.                       */
00196                                     /* ie == 0xffff indicates error         */
00197 
00198 /*****************************************************************************
00199 
00200         MAXTRUNKS sets how many physical trunks this system might have. This
00201         number should be keept at a minimum since it will use global space.
00202 
00203         It is recommended that you leave MAXCHPERTRUNK as is
00204 
00205 *****************************************************************************/
00206 /* some probably private */
00207 #define Q931_LOGBUFSIZE 1024            /* size of logging buffer               */
00208 
00209 #define Q931L4BUF       1000            /* size of message buffer               */
00210 
00211 #define Q931L2BUF       300             /* size of message buffer               */
00212 
00213 #define Q931MAXTRUNKS   4               /* Total number of trunks that will be  */
00214                                         /* processed by this instance of the    */
00215                                         /* stack                                */
00216 
00217 #define Q931MAXCHPERTRUNK       32      /* Number of channels per trunk. The    */
00218                                         /* stack uses a static set of 32        */
00219                                         /* channels regardless if it is E1, T1  */
00220                                         /* or BRI that actually is used.        */
00221 
00222 #define Q931MAXCALLPERTRUNK     (Q931MAXCHPERTRUNK * 2)
00223                                         /* Number of max active CRV per trunk.  */
00224                                         /* Q.931 can have more calls than there */
00225                                         /* are channels.                        */
00226 
00227 /* private? */
00228 #define Q931_IS_BRI(x)          ((x)->TrunkType == Q931_TrType_BRI || (x)->TrunkType == Q931_TrType_BRI_PTMP)
00229 #define Q931_IS_PRI(x)          (!Q931_IS_BRI(x))
00230 
00231 #define Q931_IS_PTP(x)          ((x)->TrunkType != Q931_TrType_BRI_PTMP)
00232 #define Q931_IS_PTMP(X)         ((x)->TrunkType == Q931_TrType_BRI_PTMP)
00233 
00234 #define Q931_BRI_MAX_CRV        127
00235 #define Q931_PRI_MAX_CRV        32767
00236 
00237 /*****************************************************************************
00238 
00239   The following defines control the dialect switch tables and should only be
00240   changed when a new dialect needs to be inserted into the stack.
00241 
00242   This stack uses an array of functions to know which function to call as
00243   it receives a SETUP message etc. A new dialect can when choose to use
00244   the proc etc. for standard Q.931 or insert a modified proc.
00245 
00246   This technique has also been used to distinguish between user and network
00247   mode to make the code as easy to read and maintainable as possible.
00248 
00249   A message and IE index have been used to save space. These indexes allowes
00250   the message or IE code to be used directly and will give back a new index
00251   into the table.
00252 
00253 *****************************************************************************/
00254 
00255 /* WARNING! Initialize Q931CreateDialectCB[] will NULL when increasing the */
00256 /* Q931MAXDLCT value to avoid Q931Initialize from crashing if one entry is */
00257 /* not used.                                                               */
00258 #define Q931MAXDLCT     8       /* Max dialects included in this        */
00259                                 /* compile. User and Network count as   */
00260                                 /* one dialect each.                    */
00261 
00262 #define Q931MAXMES      128             /* Number of messages                           */
00263 #define Q931MAXIE       255             /* Number of IE                                 */
00264 #define Q931MAXUSEDIE   50              /* Maximum number of ie types per Dialect       */
00265 #define Q931MAXCODESETS 7               /* Maximum number of codests (by spec, 0-7)     */
00266 #define Q931MAXSTATE    100             /* Size of state tables                         */
00267 #define Q931MAXTIMER    25              /* Maximum number of timers                     */
00268 
00269 
00270 /*****************************************************************************
00271 
00272   Q.931 Message codes
00273 
00274 *****************************************************************************/
00275 /* goal: private */
00276 #define Q931mes_ALERTING             0x01 /* 0000 0001                   */
00277 #define Q931mes_CALL_PROCEEDING      0x02 /* 0000 0010                   */
00278 #define Q931mes_CONNECT              0x07 /* 0000 0111                   */
00279 #define Q931mes_CONNECT_ACKNOWLEDGE  0x0f /* 0000 1111                   */
00280 #define Q931mes_PROGRESS             0x03 /* 0000 0011                   */
00281 #define Q931mes_SETUP                0x05 /* 0000 0101                   */
00282 #define Q931mes_SETUP_ACKNOWLEDGE    0x0d /* 0000 1101                   */
00283 #define Q931mes_RESUME               0x26 /* 0010 0110                   */
00284 #define Q931mes_RESUME_ACKNOWLEDGE   0x2e /* 0010 1110                   */
00285 #define Q931mes_RESUME_REJECT        0x22 /* 0010 0010                   */
00286 #define Q931mes_SUSPEND              0x25 /* 0010 0101                   */
00287 #define Q931mes_SUSPEND_ACKNOWLEDGE  0x2d /* 0010 1101                   */
00288 #define Q931mes_SUSPEND_REJECT       0x21 /* 0010 0001                   */
00289 #define Q931mes_USER_INFORMATION     0x20 /* 0010 0000                   */
00290 #define Q931mes_DISCONNECT           0x45 /* 0100 0101                   */
00291 #define Q931mes_RELEASE              0x4d /* 0100 1101                   */
00292 #define Q931mes_RELEASE_COMPLETE     0x5a /* 0101 1010                   */
00293 #define Q931mes_RESTART              0x46 /* 0100 0110                   */
00294 #define Q931mes_RESTART_ACKNOWLEDGE  0x4e /* 0100 1110                   */
00295 #define Q931mes_CONGESTION_CONTROL   0x79 /* 0111 1001                   */
00296 #define Q931mes_INFORMATION          0x7b /* 0111 1011                   */
00297 #define Q931mes_NOTIFY               0x6e /* 0110 1110                   */
00298 #define Q931mes_STATUS               0x7d /* 0111 1101                   */
00299 #define Q931mes_STATUS_ENQUIRY       0x75 /* 0111 0101                   */
00300 #define Q931mes_SEGMENT              0x60 /* 0110 0000                   */
00301 #define Q931mes_FACILITY             0x62 /* 0110 0010                   */
00302 
00303 /* AT&T 5ESS */
00304 #define Q931mes_SERVICE              0x0f /* 0000 1111  (ProtDisc 3)     */
00305 #define Q931mes_SERVICE_ACKNOWLEDGE  0x07 /* 0000 0111  (ProtDisc 3)     */
00306 
00307 #define Q931mes_FACILITY_ACKNOWLEDGE 0x6a /* 0110 1010                   */
00308 #define Q931mes_FACILITY_REJECT      0x72 /* 0111 0010                   */
00309 #define Q931mes_REGISTER             0x64 /* 0110 0100                   */
00310 
00311 
00316 enum {
00317         Q931_TIMER_NONE = 0,
00318         Q931_TIMER_T300,                /* */
00319         Q931_TIMER_T301,
00320         Q931_TIMER_T302,
00321         Q931_TIMER_T303,
00322         Q931_TIMER_T304,
00323         Q931_TIMER_T305,
00324         Q931_TIMER_T306,
00325         Q931_TIMER_T307,
00326         Q931_TIMER_T308,
00327         Q931_TIMER_T309,
00328         Q931_TIMER_T310,
00329         Q931_TIMER_T311,
00330         Q931_TIMER_T312,
00331         Q931_TIMER_T313,
00332         Q931_TIMER_T314,
00333         Q931_TIMER_T315,
00334         Q931_TIMER_T316,
00335         Q931_TIMER_T317,
00336         Q931_TIMER_T318,
00337         Q931_TIMER_T319,
00338         Q931_TIMER_T320,
00339         Q931_TIMER_T321,
00340         Q931_TIMER_T322,
00341 };
00342 
00346 typedef enum {
00347         Q931_TON_UNKNOWN                = 0x00,
00348         Q931_TON_INTERNATIONAL          = 0x01,
00349         Q931_TON_NATIONAL               = 0x02,
00350         Q931_TON_NETWORK_SPECIFIC       = 0x03,
00351         Q931_TON_SUBSCRIBER_NUMBER      = 0x04,
00352         Q931_TON_ABBREVIATED_NUMBER     = 0x06,
00353         Q931_TON_RESERVED               = 0x07
00354 } q931_ton_t;
00355 
00359 typedef enum {
00360         Q931_NUMPLAN_UNKNOWN            = 0x00,
00361         Q931_NUMPLAN_E164               = 0x01,
00362         Q931_NUMPLAN_X121               = 0x03,
00363         Q931_NUMPLAN_F69                = 0x04,
00364         Q931_NUMPLAN_NATIONAL           = 0x08,
00365         Q931_NUMPLAN_PRIVATE            = 0x09,
00366         Q931_NUMPLAN_RESERVED           = 0x0e
00367 } q931_npi_t;
00368 
00372 typedef enum {
00373         Q931_PRES_ALLOWED               = 0x00,
00374         Q931_PRES_RESTRICTED            = 0x01,
00375         Q931_PRES_NOT_AVAILABLE         = 0x02,
00376         Q931_PRES_RESERVED              = 0x03
00377 } q931_pres_t;
00378 
00382 typedef enum {
00383         Q931_SCREEN_USER_NOT_SCREENED           = 0x00,
00384         Q931_SCREEN_USER_VERIFIED_PASSED        = 0x01,
00385         Q931_SCREEN_USER_VERIFIED_FAILED        = 0x02,
00386         Q931_SCREEN_NETWORK                     = 0x03
00387 } q931_screen_t;
00388 
00392 typedef enum {
00393         Q931_CODING_ITU         = 0x00,
00394         Q931_CODING_ISO         = 0x01,
00395         Q931_CODING_NATIONAL    = 0x02,
00396         Q931_CODING_NETWORK     = 0x03
00397 } q931_coding_t;
00398 
00402 typedef enum {
00403         Q931_HLCHAR_TELEPHONY   = 0x01,
00404         Q931_HLCHAR_FAX_G23     = 0x04,
00405         Q931_HLCHAR_FAX_G4      = 0x21,
00406         Q931_HLCHAR_FAX_G4II    = 0x24,
00407         Q931_HLCHAR_T102        = 0x32,
00408         Q931_HLCHAR_T101        = 0x33,
00409         Q931_HLCHAR_F60         = 0x35,
00410         Q931_HLCHAR_X400        = 0x38,
00411         Q931_HLCHAR_X200        = 0x41
00412 } q931_hlchar_t;
00413 
00417 typedef enum {
00418         Q931_UIL1P_V110         = 0x01,
00419         Q931_UIL1P_I460         = 0x01,
00420         Q931_UIL1P_X30          = 0x01,
00421 
00422         Q931_UIL1P_G711U        = 0x02,
00423         Q931_UIL1P_G711A        = 0x03,
00424         Q931_UIL1P_G721         = 0x04,
00425 
00426         Q931_UIL1P_H221         = 0x05,
00427         Q931_UIL1P_H242         = 0x05,
00428 
00429         Q931_UIL1P_H223         = 0x06,
00430         Q931_UIL1P_H245         = 0x06,
00431 
00432         Q931_UIL1P_RATE_ADAP    = 0x07,
00433 
00434         Q931_UIL1P_V120         = 0x08,
00435         Q931_UIL1P_X31          = 0x09
00436 } q931_uil1p_t;
00437 
00441 typedef enum {
00442         Q931_ITC_SPEECH                 = 0x00,
00443         Q931_ITC_UNRESTRICTED           = 0x08,
00444         Q931_ITC_RESTRICTED             = 0x09,
00445         Q931_ITC_3K1_AUDIO              = 0x10,
00446         Q931_ITC_UNRESTRICTED_TONES     = 0x11,
00447         Q931_ITC_VIDEO                  = 0x18
00448 } q931_itc_t;
00449 
00453 typedef enum {
00454         Q931_ITR_PACKET = 0x00,
00455         Q931_ITR_64K    = 0x10,
00456         Q931_ITR_128K   = 0x11,
00457         Q931_ITR_384K   = 0x13,
00458         Q931_ITR_1536K  = 0x15,
00459         Q931_ITR_1920K  = 0x17,
00460         Q931_ITR_MULTI  = 0x18
00461 } q931_itr_t;
00462 
00466 enum {
00467         Q931_CODESET_0 = 0,
00468         Q931_CODESET_1,
00469         Q931_CODESET_2,
00470         Q931_CODESET_3,
00471         Q931_CODESET_4,
00472         Q931_CODESET_5,
00473         Q931_CODESET_6,
00474         Q931_CODESET_7,
00475 };
00476 #define Q931_CODESET_ALL        0x07
00477 
00478 /*
00479  * ITU-T Q.850 cause codes and helper functions
00480  */
00481 #include "Q850.h"
00482 
00483 /*****************************************************************************
00484 
00485   Struct:       Q931mes_Header
00486 
00487   Description:  Used to read the header & message code.
00488 
00489 *****************************************************************************/
00490 /* private */
00491 typedef struct {
00492         L3UINT  Size;           /* Size of message in bytes             */
00493         L3UCHAR ProtDisc;       /* Protocol Discriminator               */
00494         L3UCHAR MesType;        /* Message type                         */
00495         L3UCHAR CRVFlag;        /* Call reference value flag            */
00496         L3INT   CRV;            /* Call reference value                 */
00497 
00498 } Q931mes_Header;
00499 
00500 /*****************************************************************************
00501 
00502   Struct:       Q931mes_Generic
00503 
00504   Description:  Generic header containing all IE's. This is not used, but is
00505                                 provided in case a proprietary variant needs it.
00506 
00507 *****************************************************************************/
00508 /* private (well, that's the goal) */
00509 typedef struct {
00510         L3UINT          Size;           /* Size of message in bytes             */
00511         L3UCHAR         ProtDisc;       /* Protocol Discriminator               */
00512         L3UCHAR         MesType;        /* Message type                         */
00513         L3UCHAR         CRVFlag;        /* Call reference value flag            */
00514         L3INT           CRV;            /* Call reference value                 */
00515 
00516         /* WARNING: don't touch anything above this line (TODO: use Q931mes_Header directly to make sure it's the same) */
00517 
00518         L3UCHAR         Tei;            /* TEI                                  */
00519         L3UCHAR         nr_ie;          /* */
00520 
00521         ie              Shift;
00522         ie              MoreData;
00523         ie              SendComplete;
00524         ie              CongestionLevel;
00525         ie              RepeatInd;
00526 
00527         ie              Segment;        /* Segmented message                    */
00528         ie              BearerCap;      /* Bearer Capability                    */
00529         ie              Cause;          /* Cause                                */
00530         ie              CallState;      /* Call State                           */
00531         ie              CallID;                 /* Call Identity                        */
00532         ie              ChanID;         /* Channel Identification               */
00533         ie              ChangeStatus;   /* Change Staus                         */
00534         ie              ProgInd;        /* Progress Indicator                   */
00535         ie              NetFac;         /* Network Spesific Facilities          */
00536         ie              NotifInd;       /* Notification Indicator               */
00537         ie              Display;        /* Display                              */
00538         ie              DateTime;       /* Date/Time                            */
00539         ie              KeypadFac;      /* Keypad Facility                      */
00540         ie              Signal;         /* Signal                               */
00541         ie              InfoRate;       /* Information rate                     */
00542         ie              EndEndTxDelay;  /* End to End Transmit Delay            */
00543         ie              TransDelSelInd; /* Transmit Delay Sel. and Ind.         */
00544         ie              PackParam;      /* Packed Layer Binary parameters       */
00545         ie              PackWinSize;    /* Packet Layer Window Size             */
00546         ie              PackSize;       /* Packed Size                          */
00547         ie              ClosedUserGrp;  /* Closed User Group                    */
00548         ie              RevChargeInd;   /* Reverse Charging Indicator           */
00549         ie              CalledNum;      /* Called Party Number                  */
00550         ie              CalledSub;      /* Called Party subaddress              */
00551         ie              CallingNum;     /* Calling Party Number                 */
00552         ie              CallingSub;     /* Calling Party Subaddress             */
00553         ie              RedirNum;       /* Redirection Number                   */
00554         ie              TransNetSel;    /* Transmit Network Selection           */
00555         ie              LLRepeatInd;    /* Repeat Indicator 2 LLComp            */
00556         ie              RestartWin;     /* Restart Window                       */
00557         ie              RestartInd;     /* Restart Indicator                    */
00558         ie              LLComp;         /* Low Layer Compatibility              */
00559         ie              HLComp;         /* High Layer Compatibility             */
00560         ie              UserUser;       /* User-user                            */
00561         ie              Escape;         /* Escape for extension                 */
00562         ie              Switchhook;
00563         ie              FeatAct;
00564         ie              FeatInd;
00565         ie              GenericDigits;
00566 
00567         L3UCHAR         buf[1];                 /* Buffer for IE's                                              */
00568 
00569 } Q931mes_Generic;
00570 
00571 /*****************************************************************************
00572 
00573   Struct:       Q931_TrunkInfo
00574 
00575   Description:  TrunkInfo is the struct entry used to store Q.931 related
00576                 information and state for E1/T1/J1 trunks and associated
00577                 channels in the system.
00578 
00579                                 The user should store this information outside this stack
00580                                 and needs to feed the interface functions with a pointer to
00581                                 the TrunkInfo entry.
00582 
00583 *****************************************************************************/
00584 /* public */
00585 typedef struct Q931_TrunkInfo Q931_TrunkInfo_t;
00586 
00590 typedef enum {
00591     Q931_LOG_NONE = -1,
00592     Q931_LOG_EMERG,
00593     Q931_LOG_ALERT,
00594     Q931_LOG_CRIT,
00595     Q931_LOG_ERROR,
00596     Q931_LOG_WARNING,
00597     Q931_LOG_NOTICE,
00598     Q931_LOG_INFO,
00599     Q931_LOG_DEBUG
00600 } Q931LogLevel_t;
00601 
00605 typedef enum {
00606         Q931_TE = 0,                    
00607         Q931_NT                         
00608 } Q931NetUser_t;
00609 
00610 typedef enum {                                  /* Dialect enum */
00611         Q931_Dialect_Q931 = 0,
00612         Q931_Dialect_National,
00613         Q931_Dialect_DMS,
00614         Q931_Dialect_5ESS,
00615         Q931_Dialect_DSS1,              
00617         Q931_Dialect_Count
00618 } Q931Dialect_t;
00619 
00623 typedef enum {
00624         Q931_TrType_E1 = 0,                     
00625         Q931_TrType_T1,                         
00626         Q931_TrType_J1,                         
00627         Q931_TrType_BRI,                        
00628         Q931_TrType_BRI_PTMP                    
00629 } Q931_TrunkType_t;
00630 
00634 typedef enum {
00635         Q931_TrState_NoAlignment = 0,           
00636         Q931_TrState_Aligning,                  
00637         Q931_TrState_Aligned                    
00638 } Q931_TrunkState_t;
00639 
00643 typedef enum {
00644         Q931_ChType_NotUsed = 0,                
00645         Q931_ChType_B,                          
00646         Q931_ChType_D,                          
00647         Q931_ChType_Sync                        
00648 } Q931_ChanType_t;
00649 
00650 /* public: High-level access */
00651 Q931_API void Q931TrunkSetAutoSetupAck(Q931_TrunkInfo_t *trunk, L3BOOL enable);
00652 Q931_API void Q931TrunkSetAutoServiceAck(Q931_TrunkInfo_t *trunk, L3BOOL enable);
00653 Q931_API void Q931TrunkSetAutoRestartAck(Q931_TrunkInfo_t *trunk, L3BOOL enable);
00654 Q931_API void Q931TrunkSetAutoConnectAck(Q931_TrunkInfo_t *trunk, L3BOOL enable);
00655 Q931_API void Q931TrunkSetStatusEnquiry(Q931_TrunkInfo_t *trunk, L3BOOL enable);
00656 Q931_API void Q931TrunkSetIgnoreUnknownMsg(Q931_TrunkInfo_t *trunk, L3BOOL enable);
00657 Q931_API void Q931TrunkSetIgnoreUnknownIEs(Q931_TrunkInfo_t *trunk, L3BOOL enable);
00658 Q931_API void Q931TrunkSetIgnoreIllegalIEs(Q931_TrunkInfo_t *trunk, L3BOOL enable);
00659 
00660 Q931_API L3BOOL Q931TrunkGetAutoSetupAck(Q931_TrunkInfo_t *trunk);
00661 Q931_API L3BOOL Q931TrunkGetAutoServiceAck(Q931_TrunkInfo_t *trunk);
00662 Q931_API L3BOOL Q931TrunkGetAutoRestartAck(Q931_TrunkInfo_t *trunk);
00663 Q931_API L3BOOL Q931TrunkGetAutoConnectAck(Q931_TrunkInfo_t *trunk);
00664 Q931_API L3BOOL Q931TrunkGetStatusEnquiry(Q931_TrunkInfo_t *trunk);
00665 Q931_API L3BOOL Q931TrunkGetIgnoreUnknownMsg(Q931_TrunkInfo_t *trunk);
00666 Q931_API L3BOOL Q931TrunkGetIgnoreUnknownIEs(Q931_TrunkInfo_t *trunk);
00667 Q931_API L3BOOL Q931TrunkGetIgnoreIllegalIEs(Q931_TrunkInfo_t *trunk);
00668 
00669 Q931_API void Q931TrunkSetRelaxedMode(Q931_TrunkInfo_t *trunk, L3BOOL enable);
00670 
00671 struct Q931_Call;
00672 
00673 /* public */
00674 typedef L3INT (*Q931Tx34CB_t)  (void *, struct Q931_Call *call, Q931mes_Generic *, int);
00675 typedef L3INT (*Q931Tx32CB_t)  (void *, L3INT, L3UCHAR, L3UCHAR *, L3INT);
00676 typedef L3INT (*Q931ErrorCB_t) (void *, L3INT, L3INT, L3INT);
00677 typedef L3INT (*Q931LogCB_t)   (void *, Q931LogLevel_t, const char *, L3INT);
00678 
00679 struct Q931Dialect;
00680 
00681 /*****************************************************************************
00682  * Q.931 Call API
00683  *****************************************************************************/
00684 #include "Q931call.h"
00685 
00686 /* public, needs cleanup */
00687 struct Q931_TrunkInfo
00688 {
00689         Q931NetUser_t           NetUser;        /* Network/User Mode.         */
00690         Q931_TrunkType_t        TrunkType;      /* Trunk Line Type.           */
00691         struct Q931Dialect      *Dialect;       /* Dialect handle             */
00692 
00693         Q931Tx34CB_t     Q931Tx34CBProc;
00694         Q931Tx32CB_t     Q931Tx32CBProc;
00695         Q931ErrorCB_t    Q931ErrorCBProc;
00696         Q931LogCB_t      Q931LogCBProc;
00697         void *PrivateData32;
00698         void *PrivateData34;
00699         void *PrivateDataLog;
00700 
00701         Q931CallEventCB_t CallEventCBProc;
00702         void *PrivateDataCallEventCB;
00703 
00704         Q931LogLevel_t   loglevel;
00705 
00706         L3UCHAR     Enabled;        /* Enabled/Disabled                     */
00707                                     /*  0 = Disabled                        */
00708                                     /*  1 = Enabled                         */
00709 
00710         Q931_TrunkState_t TrunkState;
00711 
00712         L3INT   LastCRV;            /* Last used crv for the trunk.         */
00713 
00714         L3UCHAR L3Buf[Q931L4BUF];               /* message buffer for messages to be    */
00715                                     /* send from Q.931 L4.                  */
00716 
00717         L3UCHAR L2Buf[Q931L2BUF];               /* buffer for messages send to L2.      */
00718 
00719         /* The auto flags below switch on/off automatic Ack messages. SETUP ACK */
00720         /* as an example can be sent by the stack in response to SETUP to buy   */
00721         /* time in processing on L4. Setting this to true will cause the stack  */
00722         /* to automatically send this.                                                                                  */
00723         L3INT   flags;
00724 
00725         /* channel array holding info per channel. Usually defined to 32                */
00726         /* channels to fit an E1 since T1/J1 and BRI will fit inside a E1.              */
00727         struct _charray
00728         {
00729                 Q931_ChanType_t ChanType;   /* Unused, B, D, Sync */
00730 
00731                 L3UCHAR Available;          /* Channel Available Flag               */
00732                                             /*  0 : Avaiabled                       */
00733                                             /*  1 : Used                            */
00734 
00735                 L3INT   CRV;                /* Associated CRV                       */
00736 
00737         } ch[Q931MAXCHPERTRUNK];
00738 
00739         /* Active Call information indentified by CRV. See Q931AllocateCRV for  */
00740         /* initialization of call table.                                        */
00741         struct Q931_Call        call[Q931MAXCALLPERTRUNK];      
00742 };
00743 
00744 /*****************************************************************************
00745 
00746   Macro:        GetIETotoSize
00747 
00748   Syntax:       L3INT GetIETotSize(InfoElem ie);
00749 
00750   Description:  Compute the total size in bytes of an info element including
00751                 size of 'header'.
00752 
00753 *****************************************************************************/
00754 #define Q931GetIETotSize(ie) (((ie.InfoID & 0x80) != 0) ? 1 : ie.LenIE) + 2)
00755 
00756 /*****************************************************************************
00757 
00758   Macro:        IsIEPresent
00759 
00760   Syntax:       BOOL IsIEPresent(ie InfoElement);
00761 
00762   Description:  Return TRUE if the Information Element is included.
00763 
00764 *****************************************************************************/
00765 #define Q931IsIEPresent(x) ((x & 0x8000) != 0)
00766 
00767 /*****************************************************************************
00768 
00769   Macro:        GetIEOffset and GetIEValue
00770 
00771   Syntax:       L3INT GetIEOffset(ie InfoElement)
00772                 L3INT GetIEValue(ie InfoElement)
00773 
00774   Description:  Returns the offset (or the value )to the Information Element.
00775 
00776   Note:         GetIEValue assumes that the 15 lsb bit is the value of a
00777                 single octet information element. This macro can not be used
00778                 on a variable information element.
00779 
00780 *****************************************************************************/
00781 #define Q931GetIEOffset(x) (x & 0x7fff)
00782 #define Q931GetIEValue(x)  (x & 0x7fff)
00783 
00784 /*****************************************************************************
00785 
00786   Macro:        Q931GetIEPtr
00787 
00788   Syntax:       void * Q931GetIEPtr(ie InfoElement, L3UCHAR * Buf);
00789 
00790   Description:  Compute a Ptr to the information element.
00791 
00792 *****************************************************************************/
00793 #define Q931GetIEPtr(ie,buf) ((void *)&buf[Q931GetIEOffset(ie)])
00794 
00795 /*****************************************************************************
00796 
00797   Macro:        SetIE
00798 
00799   Syntax:       void SetIE(ie InfoElement, L3INT Offset);
00800 
00801   Description:  Set an information element.
00802 
00803 *****************************************************************************/
00804 #define Q931SetIE(x,o) { x = (ie)(o) | 0x8000; }
00805 
00806 /*****************************************************************************
00807 
00808   Macro:        IsQ931Ext
00809 
00810   Syntax        BOOL IsQ931Ext(L3UCHAR c)
00811 
00812   Description:  Return true Check if the msb (bit 8) is 0. This indicate
00813                 that the octet is extended.
00814 
00815 *****************************************************************************/
00816 #define IsQ931Ext(x) ((x & 0x80) == 0)
00817 
00818 /*****************************************************************************
00819 
00820   Macro:        ieGetOctet
00821 
00822   Syntax:       unsigned L3UCHAR ieGetOctet(L3INT e)
00823 
00824   Description:  Macro to fetch one byte from an integer. Mostly used to
00825                 avoid warnings.
00826 
00827 *****************************************************************************/
00828 #define ieGetOctet(x) ((L3UCHAR)(x))
00829 
00830 /*****************************************************************************
00831 
00832   Macro:        NoWarning
00833 
00834   Syntax:       void NoWarning(x)
00835 
00836   Description:  Macro to suppress unreferenced formal parameter warnings
00837 
00838                 Used during creation of the stack since the stack is
00839                 developed for Warning Level 4 and this creates a lot of
00840                 warning for the initial empty functions.
00841 
00842 *****************************************************************************/
00843 #define NoWarning(x) (x = x)
00844 
00845 /*****************************************************************************
00846 
00847   External references. See Q931.c for details.
00848 
00849 *****************************************************************************/
00850 
00851 #include "Q931ie.h"
00852 
00853 /*****************************************************************************
00854 
00855   Interface Function Prototypes. Implemented in Q931.c
00856 
00857 *****************************************************************************/
00858 /* public */
00859 Q931_API void Q931TimerTick(Q931_TrunkInfo_t *trunk);
00860 
00861 Q931_API L3INT Q931Rx23(Q931_TrunkInfo_t *trunk, L3INT ind, L3UCHAR tei, L3UCHAR * Mes, L3INT Size);
00862 Q931_API L3INT Q931Rx43(Q931_TrunkInfo_t *trunk, Q931mes_Generic *msg, int size);
00863 
00864 void Q931SetError(Q931_TrunkInfo_t *trunk, L3INT ErrID, L3INT ErrPar1, L3INT ErrPar2);  /* private ? */
00865 
00866 Q931_API void Q931Initialize(void);
00867 Q931_API void Q931SetGetTimeCB(L3ULONG (*callback)(void));
00868 
00869 /* private ?? */
00870 Q931_API L3INT Q931GetMesSize(Q931mes_Generic *msg);
00871 Q931_API L3INT Q931InitMesResume(Q931mes_Generic *msg);
00872 Q931_API L3INT Q931InitMesSetup(Q931mes_Generic *msg);
00873 Q931_API L3INT Q931InitMesRestartAck(Q931mes_Generic *msg);
00874 Q931_API L3INT Q931InitMesGeneric(Q931mes_Generic *msg);
00875 
00876 Q931_API L3INT Q931ReleaseCRV(Q931_TrunkInfo_t *trunk, L3INT crv);      /* legacy, public for now, still needed by ozmod_isdn */
00877 
00878 /*****************************************************************************
00879 
00880   Q.931 Low Level API Function Prototyping. Implemented in Q931API.c
00881 
00882 *****************************************************************************/
00883 
00884 /* public, helper functions */
00885 Q931_API ie Q931AppendIE(Q931mes_Generic *msg, L3UCHAR *pi);
00886 
00887 /* remove these? */
00888 Q931_API L3INT Q931InitIEBearerCap(Q931ie_BearerCap *ie);
00889 Q931_API L3INT Q931InitIEChanID(Q931ie_ChanID *ie);
00890 Q931_API L3INT Q931InitIEProgInd(Q931ie_ProgInd *ie);
00891 Q931_API L3INT Q931InitIENetFac(Q931ie_NetFac *ie);
00892 Q931_API L3INT Q931InitIEDisplay(Q931ie_Display *ie);
00893 Q931_API L3INT Q931InitIEDateTime(Q931ie_DateTime *ie);
00894 Q931_API L3INT Q931InitIEKeypadFac(Q931ie_KeypadFac *ie);
00895 Q931_API L3INT Q931InitIESignal(Q931ie_Signal *ie);
00896 Q931_API L3INT Q931InitIECallingNum(Q931ie_CallingNum *ie);
00897 Q931_API L3INT Q931InitIECallingSub(Q931ie_CallingSub *ie);
00898 Q931_API L3INT Q931InitIECalledNum(Q931ie_CalledNum *ie);
00899 Q931_API L3INT Q931InitIECalledSub(Q931ie_CalledSub *ie);
00900 Q931_API L3INT Q931InitIETransNetSel(Q931ie_TransNetSel *ie);
00901 Q931_API L3INT Q931InitIELLComp(Q931ie_LLComp *ie);
00902 Q931_API L3INT Q931InitIEHLComp(Q931ie_HLComp *ie);
00903 
00904 /* hmm... */
00905 L3INT Q931Disconnect(Q931_TrunkInfo_t *trunk, L3INT iTo, L3INT iCRV, L3INT iCause);
00906 L3INT Q931Release(Q931_TrunkInfo_t *trunk, struct Q931_Call *call, L3UCHAR causeval);
00907 L3INT Q931ReleaseComplete(Q931_TrunkInfo_t *trunk, struct Q931_Call *call, L3UCHAR causeval);
00908 L3INT Q931AckRestart(Q931_TrunkInfo_t *trunk, Q931mes_Generic *msg);
00909 L3INT Q931AckConnect(struct Q931_Call *call);
00910 L3INT Q931AckSetup(Q931_TrunkInfo_t *trunk, Q931mes_Generic *msg);
00911 L3INT Q931AckService(Q931_TrunkInfo_t *trunk, Q931mes_Generic *msg);
00912 
00913 /* public */
00914 Q931_API L3INT Q931InitTrunk(Q931_TrunkInfo_t *trunk,
00915                                                 Q931Dialect_t Dialect,
00916                                                 Q931NetUser_t NetUser,
00917                                                 Q931_TrunkType_t TrunkType,
00918                                                 Q931Tx34CB_t Q931Tx34CBProc,
00919                                                 Q931Tx32CB_t Q931Tx32CBProc,
00920                                                 Q931ErrorCB_t Q931ErrorCBProc,
00921                                                 void *PrivateData32,
00922                                                 void *PrivateData34);
00923 Q931_API L3INT Q931Start(Q931_TrunkInfo_t *trunk);
00924 
00925 /* public */
00926 Q931_API void Q931SetLogCB(Q931_TrunkInfo_t *trunk, Q931LogCB_t func, void *priv);
00927 Q931_API void Q931SetLogLevel(Q931_TrunkInfo_t *trunk, Q931LogLevel_t level);
00928 Q931_API Q931LogLevel_t Q931GetLogLevel(Q931_TrunkInfo_t *trunk);
00929 Q931_API const char * Q931GetLogLevelName(Q931_TrunkInfo_t *trunk);
00930 
00931 /* private? clashing with Q931SetHeaderSpace() */
00932 //void Q931SetL4HeaderSpace(L3INT space);
00933 void Q931SetL2HeaderSpace(L3INT space);
00934 
00935 /* bad example function for new l4 call control api */
00936 L3INT Q931CallSendStatus(const struct Q931_Call *call, const L3UCHAR causeval);
00937 
00938 #endif /* _Q931_NL */