Fixed DevStudio 2003 build with memory check code.
[pwlib.git] / pwlib.dxy
blobe3e3461dfdf8fa11f36802dc821e2781b2d3481e
1 /*! \mainpage Portable Windows Library
3 \section contents Table of Contents
5 \li \ref intro
6 \li \ref overview
7 \li \ref using
8 \li \ref base
9 \li \ref components
10 \li \ref history
13 \section intro Introduction
15 This document provides reference information for the PWLib C++ class library. It is not intended
16 as a tutorial document.
18 Last updated 17 May, 2004
20 Copyright (C) 1999-2003 Equivalence Pty Ltd, All right reserved 
22 Portions Copyright (C) 2004 Post Increment, All Rights Reserved
25 \section overview Overview
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.
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.
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
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.
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 
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.
70 Note that previous versions of PWLib also contained GUI classes and GUI components, but support for these
71 classes has been discontinued.
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.
77 Here is the canonical "Hello world!" program written using the PWLib infrastructure.
79 \verbatim
81 // hello.cxx
83 #include <ptlib.h>
85 class Hello : public PProcess
87   PCLASSINFO(Hello, PProcess)
88   public:
89         void Main();
92 PCREATE_PROCESS(Hello)
94 void Hello::Main()
96   cout << "Hello world!\n";
99 // End of hello.cxx
100 \endverbatim
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.
108 \section base Base Classes
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.
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
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
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
167 \section components Console Components
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
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
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 
230 \subsection history History
232 \li 17 May 2004 - Converted from Doc++ to Doxygen format by Craig Southeren