lib/pwlib/pwlib.dxy

   1 /*! \mainpage Portable Windows Library
   2
   3 \section contents Table of Contents
   4
   5 \li \ref intro
   6 \li \ref overview
   7 \li \ref using
   8 \li \ref base
   9 \li \ref components
  10 \li \ref history
  11
  12
  13 \section intro Introduction
  14
  15 This document provides reference information for the PWLib C++ class library. It is not intended
  16 as a tutorial document.
  17
  18 Last updated 17 May, 2004
  19
  20 Copyright (C) 1999-2003 Equivalence Pty Ltd, All right reserved
  21
  22 Portions Copyright (C) 2004 Post Increment, All Rights Reserved
  23
  24
  25 \section overview Overview
  26
  27 PWLib is a moderately large C++ class library that originated many years ago as
  28 a method to produce applications that run on both Microsoft Windows and Unix
  29 X-Windows systems. It also was to have a Macintosh port as well, but this never
  30 eventuated.
  31
  32 Since then, the availability of multi-platform GUI toolkits such as KDE and wxWindows,
  33 and the development of the OpenH323 project as primary user of the library,
  34 has emphasised the focus on networking, I/O portability, multi-threading
  35 and portability. Mostly, the library is used to create high performance and
  36 highly portable network-centric applications.
  37
  38 In addition to these high level functions, basic "container" classes such as arrays, linear lists,
  39 sorted lists (RB Tree) and dictionaries (hash tables) are available. These were
  40 created before the emergence of STL as a standard, so unfortunately these
  41 constructs are incompatible with iterators and generic algorithms.
  42 Development continues in this area, and future versions of PWLIB will see increased
  43 use of, and compatibility with, STL
  44
  45 The library is used extensively by many companies for both commercial and Open Source products.
  46 The motivation in making PWLib available as Open Source was primarily to support the OpenH323 project,
  47 but it is definitely useful as a stand-alone library.
  48
  49 The classes within PWLib are seperated into two types:
  50 \ref base
  51 and
  52 \ref components
  53 The
  54 \ref base
  55 contain all of the essential support for constructs such as containers, threads and sockets
  56 that are dependent on platform specific features. All PWLib programs will require the
  57 \ref base
  58
  59 The
  60 \ref components
  61 implement functionality that is usually platform independent, and may not be required
  62 for all programs.  On some platforms (notably Windows) the
  63 \ref base
  64 and
  65 \ref components
  66 may be divided
  67 into discrete library archives. Other platforms (notably Unix platforms) combine all of the code into a single library
  68 and rely on the linker to omit code that is not required.
  69
  70 Note that previous versions of PWLib also contained GUI classes and GUI components, but support for these
  71 classes has been discontinued.
  72
  73 \section using Using PWLib
  74 Tutorial introductions for PWLib are available elsewhere (see http://toncar.cz/openh323/tut), but some
  75 information on how to create a simple program is always useful.
  76
  77 Here is the canonical "Hello world!" program written using the PWLib infrastructure.
  78
  79 \verbatim
  80
  81 // hello.cxx
  82
  83 #include <ptlib.h>
  84
  85 class Hello : public PProcess
  86 {
  87   PCLASSINFO(Hello, PProcess)
  88   public:
  89         void Main();
  90 };
  91
  92 PCREATE_PROCESS(Hello)
  93
  94 void Hello::Main()
  95 {
  96   cout << "Hello world!\n";
  97 }
  98
  99 // End of hello.cxx
 100 \endverbatim
 101
 102 The PCREATE_PROCESS macro actually defines the #main()# function
 103 and creates an instance of Hello. This assures that everything is
 104 initialised in the correct order. C++ does initialisation of global
 105 statics badly (and destruction is even worse), so try to put
 106 everything into your PProcess descedent rather than globals.
 107
 108 \section base Base Classes
 109
 110 \subsection object_h Base Object Classes
 111  \li PObject - the base class for all other classes in the PWLib
 112  \li PContainer - the base class for all reference-counted classes in PWLib
 113  \li PAbstractArray - base class for array of objects. Equivalent to the STL vector template class
 114  \li PAbstractList - base class for lists of objects. Equivalent to the STL list template class
 115  \li PAbstractDictionary - base class for dictionaries. Equivalent to the STL map template class
 116  \li PString - base class for the string abstraction. Equivalent to the STL string class.
 117
 118 \subsection channel I/O Channel Classes
 119 Classes that perform general I/O using the PChannel abstraction
 120   \li PChannel - base class for all I/O channels
 121   \li PIndirectChannel - a channel that encapsulates another channel
 122   \li PConsoleChannel - channel for accessing the system console
 123   \li PPipeChannel - execute a program and access input and output as a PChannel
 124   \li PSerialChannel - access a serial communications port as a PChannel
 125   \li PFile - access files on the host operating system using PChannels
 126   \li PTextFile - access text files on the host operating system as PChannels
 127   \li PStructuredFile - access files on the host operating system as arrays of structured records
 128   \li PFilePath - access directories on the host operating system
 129   \li PVideoChannel - read or write data to a video device as a PChannel. See also PVideoDevice and PColourConverter
 130   \li PSoundChannel - read or write data to sound device as a PChannel
 131
 132 \subsection socket Socket Classes
 133 Implementation of a network sockets abstraction (roughly based on Berkeley sockets)
 134   \li PSocket - base class for all network sockets
 135   \li PIPSocket - base class for all sockets using the IP protocol
 136   \li PUDPSocket - IP socket using the UDP protocol
 137   \li PTCPSocket - IP socket using the TCP/IP protocol
 138   \li PICMPSocket - IP socket using the ICMP protocl
 139   \li PIPXSocket - base class for sockets using the IPX protocol
 140   \li PEthSocket - socket interface for raw Ethernet interfaces
 141
 142 \subsection thread Process and Thread Classes
 143 Classes that handle processes, multi-threading and synchronsiation.
 144   \li PProcess - implements the primary thread of control for a running program
 145   \li PServiceProcess - implements a "daemon" or "system process"
 146   \li PThread - abstracts a thread of control or execution context
 147   \li PSemaphore - synchronisation primitive based on a counter
 148   \li PMutex - synchronisation primitive based on mutual exclusion
 149   \li PCriticalSection - synchronisation primitive implementing exclusive access to a critical code section
 150   \li PSyncPoint - allows multiple threads to sychronise to a specific code point. See also PSyncPointAck
 151   \li PAtomicInteger - implements an integer counter with atomic increment and decrement operations
 152
 153 \subsection misc Miscellaneous Classes
 154   \li PArgList - parse a command line passed to a console program
 155   \li PConfig - provide persistent storage for program settings using a platform-appropriate mechanism
 156   \li PTime - abstracts the notion of a wall-clock time and date
 157   \li PTimeInterval - abstracts the notion of a time interval as the difference between two PTime values
 158   \li PDynaLink - implements a dynamically loadable code module
 159   \li PRemoteConnection - controls for a dialup network connection
 160   \li PMail - send an email using a platform-appropriate mechanism
 161   \li PPluginManager - manage plugin code modules
 162   \li PAbstractFactory - an implementation of the "Abstract Factory" paradigm using templates
 163   \li PSmartPointer - a reference counted pointer
 164   \li PNotifier - a notifier function that allows any class to call a member function on any other class
 165   \li PSmartNotifierFunction - a smart notifier function that uses object IDs rather than pointers
 166
 167 \section components Console Components
 168
 169 \subsection http HTTP Classes
 170 Implementation of the HTTP protocol
 171   \li PHTTP - base class for HTTP protocol. See also PHTTPClient and PHTTPServer
 172   \li PURL - parse and maniulate uniform resource locations
 173   \li PHTML - a string stream that formats HTML information
 174   \li PHTTPForm - allows the creation of HTTP forms
 175   \li PHTTPServiceProcess - a PServiceProcess descendant that contains a HTTP server
 176
 177 \subsection protocol Protocol Classes
 178 Implementation of various Internet-related protocols. Some of these are implemented within PWLib - some require external libraries for support
 179   \li PInternetProtocol - base class for all text-based Internet protocols
 180   \li PPOP3 - base class for POP3 protocol classes. See also PPOP3Client and PPOP3Server
 181   \li PSMTMP - base class for SMTP protocol classes. See also PSMTPClient and PSMTPServer
 182   \li PFTP - base class for FTP protocol classes. See also PFTPClient and FTPServer
 183   \li PMIMEInfo - implements a list of key-value pairs in MIME format
 184   \li PTelnetSocket - implements the TELNET protocol
 185   \li PSocksProtocol - base class for SOCKS protocol implementation. See also PSocks4Socket, PSocks5Socket, PSocksSocket, PSocksUDPSocket
 186   \li PSTUNClient - implementation of a STUN client
 187   \li PSNMP - base classs for SNMP protocol implementations. See also PSNMPClient and PSNMPServer
 188   \li PSSLChannel - PIndirectChannel that implements the SSL protocol via OpenSSL.
 189   \li PSASL - implements the SASL protocol via the Cyrus SASL library
 190   \li PXMLRPC - implements the XMLRPC protocol via the Expat XML library and the HTTP classes
 191   \li PSOAPClient - implements a SOAP client
 192   \li PLDAPSession - implements a LDAP client via the OpenLDAP library
 193   \li PILSSession - implements a ILS client via the OpenLDAP library
 194   \li XMPP::Stream - implements a XMPP (Jabber) stream as a PChannel.
 195
 196 \subsection misccomponents Miscellaneous Classes
 197   \li PModem - a descendant of PSerialChannel that is customised for modems that obey the AT command set
 198   \li PIpAccessControlList - a list of entries that allow specification of a range of IP addresses or networks
 199   \li PRandom - a random number generator
 200   \li PCypher - implementation of various code cyphers such as PMessageDigest5, PTEACypher, and PMessageDigestSHA1
 201   \li PWAVFile - implements a AIFF format WAV file
 202   \li PDTMFDecoder - decodes DTMF digits from a stream of PCM data
 203   \li PMemoryFile - implements a PFile descendant that stores data in memory
 204   \li PSDLVideoDevice - implement a vide display device using the SDL library
 205   \li PXML - Implements a parser for XML using the Expat library
 206   \li PVXMLChannel - Implements a parser for the VXML language
 207   \li PTextToSpeech - Implement a Text to Speech converter
 208
 209 \subsection asn ASN.1 Support Classes
 210   \li PASN_Array
 211   \li PASN_BitString
 212   \li PASN_BMPString
 213   \li PASN_Boolean
 214   \li PASN_Choice
 215   \li PASN_ConstrainedObject
 216   \li PASN_ConstrainedString
 217   \li PASN_Enumeration
 218   \li PASN_GeneralisedTime
 219   \li PASN_Integer
 220   \li PASN_Null
 221   \li PASN_Object
 222   \li PASN_ObjectId
 223   \li PASN_OctetString
 224   \li PASN_Real
 225   \li PASN_Sequence
 226   \li PASN_Set
 227   \li PASN_Stream
 228   \li PASN_UniversalTime
 229
 230 \subsection history History
 231
 232 \li 17 May 2004 - Converted from Doc++ to Doxygen format by Craig Southeren
 233
 234 */