aboutsummaryrefslogtreecommitdiffstats
path: root/addons/ooh323c/src/ooGkClient.h
blob: fa52f3e9283aee7386f65da3696159601eee7065 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
/*
 * Copyright (C) 2005 by Page Iberica, S.A.
 * Copyright (C) 2005 by Objective Systems, Inc.
 *
 * This software is furnished under an open source license and may be 
 * used and copied only in accordance with the terms of this license. 
 * The text of the license may generally be found in the root 
 * directory of this installation in the COPYING file.  It 
 * can also be viewed online at the following URL:
 *
 *   http://www.obj-sys.com/open/license.html
 *
 * Any redistributions of this file including modified versions must 
 * maintain this copyright notice.
 *
 *****************************************************************************/

/**
 * @file ooGkClient.h 
 * This file contains functions to support RAS protocol. 
 *
 *
 */
#ifndef _OOGKCLIENT_H_
#define _OOGKCLIENT_H_

#include "ooasn1.h"
#include "ootypes.h"
#include "H323-MESSAGES.h"

#ifdef __cplusplus
extern "C" {
#endif

#ifndef EXTERN
#ifdef MAKE_DLL
#define EXTERN __declspec(dllexport)
#else
#define EXTERN
#endif /* _WIN32 */
#endif /* EXTERN */


/*-------------------------------------------------------------------*/
/*  Public definitions                                               */
/*-------------------------------------------------------------------*/



#define MAX_IP_LEN 15
#define DEFAULT_GKPORT 1719
#define MULTICAST_GKADDRESS "224.0.1.41"
#define MULTICAST_GKPORT 1718
#define DEFAULT_BW_REQUEST  100000

/* Various timeouts in seconds */
#define DEFAULT_REG_TTL 300
#define DEFAULT_TTL_OFFSET 20
#define DEFAULT_ARQ_TIMEOUT 5
#define DEFAULT_DRQ_TIMEOUT 5
#define DEFAULT_GRQ_TIMEOUT 15
#define DEFAULT_RRQ_TIMEOUT 10

/* Number of retries before giving up */
#define OO_MAX_GRQ_RETRIES 3
#define OO_MAX_RRQ_RETRIES 3
#define OO_MAX_ARQ_RETRIES 3

/* Gk Client timers */
#define OO_GRQ_TIMER (1<<0)
#define OO_RRQ_TIMER (1<<1)
#define OO_REG_TIMER (1<<2)
#define OO_ARQ_TIMER (1<<3)
#define OO_DRQ_TIMER (1<<4)

/** 
 * @defgroup gkclient Gatekeeper client
 * @{
 */

struct OOH323CallData;
struct ooGkClient;
struct RasCallAdmissionInfo;

typedef struct ooGkClientTimerCb{
   int timerType;
   struct ooGkClient *pGkClient;
   struct RasCallAdmissionInfo *pAdmInfo;
}ooGkClientTimerCb;

enum RasGatekeeperMode {
   RasNoGatekeeper = 0,
   RasDiscoverGatekeeper = 1,
   RasUseSpecificGatekeeper = 2,
};

enum RasCallType{
   RasPointToPoint =0,
   RasOneToN,
   RasnToOne,
   RasnToN,
};


enum OOGkClientState {
   GkClientIdle = 0,
   GkClientDiscovered, /* Gk Discovery is complete */
   GkClientRegistered, /* registered with gk */
   GkClientUnregistered,
   GkClientGkErr,/*Gk is not responding, in discover mode can look for new GK*/
   GkClientFailed
};
   

typedef struct RasGatekeeperInfo
{
   ASN1BOOL willRespondToIRR;
   H225UUIEsRequested uuiesRequested;
   H225BandWidth bw;
   H225RegistrationConfirm_preGrantedARQ preGrantedARQ;
}RasGatekeeperInfo;

/**
 *  Call Admission Information
 */
typedef struct RasCallAdmissionInfo
{
   struct OOH323CallData *call;
   unsigned int retries;
   unsigned short requestSeqNum;
   ASN1USINT irrFrequency;
} RasCallAdmissionInfo;

struct OOAliases;

/**
 * NOTE- This functionality is not yet fully completed.
 * This is a callback function which is triggered when registration confirm 
 * message is received from the gatekeeper. The first parameter is the message
 * received. The second parameter provides updated list of aliases after the 
 * message was processed by the stack.
 * @param rcf  Handle to the received registration confirm message
 */
typedef int (*cb_OnReceivedRegistrationConfirm)
     (H225RegistrationConfirm *rcf, struct OOAliases *aliases);


/**
 * NOTE- This functionality is not yet fully completed.
 * This is a callback function which is triggered when unregistration confirm 
 * message is received. The first parameter is the message received. The second
 * parameter provides updated list of aliases after the message was processed 
 * by the stack.
 */
typedef int (*cb_OnReceivedUnregistrationConfirm)
     (H225UnregistrationConfirm *ucf, struct OOAliases *aliases);

/**
 * NOTE- This functionality is not yet fully completed.
 * This is a callback function which is triggered when unregistration request 
 * message is received. The first parameter is the message received. The second
 * parameter provides the list of aliases requested to be unregistered.
 */
typedef int (*cb_OnReceivedUnregistrationRequest)
     (H225UnregistrationRequest *urq, struct OOAliases *aliases);

typedef struct OOGKCLIENTCALLBACKS{
   cb_OnReceivedRegistrationConfirm onReceivedRegistrationConfirm;
   cb_OnReceivedUnregistrationConfirm onReceivedUnregistrationConfirm;
   cb_OnReceivedUnregistrationRequest onReceivedUnregistrationRequest;
}OOGKCLIENTCALLBACKS;

/**
 * Structure to store all the configuration information for the gatekeeper
 * client. Gatekeeper client is responsible for all the communication with
 * a gatekeeper.
 */
typedef struct ooGkClient{
   ASN1BOOL discoveryComplete;
   OOCTXT ctxt;
   OOCTXT msgCtxt;
   OOSOCKET rasSocket;
   int localRASPort;
   char localRASIP[20];
   char gkRasIP[20];
   char gkCallSignallingIP[20];
   RasGatekeeperInfo gkInfo;
   int gkRasPort;
   int gkCallSignallingPort;
   unsigned short requestSeqNum;
   enum RasGatekeeperMode gkMode; /* Current Gk mode */
   struct timeval registrationTime;
   H225GatekeeperIdentifier gkId;
   H225EndpointIdentifier endpointId;
   DList callsPendingList;
   DList callsAdmittedList;
   DList timerList;
   OOGKCLIENTCALLBACKS callbacks;
   ASN1UINT grqRetries;
   ASN1UINT rrqRetries;
   ASN1UINT grqTimeout;
   ASN1UINT rrqTimeout;
   ASN1UINT regTimeout;
   ASN1UINT arqTimeout;
   ASN1UINT drqTimeout;
   enum OOGkClientState  state;
} ooGkClient;

struct OOAliases;
struct OOH323CallData;

/**
 * This function is used to initialize the Gatekeeper client.If an application
 * wants to use gatekeeper services, it should call this function immediately
 * after initializing the H323 EndPoint.
 * @param eGkMode          Gatekeeper mode.
 * @param szGkAddr         Dotted gk ip address, if gk has to be specified.
 * @param iGkPort          Gk port.
 *
 * @return                 OO_OK, on success. OO_FAILED, on failure.
 * 
 */
EXTERN int ooGkClientInit
   (enum RasGatekeeperMode eGkMode, char *szGkAddr, int iGkPort );

/**
 * This function is used to print the gatekeeper client configuration 
 * information to log.
 * @param pGkClient        Handle to gatekeeper client.
 */
EXTERN void ooGkClientPrintConfig(ooGkClient *pGkClient);

/**
 * This function is used to destroy Gatekeeper client. It releases all the 
 * associated memory.
 *
 * @return     OO_OK, on success. OO_FAILED, on failure.
 */
EXTERN int ooGkClientDestroy(void);

/**
 * This function is used to start the Gatekeeper client functionality.
 * @param pGkClient        Pointer to the Gatekeeper Client.
 * 
 * @return                 OO_OK, on success. OO_FAILED, on failure.
 */
EXTERN int ooGkClientStart(ooGkClient *pGkClient);

/**
 * This function is invoked to set a gatekeeper mode. 
 * @param pGkClient Handle to gatekeeper client. 
 * @param eGkMode   Gatekeeper mode selected. One of the following: 
 *                    - RasNoGatekeeper (DEFAULT), No Gatekeeper.              
 *                    - RasDiscoverGatekeeper, to discover a gatekeeper 
 *                      automatically.
 *                    - RasUseSpecificGatekeeper, to use a specific gatekeeper.
 * @param szGkAddr  Gatekeeper address (only when using specific gatekeeper).
 * @param iGkPort   Gatekeeper RAS port
 *
 * @return         Completion status - OO_OK on success, OO_FAILED on failure
 */
EXTERN int ooGkClientSetGkMode(ooGkClient *pGkClient, 
                               enum RasGatekeeperMode eGkMode, char *szGkAddr, 
                               int iGkPort );

/**
 * This function is used to create a RAS channel for the gatekeeper.
 * @param pGkClient     Pointer to the Gatekeeper client for which RAS channel
 *                      has to be created.
 *
 * @return              OO_OK, on success. OO_FAILED, on failure.
 */
EXTERN int ooGkClientCreateChannel(ooGkClient *pGkClient);

/**
 * This function is used to close a RAS channel of the gatekeeper client.
 * @param pGkClient    Pointer to the gatekeeper client.
 *
 * @return             OO_OK, on success. OO_FAILED, on failure.
 */
EXTERN int ooGkClientCloseChannel(ooGkClient *pGkClient);


/**
 * This function is used to fill endpoint's vendor information into vendor
 * identifier.
 * @param pGkClient    Pointer to gatekeeper client.
 * @param psVendor     Pointer to vendor identifier to be filled.
 * 
 */
EXTERN void ooGkClientRasFillVendor
   (ooGkClient *pGkClient, H225VendorIdentifier *psVendor);


/**
 * This function is invoked to receive data on Gatekeeper client's RAS channel.
 * @param pGkClient    Handle to Gatekeeper client for which message has to be
 *                     received.
 *
 * @return             Completion status - OO_OK on success, OO_FAILED on 
 *                     failure
 */
EXTERN int ooGkClientReceive(ooGkClient *pGkClient);


/**
 * This function is used to handle a received RAS message by a gatekeeper 
 * client.
 * @param pGkClient   Handle to gatekeeper client.
 * @param pRasMsg     Handle to received Ras message.
 *
 * @return            OO_OK, on success. OO_FAILED, on failure.
 */
EXTERN int ooGkClientHandleRASMessage
   (ooGkClient *pGkClient, H225RasMessage *pRasMsg);


/**
 * This function is used to send a message on Gatekeeper clien't RAS channel.
 * @param pGkClient   Handle to the gatekeeper client.
 * @param pRasMsg     Handle to Ras message to be sent.
 *
 * @return            OO_OK, on success. OO_FAILED, otherwise. 
 */
EXTERN int ooGkClientSendMsg(ooGkClient *pGkClient, H225RasMessage *pRasMsg);


/**
 * This function is used to send Gatekeeper request message.
 * @param pGkClient  Handle to gatekeeper client for which GRQ message has to 
 *                   be sent.
 *
 * @return           OO_OK, on success. OO_FAILED, otherwise.
 */
EXTERN int ooGkClientSendGRQ(ooGkClient *pGkClient);


/**
 * This function is used to handle a received gatekeeper reject message.
 * @param pGkClient          Handle to gatekeeper client.
 * @param pGatekeeperReject  Handle to received reject message.
 *
 * @return                   OO_OK, on success. OO_FAILED, otherwise.
 */
EXTERN int ooGkClientHandleGatekeeperReject
   (ooGkClient *pGkClient, H225GatekeeperReject *pGatekeeperReject);

/**
 * This function is used to handle a received gatekeeper confirm message.
 * @param pGkClient          Handle to gatekeeper client.
 * @param pGatekeeperConfirm Handle to received confirmed message.
 *
 * @return                   OO_OK, on success. OO_FAILED, otherwise.
 */
EXTERN int ooGkClientHandleGatekeeperConfirm
   (ooGkClient *pGkClient, H225GatekeeperConfirm *pGatekeeperConfirm);


/**
 * This function is used to send Registration request message.
 * @param pGkClient  Handle to gatekeeper client for which RRQ message has to 
 *                   be sent.
 * @param keepAlive  Indicates whether keepalive lightweight registration has 
 *                   to be sent.
 *
 * @return           OO_OK, on success. OO_FAILED, otherwise.
 */
EXTERN int ooGkClientSendRRQ(ooGkClient *pGkClient, ASN1BOOL keepAlive);

/**
 * This function is used to handle a received registration confirm message.
 * @param pGkClient            Handle to gatekeeper client.
 * @param pRegistrationConfirm Handle to received confirmed message.
 *
 * @return                     OO_OK, on success. OO_FAILED, otherwise.
 */
EXTERN int ooGkClientHandleRegistrationConfirm
   (ooGkClient *pGkClient, H225RegistrationConfirm *pRegistrationConfirm);

/**
 * This function is used to handle a received registration reject message.
 * @param pGkClient           Handle to gatekeeper client.
 * @param pRegistrationReject Handle to received reject message.
 *
 * @return                    OO_OK, on success. OO_FAILED, otherwise.
 */
EXTERN int ooGkClientHandleRegistrationReject
   (ooGkClient *pGkClient, H225RegistrationReject *pRegistrationReject);


/**
 * This function is used to send UnRegistration request message.
 * @param pGkClient  Handle to gatekeeper client for which URQ message has to 
 *                   be sent.
 * @param aliases    List of aliases to be unregistered. NULL, if all the 
 *                   aliases have to be unregistered.
 *
 * @return           OO_OK, on success. OO_FAILED, otherwise.
 */
EXTERN int ooGkClientSendURQ(ooGkClient *pGkClient, struct OOAliases *aliases);

/**
 * This function is used to handle a received Unregistration request message.
 * @param pGkClient              Handle to gatekeeper client.
 * @param punregistrationRequest Handle to received unregistration request.
 *
 * @return                   OO_OK, on success. OO_FAILED, otherwise.
 */
EXTERN int ooGkClientHandleUnregistrationRequest
   (ooGkClient *pGkClient, H225UnregistrationRequest *punregistrationRequest);


/**
 * This function is used to send an unregistration confirm messsage to 
 * gatekeeper.
 * @param pGkClient        Handle to gatekeeper client.
 * @param reqNo            Request Sequence number for the confirm message.
 *
 * @return                 OO_OK, on success. OO_FAILED, on failure.
 */
EXTERN int ooGkClientSendUnregistrationConfirm(ooGkClient *pGkClient, 
                                                               unsigned reqNo);

/**
 * This function is invoked to request bandwith admission for a call. 
 * @param pGkClient     Gatekeeper client to be used
 * @param call          Handle to the call.
 * @param retransmit    Indicates whether new call or retransmitting for 
 *                      existing call.
 *
 * @return              OO_OK, on success. OO_FAILED, on failure.
 */
EXTERN int ooGkClientSendAdmissionRequest
   (ooGkClient *pGkClient, struct OOH323CallData *call, ASN1BOOL retransmit);

/**
 * This function is used to handle a received Admission confirm message.
 * @param pGkClient         Handle to gatekeeper client.
 * @param pAdmissionConfirm Handle to received confirmed message.
 *
 * @return                  OO_OK, on success. OO_FAILED, otherwise.
 */
EXTERN int ooGkClientHandleAdmissionConfirm
   (ooGkClient *pGkClient, H225AdmissionConfirm *pAdmissionConfirm);


/**
 * This function is used to handle a received Admission Reject message. It 
 * finds the associated call and marks it for cleaning with appropriate 
 * call end reason code.
 * @param pGkClient         Handle to Gatekeeper client.
 * @param pAdmissionReject  Handle to received admission reject message.
 *
 * @return                  OO_OK, on success. OO_FAILED, on failure.
 */
EXTERN int ooGkClientHandleAdmissionReject
   (ooGkClient *pGkClient, H225AdmissionReject *pAdmissionReject);

/**
 * This function is invoked to request call disengage to gatekeeper. 
 * @param pGkClient  Gatekeeper client to be used.
 * @param call       Call Handle
 *
 * @return           Completion status - OO_OK on success, OO_FAILED on failure
 */
EXTERN int ooGkClientSendDisengageRequest
   (ooGkClient *pGkClient, struct OOH323CallData *call);

/**
 * This function is used to handle a received disengage confirm message.
 * @param pGkClient            Handle to gatekeeper client.
 * @param pDCF                 Handle to received confirmed message.
 *
 * @return                     OO_OK, on success. OO_FAILED, otherwise.
 */
EXTERN int ooGkClientHandleDisengageConfirm
   (ooGkClient *pGkClient, H225DisengageConfirm *pDCF);

/**
 * This function is used to handle an expired registration request timer.
 * @param pdata     Handle to callback data
 *
 * @return          OO_OK, on success. OO_FAILED, on failure.
 */
EXTERN int ooGkClientRRQTimerExpired(void*pdata);

/**
 * This function is used to handle an expired gatekeeper request timer.
 * @param pdata     Handle to callback data
 *
 * @return          OO_OK, on success. OO_FAILED, on failure.
 */
EXTERN int ooGkClientGRQTimerExpired(void* pdata);

/**
 * This function is used to handle an expired registration time-to-live timer.
 * @param pdata     Handle to callback data
 *
 * @return          OO_OK, on success. OO_FAILED, on failure.
 */
EXTERN int ooGkClientREGTimerExpired(void *pdata);

/**
 * This function is used to handle an expired admission request timer.
 * @param pdata     Handle to callback data
 *
 * @return          OO_OK, on success. OO_FAILED, on failure.
 */
EXTERN int ooGkClientARQTimerExpired(void* pdata);

/**
 * This function is used to clean call related data from gatekeeper client.
 * @param pGkClient  Handle to the gatekeeper client.
 * @param call       Handle to the call to be cleaned.
 *
 * @return           OO_OK, on success. OO_FAILED, on failure.
 */
EXTERN int ooGkClientCleanCall(ooGkClient *pGkClient, struct OOH323CallData *call);

/**
 * This function is used to handle gatekeeper client failure or gatekeeper 
 * failure which can be detected by unresponsiveness of gk.
 * @param pGkClient  Handle to gatekeeper client.
 *
 * @return           OO_OK, on success. OO_FAILED, on failure.
 */
EXTERN int ooGkClientHandleClientOrGkFailure(ooGkClient *pGkClient);

/**
 * This function is used to update the registration status of aliases.
 * @param pGkClient  Handle to the GK client.
 * @param pAddresses List of newly registered addresses. NULL means all
 *                   aliases have been successfully registered.
 * @param registered Indicates whether aliases are registered or unregistered.
 *
 * @return           OO_OK, on success. OO_FAILED, on failure.
 */
EXTERN int ooGkClientUpdateRegisteredAliases
   (ooGkClient *pGkClient, H225_SeqOfH225AliasAddress *pAddresses, 
    OOBOOL registered);

/**
 * This function is used internally to set Gatekeeper Clients callbacks.
 * Note: This functionality is not yet fully supported
 * @param pGkClient  Handle to the GK client.
 * @param callbacks  Callback structure contatining various gatekeeper client
 *                   callbacks.
 * @return           OO_OK, on success. OO_FAILED, on failure.
 */
int ooGkClientSetCallbacks
   (ooGkClient *pGkClient, OOGKCLIENTCALLBACKS callbacks);
/** 
 * @} 
 */

#ifdef __cplusplus
}
#endif

#endif /* __GKCLIENT_H */