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