/[resiprocate]/main/reflow/ReadMe.txt
ViewVC logotype

Contents of /main/reflow/ReadMe.txt

Parent Directory Parent Directory | Revision Log Revision Log


Revision 7750 - (show annotations) (download)
Wed May 21 20:07:52 2008 UTC (11 years, 7 months ago) by sgodin
File MIME type: text/plain
File size: 7399 byte(s)
-updated reflow/recon documentation
1 reflow (FlowManager)
2 ====================
3
4 The flow manager is a layer that faciltates the flow of media to/from a media based application.
5 It is responsible for any NAT traversal logic, and will eventually implement ICE as a Nat
6 traversal solution.
7
8 Currently the Flow Manager allows NAT traversal via static configuration only.
9
10 An application should create one instance of the FlowManager object. Once an application
11 determines that an audio media stream is needed it uses the following API call on the
12 FlowManager object to create a MediaStream object.
13
14 MediaStream* createMediaStream(MediaStreamHandler& mediaStreamHandler,
15 const StunTuple& localBinding,
16 bool rtcpEnabled = true,
17 Flow::NatTraversalMode natTraversalMode = Flow::NoNatTraversal,
18 const char* natTraversalServerHostname = 0,
19 unsigned short natTraversalServerPort = 0,
20 const char* stunUsername = 0,
21 const char* stunPassword = 0);
22
23 Possible NatTraversalModes are:
24
25 NoNatTraveral - just send media to/from localBinding
26
27 StunBindDiscovery - send STUN bind request to stun server specified and fire an event when
28 discovered reflexive mapping is retrieved
29
30 TurnUdpAllocation - send a TURN allocation request via UDP to the turn server specified and
31 fire an event when the allocation is complete and allocated address is
32 known
33
34 TurnTcpAllocation - send a TURN allocation request via TCP to the turn server specified and
35 fire an event when the allocation is complete and allocated address is
36 known - this allows us to tunnel media via TCP to the TURN server which
37 is relayed via UDP to the peer
38
39 TurnTlsAllocation - send a TURN allocation request via TLS to the turn server specified and
40 fire an event when the allocation is complete and allocated address is
41 known - this allows us to tunnel media via TCP to the TURN server which
42 is relayed via UDP to the peer
43
44 MediaStreamHandler class passed in will receive event notifications:
45
46 virtual void onMediaStreamReady(const StunTuple& rtpTuple, const StunTuple& rtcpTuple) = 0;
47 virtual void onMediaStreamError(unsigned int errorCode) = 0;
48
49
50
51 Each created Media Stream consists of one or two flows, depending on whether RTCP is enabled
52 or not. The Flow objects can be obtained from the MediaStream via the following MediaStream
53 API's:
54
55 Flow* getRtpFlow();
56 Flow* getRtcpFlow();
57
58
59 Each Flow can then be used to send/receive media after the onMediaStreamReady callback has
60 been received. The following Flow API's are available:
61
62 bool isReady(); // will return true after onMediaStreamReady callback has fired
63
64 /// Returns a socket descriptor that can be used in a select call
65 /// WARNING - this descriptor should not be used for any other purpose
66 /// - do NOT set socket options, or send, receive from this descriptor,
67 /// instead use the Flow api's
68 unsigned int getSelectSocketDescriptor();
69 unsigned int getSocketDescriptor(); // returns the real socket descriptor - can be used to
70 // correlate callbacks
71
72 /// Turn Send Methods
73 void send(const char* buffer, unsigned int size);
74 void sendTo(const asio::ip::address& address, unsigned short port, const char* buffer,
75 unsigned int size);
76
77 /// Receive Methods
78 asio::error_code receive(char* buffer, unsigned int& size, unsigned int timeout,
79 asio::ip::address* sourceAddress=0, unsigned short* sourcePort=0);
80 asio::error_code receiveFrom(const asio::ip::address& address, unsigned short port,
81 char* buffer, unsigned int& size, unsigned int timeout);
82
83 /// Used to set where this flow should be sending to
84 void setActiveDestination(const char* address, unsigned short port);
85
86 const StunTuple& getLocalTuple();
87 StunTuple getSessionTuple(); // returns either local, reflexive, or relay tuple depending
88 // on NatTraversalMode
89 StunTuple getRelayTuple();
90 StunTuple getReflexiveTuple();
91
92
93
94 Using SRTP support in FlowManager
95 ---------------------------------
96
97 DTLS-SRTP Support
98 -----------------
99
100 FlowManager::initializeDtlsFactory must be called during application
101 initialization by passing in an AOR to use in the automatically generated
102 client certificate that may be used with dtls-srtp.
103
104 The following API's on the Flow object are then used to control dtls-srtp:
105 /// Starts the dtls client handshake process - (must call setActiveDestination first)
106 /// Call this method if this client has negotiated the "Active" role via SDP
107 void startDtlsClient(const char* address, unsigned short port);
108
109 /// This method should be called when remote fingerprint is discovered
110 /// via SDP negotiation. After this is called only dtls-srtp connections
111 /// with a matching fingerprint will be maintained.
112 void setRemoteSDPFingerprint(const resip::Data& fingerprint);
113
114
115 SDES SRTP Support
116 -----------------
117
118 If using SDES srtp key negotiation, then the following two API's on the
119 MediaStream object are used in order to initialize the SRTP sessions before
120 sending or receiving on the RTP or RTCP flows.
121
122 bool createOutboundSRTPSession(SrtpCryptoSuite cryptoSuite, const char* key, unsigned int keyLen);
123 bool createInboundSRTPSession(SrtpCryptoSuite cryptoSuite, const char* key, unsigned int keyLen);
124
125
126
127 License
128 -------
129
130 /* ====================================================================
131
132 Copyright (c) 2007-2008, Plantronics, Inc.
133 All rights reserved.
134
135 Redistribution and use in source and binary forms, with or without
136 modification, are permitted provided that the following conditions are
137 met:
138
139 1. Redistributions of source code must retain the above copyright
140 notice, this list of conditions and the following disclaimer.
141
142 2. Redistributions in binary form must reproduce the above copyright
143 notice, this list of conditions and the following disclaimer in the
144 documentation and/or other materials provided with the distribution.
145
146 3. Neither the name of Plantronics nor the names of its contributors
147 may be used to endorse or promote products derived from this
148 software without specific prior written permission.
149
150 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
151 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
152 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
153 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
154 OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
155 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
156 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
157 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
158 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
159 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
160 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
161
162 ==================================================================== */
163

Properties

Name Value
svn:eol-style native
svn:mime-type text/plain

webmaster AT resiprocate DOT org
ViewVC Help
Powered by ViewVC 1.1.27