diff -r 000000000000 -r 307788aac0a8 realtimenetprots/rtp/documentation/rtp.dox
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/realtimenetprots/rtp/documentation/rtp.dox	Tue Feb 02 01:03:15 2010 +0200
@@ -0,0 +1,138 @@
+// Copyright (c) 2003-2009 Nokia Corporation and/or its subsidiary(-ies).
+// All rights reserved.
+// This component and the accompanying materials are made available
+// under the terms of the License "Eclipse Public License v1.0"
+// which accompanies this distribution, and is available
+// at the URL "http://www.eclipse.org/legal/epl-v10.html".
+//
+// Initial Contributors:
+// Nokia Corporation - initial contribution.
+//
+// Contributors:
+//
+// Description:
+// This is the extra documentation for the RTP API
+// This is the API for the SymbianOS RTP stack.
+// To use this API, start by creating a RRtpSession
+// A session encapsulates all RTP traffic to/from a particular port, and
+// its associated RTCP traffic. 
+// RTP traffic from this port is modelled via the RRtpSendStream class.
+// RTP traffic from a particular remote host is modelled via RRtpReceiveStream
+// RRtpPacket and its subclasses RRtpSendPacket and RRtpReceivePacket are
+// the encapsulations of the RTP packets.
+// The API uses a R class 'cheshire cat' idiom. All the R classes in
+// the API are handles onto resources, or you may prefer to think of
+// them as wrappers round pointers. As such they have the following
+// properties:
+// - They are very lightweight and can be copied around by value.
+// - 2 copies of the same handle are 'the same thing'; if you do something
+// to one of them it will apply to the other.
+// - They need to be 'opened' before they point to anactual resource,
+// and must be closed when the resource is no longer needed. Note
+// that in some cases, the resource is considered to be owned by
+// another resource, so there is no need to close it. In these
+// cases, there is no close method and this fact is clearly
+// documented. If an R class is closed, any other copies of the
+// same handle will become invalid as they are handles to
+// nonexistent resources.
+// The RTP stack relies heavily on an event model based on callback
+// functions. This has the following advantages over alternative methods, 
+// such as signaling events via TRequestStatus objects or using mixins:
+// - It is more flexible for the client; we can distinguish a large number 
+// of different events and allow the client to chose if they want to
+// receive notifications about them in 1 function or many, and how they
+// want to spread different notifications over their object structure.
+// To give an example, a client might be interested in all SDES messages,
+// only in some types of SDES messages or in no SDES messages, and they
+// might want to handle these messages in different parts of the code or
+// all in the same part. THe callback model can support all these cases.
+// - Many other RTP APIs on other platforms use a similar concept, so
+// creating a simialr API makes it easier to port code that originated 
+// on top of these APIs.
+// There are 4 major concepts in the event model:
+// - An event manager. The session, the send stream and the receive
+// streams each have their own event manager. Callbacks registered
+// on 1 manager don't apply to other managers. The manager is not
+// exposed in the API.
+// - An event. (TRtpEvent class). An event is generated when anything
+// happens that the client might want to know about. The event can
+// be thought of as comprising 2 numbers, the event type taken from
+// TRtpEventType and another parameter whose meaning is event-type
+// specific. For instance, for all the 'Fail' events it is a
+// SymbianOS error code. Additional information might be implicitly
+// associated with the event, but needs to be fetched from another
+// object, for instance when processing a ErtpPacketReceived event,
+// the RRtpReceivePacket object must be obtained from the
+// Rrt-ReceiveStream.  Events are associated with an object; for
+// instance receive stream events are associated with a
+// RRtpReceiveStream. There are functions on the event for
+// obtaining that object.
+// - A callback function. A callback function is a static function
+// with a particular signature.  Static
+// functions are used because callback models using member
+// functions in C++ either involve bending the rules of the
+// language or a lot of code bloat. If a function is registered for
+// a particular event, it will be called when that event
+// occurs. One callback function can be associated with more than 1
+// callback registration. Callback functions take a pointer argument
+// which was supplied as part of the registration; normally a
+// static callback function in a CFoo class would take a pointer to
+// a CFoo* and call a member function on the CFoo object that does
+// the real work.
+// - A callback registration. A callback registration is the thing
+// that glues all this together. The event manager contains a
+// number of callback registrations, each of which binds a function
+// and pointer (normally an object) to a particular kind of
+// event.  Registrations can be bound to all events on a stream
+// (except 'Fail' events), via the ErtpAnyEvent code, or they can
+// be further restricted by a parameter whose meaning is event-type
+// specific. (For instance for the ErtpSDES event, the parameter is
+// used to express interest in only a particular SDES field.) The
+// same callback function and object can be registered for several
+// different registrations, possibly even on different streams.
+// So to use the event model, decide which events you care about, decide
+// which objects care about those events, and register functions in all
+// those objects to be told about all the events. 
+// If an event leaves, an Fail event will be generated with the leave
+// code.  Handlers for error events must not leave, as this would
+// result in an infinite loop if allwed. It is reccomended that error
+// events are handled by a separate callback to other events, to avoid
+// confusion about whether leaves are allowed. (This is why callbacks
+// registered for ErtpAnyEvent don't get called back for Fail events)
+// One-shot event registrations are registrations that are only called
+// back once. For instance, an application might want to display the
+// NAME SDES parameter but might only need to be told what it is when
+// the first one arrives. A one-shot resistration will only be called
+// back for the first NAME received.
+// To register events, use one of the RegisterEventCallbackL
+// functions.  These are template functions that are available in
+// global and member-function versions. The reason for this is
+// limitations in the handling of template member functions in MSVC6;
+// in many situations calls to the member functions won't compile and
+// the global functions should be used instead.
+// Note that there are always a pair of functions; one doesn't take
+// the 'aParameter' parameter, and defaults it to
+// KRtpNoParameter. This is more efficient as the parameter is often
+// not used.
+// The callback function takes a pointer which can be of any type.
+// The RegisterEventCallbackL functions are all templated so that the
+// pointer you supply must be of the same type as the function
+// expects.
+// As RTP/RTCP is removable from ROM using the SYMBIAN_EXCLUDE_RTP_RTCP
+// in the build rom command a stub is used to prevent linking failures.
+// The "#ifdef RTP_Removed" is used to reduce the overhead of having an extra set of cpp files to create the 
+// stub. Using "#ifdef RTP_Removed" the MMP files create an extra set of stubbed 
+// dlls from the one cpp file.  The iby file then exports the complete or stubbed dlls depending on the 
+// SYMBIAN_EXCLUDE macro.
+// The Open session functions leave with KErrNotSuported when the stub is used.  Functions
+// which can not leave ASSERT in debug mode as should not have been called since the Open and similar 
+// functions should have 'left'.
+// 
+//
+
+/**
+ @mainpage Symbian RTP API
+ The RTP stack's event model is described in the section '@ref Events'
+ @page Events The Event Model
+ @page Stub of RTP API with #ifdef RTP_Removed
+*/