1 // Copyright (c) 2003-2009 Nokia Corporation and/or its subsidiary(-ies).

     2 // All rights reserved.

     3 // This component and the accompanying materials are made available

     4 // under the terms of the License "Eclipse Public License v1.0"

     5 // which accompanies this distribution, and is available

     6 // at the URL "http://www.eclipse.org/legal/epl-v10.html".

     7 //

     8 // Initial Contributors:

     9 // Nokia Corporation - initial contribution.

    10 //

    11 // Contributors:

    12 //

    13 // Description:

    14 // This is the extra documentation for the RTP API

    15 // This is the API for the SymbianOS RTP stack.

    16 // To use this API, start by creating a RRtpSession

    17 // A session encapsulates all RTP traffic to/from a particular port, and

    18 // its associated RTCP traffic. 

    19 // RTP traffic from this port is modelled via the RRtpSendStream class.

    20 // RTP traffic from a particular remote host is modelled via RRtpReceiveStream

    21 // RRtpPacket and its subclasses RRtpSendPacket and RRtpReceivePacket are

    22 // the encapsulations of the RTP packets.

    23 // The API uses a R class 'cheshire cat' idiom. All the R classes in

    24 // the API are handles onto resources, or you may prefer to think of

    25 // them as wrappers round pointers. As such they have the following

    26 // properties:

    27 // - They are very lightweight and can be copied around by value.

    28 // - 2 copies of the same handle are 'the same thing'; if you do something

    29 // to one of them it will apply to the other.

    30 // - They need to be 'opened' before they point to anactual resource,

    31 // and must be closed when the resource is no longer needed. Note

    32 // that in some cases, the resource is considered to be owned by

    33 // another resource, so there is no need to close it. In these

    34 // cases, there is no close method and this fact is clearly

    35 // documented. If an R class is closed, any other copies of the

    36 // same handle will become invalid as they are handles to

    37 // nonexistent resources.

    38 // The RTP stack relies heavily on an event model based on callback

    39 // functions. This has the following advantages over alternative methods, 

    40 // such as signaling events via TRequestStatus objects or using mixins:

    41 // - It is more flexible for the client; we can distinguish a large number 

    42 // of different events and allow the client to chose if they want to

    43 // receive notifications about them in 1 function or many, and how they

    44 // want to spread different notifications over their object structure.

    45 // To give an example, a client might be interested in all SDES messages,

    46 // only in some types of SDES messages or in no SDES messages, and they

    47 // might want to handle these messages in different parts of the code or

    48 // all in the same part. THe callback model can support all these cases.

    49 // - Many other RTP APIs on other platforms use a similar concept, so

    50 // creating a simialr API makes it easier to port code that originated 

    51 // on top of these APIs.

    52 // There are 4 major concepts in the event model:

    53 // - An event manager. The session, the send stream and the receive

    54 // streams each have their own event manager. Callbacks registered

    55 // on 1 manager don't apply to other managers. The manager is not

    56 // exposed in the API.

    57 // - An event. (TRtpEvent class). An event is generated when anything

    58 // happens that the client might want to know about. The event can

    59 // be thought of as comprising 2 numbers, the event type taken from

    60 // TRtpEventType and another parameter whose meaning is event-type

    61 // specific. For instance, for all the 'Fail' events it is a

    62 // SymbianOS error code. Additional information might be implicitly

    63 // associated with the event, but needs to be fetched from another

    64 // object, for instance when processing a ErtpPacketReceived event,

    65 // the RRtpReceivePacket object must be obtained from the

    66 // Rrt-ReceiveStream.  Events are associated with an object; for

    67 // instance receive stream events are associated with a

    68 // RRtpReceiveStream. There are functions on the event for

    69 // obtaining that object.

    70 // - A callback function. A callback function is a static function

    71 // with a particular signature.  Static

    72 // functions are used because callback models using member

    73 // functions in C++ either involve bending the rules of the

    74 // language or a lot of code bloat. If a function is registered for

    75 // a particular event, it will be called when that event

    76 // occurs. One callback function can be associated with more than 1

    77 // callback registration. Callback functions take a pointer argument

    78 // which was supplied as part of the registration; normally a

    79 // static callback function in a CFoo class would take a pointer to

    80 // a CFoo* and call a member function on the CFoo object that does

    81 // the real work.

    82 // - A callback registration. A callback registration is the thing

    83 // that glues all this together. The event manager contains a

    84 // number of callback registrations, each of which binds a function

    85 // and pointer (normally an object) to a particular kind of

    86 // event.  Registrations can be bound to all events on a stream

    87 // (except 'Fail' events), via the ErtpAnyEvent code, or they can

    88 // be further restricted by a parameter whose meaning is event-type

    89 // specific. (For instance for the ErtpSDES event, the parameter is

    90 // used to express interest in only a particular SDES field.) The

    91 // same callback function and object can be registered for several

    92 // different registrations, possibly even on different streams.

    93 // So to use the event model, decide which events you care about, decide

    94 // which objects care about those events, and register functions in all

    95 // those objects to be told about all the events. 

    96 // If an event leaves, an Fail event will be generated with the leave

    97 // code.  Handlers for error events must not leave, as this would

    98 // result in an infinite loop if allwed. It is reccomended that error

    99 // events are handled by a separate callback to other events, to avoid

   100 // confusion about whether leaves are allowed. (This is why callbacks

   101 // registered for ErtpAnyEvent don't get called back for Fail events)

   102 // One-shot event registrations are registrations that are only called

   103 // back once. For instance, an application might want to display the

   104 // NAME SDES parameter but might only need to be told what it is when

   105 // the first one arrives. A one-shot resistration will only be called

   106 // back for the first NAME received.

   107 // To register events, use one of the RegisterEventCallbackL

   108 // functions.  These are template functions that are available in

   109 // global and member-function versions. The reason for this is

   110 // limitations in the handling of template member functions in MSVC6;

   111 // in many situations calls to the member functions won't compile and

   112 // the global functions should be used instead.

   113 // Note that there are always a pair of functions; one doesn't take

   114 // the 'aParameter' parameter, and defaults it to

   115 // KRtpNoParameter. This is more efficient as the parameter is often

   116 // not used.

   117 // The callback function takes a pointer which can be of any type.

   118 // The RegisterEventCallbackL functions are all templated so that the

   119 // pointer you supply must be of the same type as the function

   120 // expects.

   121 // As RTP/RTCP is removable from ROM using the SYMBIAN_EXCLUDE_RTP_RTCP

   122 // in the build rom command a stub is used to prevent linking failures.

   123 // The "#ifdef RTP_Removed" is used to reduce the overhead of having an extra set of cpp files to create the 

   124 // stub. Using "#ifdef RTP_Removed" the MMP files create an extra set of stubbed 

   125 // dlls from the one cpp file.  The iby file then exports the complete or stubbed dlls depending on the 

   126 // SYMBIAN_EXCLUDE macro.

   127 // The Open session functions leave with KErrNotSuported when the stub is used.  Functions

   128 // which can not leave ASSERT in debug mode as should not have been called since the Open and similar 

   129 // functions should have 'left'.

   130 // 

   131 //

   132 

   133 /**

   134  @mainpage Symbian RTP API

   135  The RTP stack's event model is described in the section '@ref Events'

   136  @page Events The Event Model

   137  @page Stub of RTP API with #ifdef RTP_Removed

   138 */