OPAL  Version 3.10.10
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 
54 {
55  PCLASSINFO(H501Transaction, H323Transaction);
56  public:
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 
69 
70  H501_MessageCommonInfo & requestCommon;
71  H501_MessageCommonInfo & confirmCommon;
72 
73  protected:
75 };
76 
77 
79 
81 {
83  public:
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 
108 {
110  public:
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 
134 {
135  PCLASSINFO(H501AccessRequest, H501Transaction);
136  public:
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:
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 
201 
202  PBoolean ContainsNonexistent();
203 
204  enum States {
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:
224  : ordinal(0)
225  { }
226 
228  : serviceID(_serviceID), ordinal(0)
229  { }
230 
231  Comparison Compare(const PObject & obj) const
232  { return serviceID.Compare(((H323PeerElementServiceRelationship&)obj).serviceID); }
233 
235  POrdinalKey ordinal;
237  PString name;
238  PTime createdTime;
240  PTime expireTime;
241 };
242 
243 
245 
249 {
250  PCLASSINFO(H323PeerElement, H323_AnnexG);
251  public:
257  H323EndPoint & endpoint,
258  H323Transport * transport = NULL
259  );
261  H323EndPoint & endpoint,
262  const H323TransportAddress & addr
263  );
264 
267  ~H323PeerElement();
269 
270  enum Error {
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,
390  );
391 
392  PBoolean AccessRequest(
393  const PString & searchAlias,
394  H225_ArrayOf_AliasAddress & destAliases,
395  H323TransportAddress & transportAddress,
397  );
398 
399  PBoolean AccessRequest(
400  const H225_AliasAddress & searchAlias,
401  H225_ArrayOf_AliasAddress & destAliases,
402  H323TransportAddress & transportAddress,
404  );
405 
406  PBoolean AccessRequest(
407  const H225_AliasAddress & alias,
408  H225_ArrayOf_AliasAddress & destAliases,
409  H225_AliasAddress & transportAddress,
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 
445 
446  virtual void OnNewDescriptor(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 
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 
500  PString domainName;
501 
502  PSemaphore requestMutex;
503  PThread * monitor;
504  PBoolean monitorStop;
505  PSyncPoint monitorTickle;
506 
509 
510  // structures needed to maintain local service relationships (for which we receive a ServiceRequest)
511  PSafeSortedList<H323PeerElementServiceRelationship> localServiceRelationships;
513  POrdinalSet localServiceOrdinals;
514 
515  // structures needed to maintain remote service relationships (for which we send a ServiceRequest)
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;
530 };
531 
532 
533 #endif // OPAL_H501
534 
535 #endif // OPAL_H323_PECLIENT_H
536 
537 
Definition: peclient.h:248
H501_ServiceRequest & srq
Definition: peclient.h:96
PString localIdentifier
Definition: peclient.h:499
static unsigned GetPriorityOption(unsigned options)
Definition: peclient.h:188
virtual void OnAddServiceRelationship(const H323TransportAddress &)
Definition: peclient.h:443
H323PeerElementServiceRelationship()
Definition: peclient.h:223
H323TransportAddressArray(const OpalTransportAddress &address)
Definition: transaddr.h:97
Options
Definition: peclient.h:170
Definition: h323annexg.h:52
H323PeerElementServiceRelationship(const OpalGloballyUniqueID &_serviceID)
Definition: peclient.h:227
PSemaphore requestMutex
Definition: peclient.h:502
PTime lastUpdateTime
Definition: peclient.h:239
Error
Definition: peclient.h:270
virtual void OnRemoveServiceRelationship(const H323TransportAddress &)
Definition: peclient.h:444
virtual H323TransactionPDU * CreateRIP(unsigned sequenceNumber, unsigned delay) const
Definition: transports.h:703
PSafeSortedList< H323PeerElementServiceRelationship > localServiceRelationships
Definition: peclient.h:511
StringToOrdinalKey remotePeerAddrToOrdinalKey
Definition: peclient.h:520
OpalGloballyUniqueID serviceID
Definition: peclient.h:234
PMutex aliasMutex
Definition: peclient.h:526
virtual void OnUpdateDescriptor(const H323PeerElementDescriptor &)
Definition: peclient.h:447
H501_MessageCommonInfo & confirmCommon
Definition: peclient.h:71
Definition: h323trans.h:327
PMutex remotePeerListMutex
Definition: peclient.h:516
PString name
Definition: peclient.h:237
H501_AccessRequest & arq
Definition: peclient.h:149
virtual void OnRemoveDescriptor(const H323PeerElementDescriptor &)
Definition: peclient.h:448
PTime expireTime
Definition: peclient.h:240
H501_DescriptorUpdateAck & ack
Definition: peclient.h:124
Definition: peclient.h:206
static unsigned SetPriorityOption(unsigned pri)
Definition: peclient.h:187
AliasKeyList specificAliasToDescriptorID
Definition: peclient.h:528
PString gatekeeperID
Definition: peclient.h:211
AliasKey(const H225_AliasAddress &_alias, const OpalGloballyUniqueID &_id, PINDEX _pos, PBoolean _wild=false)
Definition: peclient.h:467
PSafeSortedList< H323PeerElementDescriptor > descriptors
Definition: peclient.h:522
virtual void SetRejectReason(unsigned reasonCode)=0
H323PeerElementDescriptor(const OpalGloballyUniqueID &_descriptorID)
Definition: peclient.h:164
Definition: peclient.h:464
OpalGloballyUniqueID id
Definition: peclient.h:471
H501_AccessConfirmation & acf
Definition: peclient.h:150
AliasKeyList wildcardAliasToDescriptorID
Definition: peclient.h:529
H501Transaction(H323PeerElement &pe, const H501PDU &pdu, PBoolean hasReject)
H323PeerElement & peerElement
Definition: peclient.h:74
H501_ServiceConfirmation & scf
Definition: peclient.h:97
virtual void OnNewDescriptor(const H323PeerElementDescriptor &)
Definition: peclient.h:446
Definition: peclient.h:80
POrdinalSet localServiceOrdinals
Definition: peclient.h:513
Definition: peclient.h:219
PTime lastChanged
Definition: peclient.h:212
AliasKeyList transportAddressToDescriptorID
Definition: peclient.h:527
Comparison Compare(const PObject &obj) const
Definition: peclient.h:231
Definition: peclient.h:272
PDECLARE_NOTIFIER(PThread, H323Transaction, SlowHandler)
Definition: h323trans.h:223
Definition: peclient.h:107
H323TransactionPDU * request
Definition: h323trans.h:390
Definition: peclient.h:273
PSORTED_LIST(OpalH224ClientList, OpalH224Client)
Definition: h323trans.h:51
Definition: h501pdu.h:54
PThread * monitor
Definition: peclient.h:503
ValidationResult
Definition: h235auth.h:83
PSafePtr< H323PeerElementServiceRelationship > GetFirstLocalServiceRelationship(PSafetyMode mode=PSafeReference)
Definition: peclient.h:297
PSyncPoint monitorTickle
Definition: peclient.h:505
Definition: peclient.h:53
PSafePtr< H323PeerElementDescriptor > GetFirstDescriptor(PSafetyMode mode=PSafeReference)
Definition: peclient.h:293
virtual H235Authenticator::ValidationResult ValidatePDU() const
POrdinalKey ordinal
Definition: peclient.h:235
Definition: peclient.h:271
PMutex localPeerListMutex
Definition: peclient.h:512
PMutex localNameMutex
Definition: peclient.h:498
PDICTIONARY(H323CallIdentityDict, PString, H323Connection)
PBoolean wild
Definition: peclient.h:473
OpalGloballyUniqueID descriptorID
Definition: peclient.h:200
PINDEX basePeerOrdinal
Definition: peclient.h:508
PTime createdTime
Definition: peclient.h:238
PMutex basePeerOrdinalMutex
Definition: peclient.h:507
H501_MessageCommonInfo & requestCommon
Definition: peclient.h:70
Definition: peclient.h:205
virtual Response OnHandlePDU()=0
POrdinalKey creator
Definition: peclient.h:213
PStringToString remotePeerAddrToServiceID
Definition: peclient.h:518
PINDEX pos
Definition: peclient.h:472
PSafeSortedList< H323PeerElementServiceRelationship > remoteServiceRelationships
Definition: peclient.h:517
PBoolean monitorStop
Definition: peclient.h:504
#define OpalGloballyUniqueID
Definition: guid.h:42
Response
Definition: h323trans.h:344
H323TransportAddress peer
Definition: peclient.h:236
Definition: h323ep.h:85
Definition: peclient.h:160
Definition: peclient.h:133
States
Definition: peclient.h:204
Definition: transaddr.h:66
Definition: peclient.h:274
PSafePtr< H323PeerElementServiceRelationship > GetFirstRemoteServiceRelationship(PSafetyMode mode=PSafeReference)
Definition: peclient.h:301
H501_ArrayOf_AddressTemplate addressTemplates
Definition: peclient.h:210
PString domainName
Definition: peclient.h:500
H501_AccessRejection & arj
Definition: peclient.h:151
H501_ServiceRejection & srj
Definition: peclient.h:98
H501_DescriptorUpdate & du
Definition: peclient.h:123