// 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

*/