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
|
/**************************************************************************
*** COPYRIGHT (c) 2002 by TransNexus, Inc. ***
*** ***
*** This software is property of TransNexus, Inc. ***
*** This software is freely available under license from TransNexus. ***
*** The license terms and conditions for free use of this software by ***
*** third parties are defined in the OSP Toolkit Software License ***
*** Agreement (LICENSE.txt). Any use of this software by third ***
*** parties, which does not comply with the terms and conditions of the ***
*** OSP Toolkit Software License Agreement is prohibited without ***
*** the prior, express, written consent of TransNexus, Inc. ***
*** ***
*** Thank you for using the OSP ToolKit(TM). Please report any bugs, ***
*** suggestions or feedback to support@transnexus.com ***
*** ***
**************************************************************************/
/*
* nonblocking.h - Structures and prototypes for non-blocking.
*
* This module implements non-blocking API on top of blocking
* OSP Toolkit API.
*
* Before the non-blocking API may be used, an instance of
* NonBlockingQueueMonitor must be created using NonBlockingQueueMonitorNew.
* This method allocates space, initializes private variables and starts
* consumer/work threads which will be responsible for making blocking calls.
* NOTE: Number of work/consumer threads should not exceed the maximum number
* of HTTP connections set in the OSPPProviderNew.
*
* When the non-blocking API is no longer needed the NonBlockingQueueMonitor
* should be deleted using NonBlockingQueueMonitorDelete. This method
* signals that the shutdown is in progress (which prevets non-blocking API
* from accepting any more transactions), blocks while current transactions
* are still being processed, releases consumer/work threads and deallocates space.
*
* Method NonBlockingQueueMonitorBlockWhileQueueNotEmpty allows the caller to block
* while there are transactions being processed. NOTE: This function call does not
* prevent from adding more non-blocking transactions and maybe starved if there is a
* sufficient flow of transactions.
*
* There are 2 non-blocking methods OSPPTransactionRequestAuthorisation_nb, and
* OSPPTransactionReportUsage_nb which correspond to the OSP Toolkit API methods
* OSPPTransactionRequestAuthorisation and OSPPTransactionReportUsage respectively.
* The non-blocking methods follow the same naming conventions with an exception of
* having a postfix - '_nb'.
* The non-blocking methods, in addition to expecting the same variables as their
* blocking counterparts, expect 2 variables of types: NBMONITOR* and int*.
* The 1st one is a pointer to the NonBlockingQueueMonitor (which should have been
* initialized using NonBlockingQueueMonitorNew).
* The 2nd one is a pointer to the space where return value from the blocking
* function should be stored. The caller is responsible for allocating space and
* passing a valid pointer. Initially the value is set to OSPC_REPORT_USAGE_BLOCK or
* OSPC_AUTH_REQUEST_BLOCK to indicate that a blocking call is in progress. When
* the blocking function returns and the value is set to the actual return value.
*
* NOTE: (1) The caller must not delete transaction handle or any other resources that may
* be used by the blocking functions while a transaction is in progress. Failing to do
* so will result in unpredictable behavior. (2) The caller must not attempt to call
* OSPPTransactionGetFirstDestination while OSPPTransactionRequestAuthorisation is still in
* progress.
*/
#ifndef _NONBLOCKING_H
#define _NONBLOCKING_H
#include "osp/osp.h"
#include "syncque.h"
/*
* non-blocking monitor typedef
*/
#define MAX_WORK_THREAD_NUM 100
typedef struct _NBMONITOR {
SYNCQUEUE *SyncQue;
OSPTTHREADID WorkThreadIDs[MAX_WORK_THREAD_NUM];
unsigned TimeToShutDown;
OSPTMUTEX Mutex;
OSPTCONDVAR CondVarNoActiveWorkThreads;
unsigned NumberOfWorkThreads;
unsigned NumberOfActiveWorkThreads;
/* apply only to Auth Requests */
unsigned MaxQueSize;
unsigned MaxQueWaitMS;
} NBMONITOR;
#ifdef __cplusplus
extern "C" {
#endif
int NonBlockingQueueMonitorNew(
NBMONITOR **nbMonitor, /* In\Out - NBMonitor Pointer */
unsigned NumberOfWorkThreads, /* Max number of concurent tool kit requets */
unsigned MaxQueSize, /* Apply only to AuthReq, limit number of requets in the queue */
unsigned MaxQueWaitMS); /* Apply only to AuthReq, queue expiration time in ms */
int NonBlockingQueueMonitorBlockWhileQueueNotEmpty(NBMONITOR *nbMonitor); /* In - NBMonitor Pointer */
int NonBlockingQueueMonitorDelete(NBMONITOR **nbMonitor); /* In\Out - NBMonitor Pointer */
int OSPPTransactionRequestAuthorisation_nb(
NBMONITOR *nbMonitor, /* In - NBMonitor Pointer */
int ShouldBlock, /* In - 1 WILL block, 0 - will NOT block */
int *OSPErrorCode, /* Out- Error code returned by the blocking function */
OSPTTRANHANDLE ospvTransaction, /* In - Transaction Handle */
const char *ospvSource, /* In - Source of call */
const char *ospvSourceDevice, /* In - SourceDevice of call */
const char *ospvCallingNumber, /* In - Calling number */
OSPE_NUMBER_FORMAT ospvCallingNumberFormat, /* In - Calling number Format */
const char *ospvCalledNumber, /* In - Called number */
OSPE_NUMBER_FORMAT ospvCalledNumberFormat, /* In - Called number */
const char *ospvUser, /* In - End user (optional) */
unsigned ospvNumberOfCallIds, /* In - Number of call identifiers */
OSPT_CALL_ID *ospvCallIds[], /* In - List of call identifiers */
const char *ospvPreferredDestinations[], /* In - List of preferred destinations for call */
unsigned *ospvNumberOfDestinations, /* In\Out - Max number of destinations \ Actual number of dests authorised */
unsigned *ospvSizeOfDetailLog, /* In\Out - Max size of detail log \ Actual size of detail log */
void *ospvDetailLog); /* In\Out - Location of detail log storage */
int OSPPTransactionReportUsage_nb(
NBMONITOR *nbMonitor, /* In - NBMonitor Pointer */
int ShouldBlock, /* In - 1 WILL block, 0 - will NOT block */
int *OSPErrorCode, /* Out- Error code returned by the blocking function */
OSPTTRANHANDLE ospvTransaction, /* In - Transaction handle */
unsigned ospvDuration, /* In - Length of call */
OSPTTIME ospvStartTime, /* In - StartTime of call */
OSPTTIME ospvEndTime, /* In - EndTime of call */
OSPTTIME ospvAlertTime, /* In - AlertTime of call */
OSPTTIME ospvConnectTime, /* In - ConnectTime of call */
OSPTBOOL ospvHasPDDInfo, /* In - Is PDD present */
unsigned ospvPostDialDelay, /* In - PDD in milliseconds */
OSPE_RELEASE ospvReleaseSource, /* In - Rel Src */
const char *ospvConferenceId, /* In - Conference Id */
int ospvLossPacketsSent, /* In - Packets not received by peer */
int ospvLossFractionSent, /* In - Fraction of packets not received by peer */
int ospvLossPacketsReceived, /* In - Packets not received that were expected */
int ospvLossFractionReceived, /* In - Fraction of packets expected but not received */
unsigned *ospvSizeOfDetailLog, /* In/Out - Max size of detail log \ Actual size of detail log */
void *ospvDetailLog); /* Out - Pointer to detail log storage */
int OSPPTransactionIndicateCapabilities_nb(
NBMONITOR *nbMonitor, /* In - NBMonitor Pointer */
int ShouldBlock, /* In - 1 WILL block, 0 - will NOT block */
int *OSPErrorCode, /* Out- Error code returned by the blocking function */
OSPTTRANHANDLE ospvTransaction, /* In - Transaction Handle */
const char *ospvSource, /* In - Source of call */
const char *ospvSourceDevice, /* In - SourceDevice of call */
const char *ospvSourceNetworkId, /* In - NetworkId of call */
unsigned ospvAlmostOutOfResource, /* In - A Boolean flag indicating device's availability */
unsigned *ospvSizeOfDetailLog, /* In\Out - Max size of detail log \ Actual size of detail log */
void *ospvDetailLog); /* In\Out - Location of detail log storage */
int OSPPTransactionValidateAuthorisation_nb(
NBMONITOR *nbMonitor, /* In - NBMonitor Pointer */
int ShouldBlock, /* In - 1 WILL block, 0 - will NOT block */
int *OSPErrorCode, /* Out- Error code returned by the blocking function */
OSPTTRANHANDLE ospvTransaction, /* In - Transaction handle */
const char *ospvSource, /* In - Source of call */
const char *ospvDestination, /* In - Destination for call */
const char *ospvSourceDevice, /* In - SourceDevice of call */
const char *ospvDestinationDevice, /* In - DestinationDevice for call */
const char *ospvCallingNumber, /* In - Calling number string */
OSPE_NUMBER_FORMAT ospvCallingNumberFormat, /* In - Calling number Format */
const char *ospvCalledNumber, /* In - Called number string */
OSPE_NUMBER_FORMAT ospvCalledNumberFormat, /* In - Called number Format */
unsigned ospvSizeOfCallId, /* In - Size of call id value */
const void *ospvCallId, /* In - Call Id for this call */
unsigned ospvSizeOfToken, /* In - Size of authorization token */
const void *ospvToken, /* In - Authorization token */
unsigned *ospvAuthorised, /* Out - Call authorization indicator */
unsigned *ospvTimeLimit, /* Out - Number of seconds call is authorized for */
unsigned *ospvSizeOfDetailLog, /* In\Out - Max size of detail log \ Actual size of detail log */
void *ospvDetailLog, /* In\Out - Location of detail log storage */
unsigned ospvTokenAlgo); /* In - Algorithm to be used for Validating Token */
#ifdef __cplusplus
}
#endif
#endif /* _NONBLOCKING_H */
|
