OPAL Version 3.10.4

- Main Page
- Related Pages
- Namespaces
- Data Structures
- Files

- File List
- Globals

peclient.h
Go to the documentation of this file.
1 /*
2 * peclient.h
3 *
4 * H.323 Annex G Peer Element client protocol handler
5 *
6 * Open H323 Library
7 *
8 * Copyright (c) 2003 Equivalence Pty. Ltd.
9 *
10 * The contents of this file are subject to the Mozilla Public License
11 * Version 1.0 (the "License"); you may not use this file except in
12 * compliance with the License. You may obtain a copy of the License at
13 * http://www.mozilla.org/MPL/
14 *
15 * Software distributed under the License is distributed on an "AS IS"
16 * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
17 * the License for the specific language governing rights and limitations
18 * under the License.
19 *
20 * The Original Code is Open H323 Library.
21 *
22 * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
23 *
24 * Contributor(s): ______________________________________.
25 *
26 * $Revision: 24178 $
27 * $Author: rjongbloed $
28 * $Date: 2010-04-05 19:10:56 -0500 (Mon, 05 Apr 2010) $
29 */
30
31 #ifndef OPAL_H323_PECLIENT_H
32 #define OPAL_H323_PECLIENT_H
33
34 #ifdef P_USE_PRAGMA
35 #pragma interface
36 #endif
37
38 #include <opal/buildopts.h>
39
40 #if OPAL_H501
41
42 #include <h323/h323annexg.h>
43 #include <h323/h323ep.h>
44
45 #include <ptlib/safecoll.h>
46
47
48 class H323PeerElement;
49
50
52
53 class H501Transaction : public H323Transaction
54 {
55 PCLASSINFO(H501Transaction, H323Transaction);
56 public:
57 H501Transaction(
58 H323PeerElement & pe,
59 const H501PDU & pdu,
60 PBoolean hasReject
61 );
62
63 virtual H323TransactionPDU * CreateRIP(
64 unsigned sequenceNumber,
65 unsigned delay
66 ) const;
67
68 virtual H235Authenticator::ValidationResult ValidatePDU() const;
69
70 H501_MessageCommonInfo & requestCommon;
71 H501_MessageCommonInfo & confirmCommon;
72
73 protected:
74 H323PeerElement & peerElement;
75 };
76
77
79
80 class H501ServiceRequest : public H501Transaction
81 {
82 PCLASSINFO(H501ServiceRequest, H501Transaction);
83 public:
84 H501ServiceRequest(
85 H323PeerElement & pe,
86 const H501PDU & pdu
87 );
88
89 #if PTRACING
90 virtual const char * GetName() const;
91 #endif
92 virtual void SetRejectReason(
93 unsigned reasonCode
94 );
95
96 H501_ServiceRequest & srq;
97 H501_ServiceConfirmation & scf;
98 H501_ServiceRejection & srj;
99
100 protected:
101 virtual Response OnHandlePDU();
102 };
103
104
106
107 class H501DescriptorUpdate : public H501Transaction
108 {
109 PCLASSINFO(H501DescriptorUpdate, H501Transaction);
110 public:
111 H501DescriptorUpdate(
112 H323PeerElement & pe,
113 const H501PDU & pdu
114 );
115
116 #if PTRACING
117 virtual const char * GetName() const;
118 #endif
119 virtual void SetRejectReason(
120 unsigned reasonCode
121 );
122
123 H501_DescriptorUpdate & du;
124 H501_DescriptorUpdateAck & ack;
125
126 protected:
127 virtual Response OnHandlePDU();
128 };
129
130
132
133 class H501AccessRequest : public H501Transaction
134 {
135 PCLASSINFO(H501AccessRequest, H501Transaction);
136 public:
137 H501AccessRequest(
138 H323PeerElement & pe,
139 const H501PDU & pdu
140 );
141
142 #if PTRACING
143 virtual const char * GetName() const;
144 #endif
145 virtual void SetRejectReason(
146 unsigned reasonCode
147 );
148
149 H501_AccessRequest & arq;
150 H501_AccessConfirmation & acf;
151 H501_AccessRejection & arj;
152
153 protected:
154 virtual Response OnHandlePDU();
155 };
156
157
159
160 class H323PeerElementDescriptor : public PSafeObject
161 {
162 PCLASSINFO(H323PeerElementDescriptor, PSafeObject);
163 public:
164 H323PeerElementDescriptor(const OpalGloballyUniqueID & _descriptorID)
165 : descriptorID(_descriptorID), state(Dirty), creator(0)
166 { }
167
168 Comparison Compare(const PObject & obj) const;
169
170 enum Options {
171 Protocol_H323 = 0x0001,
172 Protocol_Voice = 0x0002,
173 Protocol_Max = 0x0002,
174 Option_WildCard = 0x0004,
175 Option_SendAccessRequest = 0x0008,
176 Option_NotAvailable = 0x0010,
177 Option_PrioritySet = 0x0020,
178 Option_PriorityMask = 0x1fc0,
179 };
180
181 enum {
182 HighestPriority = 0,
183 DefaultPriority = 80,
184 LowestPriority = 127
185 };
186
187 static inline unsigned SetPriorityOption(unsigned pri) { return Option_PrioritySet | ((pri & 0x7f) << 6); }
188 static inline unsigned GetPriorityOption(unsigned options) { return (options & Option_PrioritySet) != 0 ? ((options >> 6) & 0x7f) : (int)DefaultPriority; }
189
190 void CopyTo(H501_Descriptor & descriptor);
191 static PBoolean CopyToAddressTemplate(H501_AddressTemplate & addressTemplates,
192 const H225_EndpointType & ep,
193 const H225_ArrayOf_AliasAddress & aliases,
194 const H225_ArrayOf_AliasAddress & transportAddress,
195 unsigned options = H323PeerElementDescriptor::Protocol_H323);
196
197 static void SetProtocolList(H501_ArrayOf_SupportedProtocols & h501Protocols, unsigned protocols);
198 static unsigned GetProtocolList(const H501_ArrayOf_SupportedProtocols & h501Protocols);
199
200 OpalGloballyUniqueID descriptorID;
201
202 PBoolean ContainsNonexistent();
203
204 enum States {
205 Clean,
206 Dirty,
207 Deleted
208 } state;
209
210 H501_ArrayOf_AddressTemplate addressTemplates;
211 PString gatekeeperID;
212 PTime lastChanged;
213 POrdinalKey creator;
214 };
215
216
218
219 class H323PeerElementServiceRelationship : public PSafeObject
220 {
221 PCLASSINFO(H323PeerElementServiceRelationship, PSafeObject);
222 public:
223 H323PeerElementServiceRelationship()
224 : ordinal(0)
225 { }
226
227 H323PeerElementServiceRelationship(const OpalGloballyUniqueID & _serviceID)
228 : serviceID(_serviceID), ordinal(0)
229 { }
230
231 Comparison Compare(const PObject & obj) const
232 { return serviceID.Compare(((H323PeerElementServiceRelationship&)obj).serviceID); }
233
234 OpalGloballyUniqueID serviceID;
235 POrdinalKey ordinal;
236 H323TransportAddress peer;
237 PString name;
238 PTime createdTime;
239 PTime lastUpdateTime;
240 PTime expireTime;
241 };
242
243
245
248 class H323PeerElement : public H323_AnnexG
249 {
250 PCLASSINFO(H323PeerElement, H323_AnnexG);
251 public:
256 H323PeerElement(
257 H323EndPoint & endpoint,
258 H323Transport * transport = NULL
259 );
260 H323PeerElement(
261 H323EndPoint & endpoint,
262 const H323TransportAddress & addr
263 );
264
267 ~H323PeerElement();
269
270 enum Error {
271 Confirmed,
272 Rejected,
273 NoResponse,
274 NoServiceRelationship,
275 ServiceRelationshipReestablished
276 };
277
278 enum {
279 LocalServiceRelationshipOrdinal = 0,
280 NoServiceRelationshipOrdinal = 1,
281 RemoteServiceRelationshipOrdinal = 2
282 };
283
288 void PrintOn(
289 ostream & strm
290 ) const;
292
293 PSafePtr<H323PeerElementDescriptor> GetFirstDescriptor(
294 PSafetyMode mode = PSafeReference
295 ) { return PSafePtr<H323PeerElementDescriptor>(descriptors, mode); }
296
297 PSafePtr<H323PeerElementServiceRelationship> GetFirstLocalServiceRelationship(
298 PSafetyMode mode = PSafeReference
299 ) { return PSafePtr<H323PeerElementServiceRelationship>(localServiceRelationships, mode); }
300
301 PSafePtr<H323PeerElementServiceRelationship> GetFirstRemoteServiceRelationship(
302 PSafetyMode mode = PSafeReference
303 ) { return PSafePtr<H323PeerElementServiceRelationship>(remoteServiceRelationships, mode); }
304
305 void SetLocalName(const PString & name);
306 PString GetLocalName() const;
307
308 void SetDomainName(const PString & name);
309 PString GetDomainName() const;
310
311 /*********************************************************
312 functions to establish and break service relationships
313 */
314
317 PBoolean SetOnlyServiceRelationship(const PString & peer, PBoolean keepTrying = true);
318 PBoolean AddServiceRelationship(const H323TransportAddress & peer, PBoolean keepTrying = true);
319 PBoolean AddServiceRelationship(const H323TransportAddress & peer, OpalGloballyUniqueID & serviceID, PBoolean keepTrying = true);
320 PBoolean RemoveServiceRelationship(const OpalGloballyUniqueID & serviceID, int reason = H501_ServiceReleaseReason::e_terminated);
321 PBoolean RemoveServiceRelationship(const H323TransportAddress & peer, int reason = H501_ServiceReleaseReason::e_terminated);
322 PBoolean RemoveAllServiceRelationships();
323
324 Error ServiceRequestByAddr(const H323TransportAddress & peer);
325 Error ServiceRequestByAddr(const H323TransportAddress & peer, OpalGloballyUniqueID & serviceID);
326 Error ServiceRequestByID(OpalGloballyUniqueID & serviceID);
327
330 PBoolean ServiceRelease(const OpalGloballyUniqueID & serviceID, unsigned reason);
331
332 /*********************************************************
333 functions to manipulate the local descriptor table
334 */
335
336 PBoolean AddDescriptor(
337 const OpalGloballyUniqueID & descriptorID,
338 const PStringArray & aliases,
339 const H323TransportAddressArray & transportAddrs,
340 unsigned options = H323PeerElementDescriptor::Protocol_H323,
341 PBoolean now = false
342 );
343
344 PBoolean AddDescriptor(
345 const OpalGloballyUniqueID & descriptorID,
346 const H225_ArrayOf_AliasAddress & aliases,
347 const H323TransportAddressArray & transportAddrs,
348 unsigned options = H323PeerElementDescriptor::Protocol_H323,
349 PBoolean now = false
350 );
351
352 PBoolean AddDescriptor(
353 const OpalGloballyUniqueID & descriptorID,
354 const H225_ArrayOf_AliasAddress & aliases,
355 const H225_ArrayOf_AliasAddress & transportAddr,
356 unsigned options = H323PeerElementDescriptor::Protocol_H323,
357 PBoolean now = false
358 );
359
360 PBoolean AddDescriptor(
361 const OpalGloballyUniqueID & descriptorID,
362 const POrdinalKey & creator,
363 const H225_ArrayOf_AliasAddress & alias,
364 const H225_ArrayOf_AliasAddress & transportAddresses,
365 unsigned options = H323PeerElementDescriptor::Protocol_H323,
366 PBoolean now = false
367 );
368
369 PBoolean AddDescriptor(
370 const OpalGloballyUniqueID & descriptorID,
371 const POrdinalKey & creator,
372 const H501_ArrayOf_AddressTemplate & addressTemplates,
373 const PTime & updateTime,
374 PBoolean now = false
375 );
376
379 PBoolean DeleteDescriptor(const PString & alias, PBoolean now = false);
380 PBoolean DeleteDescriptor(const H225_AliasAddress & alias, PBoolean now = false);
381 PBoolean DeleteDescriptor(const OpalGloballyUniqueID & descriptorID, PBoolean now = false);
382
385 PBoolean AccessRequest(
386 const PString & searchAlias,
387 PStringArray & destAliases,
388 H323TransportAddress & transportAddress,
389 unsigned options = H323PeerElementDescriptor::Protocol_H323
390 );
391
392 PBoolean AccessRequest(
393 const PString & searchAlias,
394 H225_ArrayOf_AliasAddress & destAliases,
395 H323TransportAddress & transportAddress,
396 unsigned options = H323PeerElementDescriptor::Protocol_H323
397 );
398
399 PBoolean AccessRequest(
400 const H225_AliasAddress & searchAlias,
401 H225_ArrayOf_AliasAddress & destAliases,
402 H323TransportAddress & transportAddress,
403 unsigned options = H323PeerElementDescriptor::Protocol_H323
404 );
405
406 PBoolean AccessRequest(
407 const H225_AliasAddress & alias,
408 H225_ArrayOf_AliasAddress & destAliases,
409 H225_AliasAddress & transportAddress,
410 unsigned options = H323PeerElementDescriptor::Protocol_H323
411 );
412
413 /*********************************************************
414 functions to send send descriptors to another peer element
415 */
416 PBoolean UpdateDescriptor(H323PeerElementDescriptor * descriptor);
417 PBoolean UpdateDescriptor(H323PeerElementDescriptor * descriptor, H501_UpdateInformation_updateType::Choices updateType);
418
419
420 Error SendUpdateDescriptorByID(const OpalGloballyUniqueID & serviceID,
421 H323PeerElementDescriptor * descriptor,
422 H501_UpdateInformation_updateType::Choices updateType);
423
424 Error SendUpdateDescriptorByAddr(const H323TransportAddress & peer,
425 H323PeerElementDescriptor * descriptor,
426 H501_UpdateInformation_updateType::Choices updateType);
427
428 Error SendAccessRequestByID(const OpalGloballyUniqueID & peerID,
429 H501PDU & request,
430 H501PDU & confirmPDU);
431
432 Error SendAccessRequestByAddr(const H323TransportAddress & peerAddr,
433 H501PDU & request,
434 H501PDU & confirmPDU);
435
436
437 /*********************************************************
438 low level request functions
439 */
440
441 PBoolean MakeRequest(H323_AnnexG::Request & request);
442
443 virtual void OnAddServiceRelationship(const H323TransportAddress &) { }
444 virtual void OnRemoveServiceRelationship(const H323TransportAddress &) { }
445
446 virtual void OnNewDescriptor(const H323PeerElementDescriptor &) { }
447 virtual void OnUpdateDescriptor(const H323PeerElementDescriptor &) { }
448 virtual void OnRemoveDescriptor(const H323PeerElementDescriptor &) { }
449
450 virtual H323Transaction::Response OnServiceRequest(H501ServiceRequest & info);
451 virtual H323Transaction::Response OnDescriptorUpdate(H501DescriptorUpdate & info);
452 virtual H323Transaction::Response OnAccessRequest(H501AccessRequest & info);
453
454 PBoolean OnReceiveServiceRequest(const H501PDU & pdu, const H501_ServiceRequest & pduBody);
455 PBoolean OnReceiveServiceConfirmation(const H501PDU & pdu, const H501_ServiceConfirmation & pduBody);
456
457 PBoolean OnReceiveDescriptorUpdate(const H501PDU & pdu, const H501_DescriptorUpdate & pduBody);
458 PBoolean OnReceiveDescriptorUpdateACK(const H501PDU & pdu, const H501_DescriptorUpdateAck & pduBody);
459
460 PBoolean OnReceiveAccessRequest(const H501PDU & pdu, const H501_AccessRequest & pduBody);
461 PBoolean OnReceiveAccessConfirmation (const H501PDU & pdu, const H501_AccessConfirmation & pduBody);
462 PBoolean OnReceiveAccessRejection(const H501PDU & pdu, const H501_AccessRejection & pduBody);
463
464 class AliasKey : public H225_AliasAddress
465 {
466 public:
467 AliasKey(const H225_AliasAddress & _alias, const OpalGloballyUniqueID & _id, PINDEX _pos, PBoolean _wild = false)
468 : H225_AliasAddress(_alias), id(_id), pos(_pos), wild(_wild)
469 { }
470
471 OpalGloballyUniqueID id;
472 PINDEX pos;
473 PBoolean wild;
474 };
475
476 protected:
477 void Construct();
478
479 Error SendUpdateDescriptor( H501PDU & pdu,
480 const H323TransportAddress & peer,
481 H323PeerElementDescriptor * descriptor,
482 H501_UpdateInformation_updateType::Choices updateType);
483
484 PBoolean OnRemoteServiceRelationshipDisappeared(OpalGloballyUniqueID & serviceID, const H323TransportAddress & peer);
485 void InternalRemoveServiceRelationship(const H323TransportAddress & peer);
486 H323Transaction::Response HandleServiceRequest(H501ServiceRequest & info);
487
488 virtual H323PeerElementDescriptor * CreateDescriptor(const OpalGloballyUniqueID & descriptorID);
489 virtual H323PeerElementServiceRelationship * CreateServiceRelationship();
490 virtual AliasKey * CreateAliasKey(const H225_AliasAddress & alias, const OpalGloballyUniqueID & id, PINDEX pos, PBoolean wild = false);
491
492 void RemoveDescriptorInformation(const H501_ArrayOf_AddressTemplate & addressTemplates);
493
494 PDECLARE_NOTIFIER(PThread, H323PeerElement, MonitorMain);
495 PDECLARE_NOTIFIER(PThread, H323PeerElement, UpdateAllDescriptors);
496 PDECLARE_NOTIFIER(PTimer, H323PeerElement, TickleMonitor);
497
498 PMutex localNameMutex;
499 PString localIdentifier;
500 PString domainName;
501
502 PSemaphore requestMutex;
503 PThread * monitor;
504 PBoolean monitorStop;
505 PSyncPoint monitorTickle;
506
507 PMutex basePeerOrdinalMutex;
508 PINDEX basePeerOrdinal;
509
510 // structures needed to maintain local service relationships (for which we receive a ServiceRequest)
511 PSafeSortedList<H323PeerElementServiceRelationship> localServiceRelationships;
512 PMutex localPeerListMutex;
513 POrdinalSet localServiceOrdinals;
514
515 // structures needed to maintain remote service relationships (for which we send a ServiceRequest)
516 PMutex remotePeerListMutex;
517 PSafeSortedList<H323PeerElementServiceRelationship> remoteServiceRelationships;
518 PStringToString remotePeerAddrToServiceID;
519 PDICTIONARY(StringToOrdinalKey, PString, POrdinalKey);
520 StringToOrdinalKey remotePeerAddrToOrdinalKey;
521
522 PSafeSortedList<H323PeerElementDescriptor> descriptors;
523
524 PSORTED_LIST(AliasKeyList, H225_AliasAddress);
525
526 PMutex aliasMutex;
527 AliasKeyList transportAddressToDescriptorID;
528 AliasKeyList specificAliasToDescriptorID;
529 AliasKeyList wildcardAliasToDescriptorID;
530 };
531
532
533 #endif // OPAL_H501
534
535 #endif // OPAL_H323_PECLIENT_H
536
537