streamMedia_interface.h

Go to the documentation of this file.
1 
2 
3 /*
4  * ====================== WARNING ======================
5  *
6  * THE CONTENTS OF THIS FILE HAVE BEEN AUTO-GENERATED.
7  * DO NOT MODIFY IN ANY WAY.
8  *
9  * ====================== WARNING ======================
10  */
11 
12 /**
13  * @page c_streamMedia Stream Media API
14  *
15  * @ref streamMedia_interface.h "API Reference" <br>
16  * <HR>
17  *
18  * @warning This interface is experimental and unsupported.
19  *
20  * The Stream Media API handles media streaming interfaces with real-time protocols like RTP.
21  *
22  * The Real-time Transport Protocol is used to stream audio over IP/Ethernet. It is used to
23  * transport any audio stream through an IP or Ethernet network.
24  *
25  * The RTP protocol is augmented by a control protocol called Real-Time Transport Control Protocol
26  * (RTCP), which provides monitoring capabilities on the data delivery and minimum control
27  * functionality.
28  *
29  * More information on the protocol can be found in
30  * <a href="https://tools.ietf.org/pdf/rfc3550.pdf">RFC-3550</a>. A description of the RTP/AVP
31  * profile, which describes generic audio and video conferences, can be found in
32  * <a href="https://tools.ietf.org/pdf/rfc3551.pdf">RFC-3551</a>.
33  *
34  * @note The RTP interface does not provide the full Audio/Video Profile (AVP) profile : it can only
35  * handle a singlecast audio session.
36  *
37  * Typically, the RTP interface can be used to redirect an audio call coming from an audio interface
38  * through an IP network. For example, an IP audio server (Legato platform) would retrieve audio
39  * from any audio interface (e.g. a Modem voice call), and connect it to the RTP interface that
40  * sends the data through an IP network. The data would be received by an IP client (PC, smartphone,
41  * Legato platform) that is able to decode the audio stream.
42  *
43  * @image html AudioOverIP.png
44  *
45  * In order to start a RTP session, information on the local and remote IP address are required to
46  * set up UDP sockets. The local port corresponds to the UDP socket on which RTP packets will be
47  * sent and received, and the remote address and port correspond to the IP address and port on which
48  * RTP packets should be sent.
49  *
50  * @section streamMedia_binding IPC interfaces binding
51  *
52  * All the functions of this API are provided by the @b streamMedia sample service.
53  *
54  * Here's a code sample binding to streamMedia service:
55  * @verbatim
56  bindings:
57  {
58  clientExe.clientComponent.streamMedia -> streamMedia.streamMedia
59  }
60  @endverbatim
61  *
62  * @section streamMedia_interfaces Open/Close an Audio Interface
63  *
64  * The following functions let you select the desired interface attributes:
65  * - streamMedia_OpenAudioRtpRx(): return an Audio Stream Reference of the digitized audio signal
66  * coming from a RTP socket.
67  * - streamMedia_OpenAudioRtpTx(): return an Audio Stream Reference of the digitized audio signal
68  * routed to a RTP socket.
69  *
70  * @section streamMedia_rtp RTP
71  *
72  * The streamMedia_OpenAudioRtpRx() and streamMedia_OpenAudioRtpTx() functions allow the
73  * application to set up a RTP session.
74  *
75  * After opening and connecting a RTP interface, it has to be started using streamMedia_Start().
76  *
77  * You can also register a handler function for RTCP packet reception management.
78  *
79  * streamMedia_AddRtcpHandler() function installs a handler for RTCP Packet reception.
80  *
81  * streamMedia_RemoveRtcpHandler() function removes the RTCP handler function.
82  *
83  * The streamMedia_SendRtcpSdes() and streamMedia_SendRtcpBye() functions allow the
84  * application to send RTCP Session Description (SDES) or BYE packet.
85  *
86  * The RTCP SDES packet can be used to mark the beginning of the RTP session. It is composed of
87  * several optional text fields that can provide information about the user's name, email address,
88  * etc... See streamMedia_SendRtcpSdes() for more details.
89  *
90  * The RTCP BYE packet can be used to mark the end of the RTP session. It is possible to specify the
91  * reason. See streamMedia_SendRtcpBye() for more details.
92  *
93  * More information on the RTCP SDES and BYE packets can be found in
94  * <a href="https://tools.ietf.org/pdf/rfc3550.pdf">RFC-3550</a>.
95  *
96  * Before disconnecting and closing a RTP interface, it has to be stopped using
97  * streamMedia_Stop(). Then, after disconnecting the interface from the connector,
98  * streamMedia_Close() is called to close it.
99  *
100  * @note The RTP interface requires one more UDP socket in order to send and receive RTCP packets.
101  * The RTCP UDP socket port number is automatically set to the local RTP port plus one.
102  *
103  * @section streamMedia_code Sample code
104  *
105  * The following samples illustrate the case described in the image above. It consists of two
106  * different devices that communicate through RTP over an IP network. One device handles a modem
107  * voice call, and the other one handles the microphone and speaker.
108  *
109  * @warning The following codes show a basic example of how to transmit audio through RTP between
110  * two peers. Quality of service is not provided in those samples. They just show how the
111  * streamMedia API should work and how it should be used.
112  *
113  * This first sample code is related to the RTP peer that handles the modem voice call.
114  *
115  * @code
116  *
117  * // Peer 1 : connection between a modem voice call and a RTP session.
118  *
119  * static void MyCallEventHandler
120  * (
121  * le_mcc_CallRef_t callRef,
122  * le_mcc_Event_t callEvent,
123  * void* contextPtr
124  * )
125  * {
126  * if (callEvent == LE_MCC_EVENT_TERMINATED)
127  * {
128  * le_mcc_TerminationReason_t term = le_mcc_GetTerminationReason(callRef);
129  * le_mcc_Delete(callRef);
130  * DisconnectAllAudio(); // Not showed here, would disconnect all audio.
131  * }
132  * else if (callEvent == LE_MCC_EVENT_INCOMING)
133  * {
134  * le_mcc_Answer(callRef);
135  * }
136  * else
137  * {
138  * LE_INFO("Other Call event.%d", callEvent);
139  * }
140  * }
141  *
142  * static void MyRtcpEventHandler
143  * (
144  * le_audio_StreamRef_t streamRef,
145  * streamMedia_RtcpEvent_t event,
146  * void* contextPtr
147  * )
148  * {
149  * switch (event)
150  * {
151  * case STREAMMEDIA_RTCP_BYE:
152  * DisconnectAllAudio(); // Not showed here, would disconnect all audio.
153  * break;
154  * default:
155  * LE_INFO("Other event");
156  * break;
157  * }
158  * }
159  *
160  * void ConnectModemToRtp
161  * (
162  * void
163  * )
164  * {
165  * static le_audio_ConnectorRef_t audioInputConnectorRef = NULL;
166  * static le_audio_ConnectorRef_t audioOutputConnectorRef = NULL;
167  * static le_audio_StreamRef_t rtpInRef = NULL;
168  * static le_audio_StreamRef_t rtpOutRef = NULL;
169  * static le_audio_StreamRef_t mdmRxAudioRef = NULL;
170  * static le_audio_StreamRef_t mdmTxAudioRef = NULL;
171  * static le_mcc_CallRef_t callRef = NULL;
172  * const char* remoteAddress = "10.40.58.2";
173  * const char* destinationNumber = "0123456789";
174  * int localPort = 4000;
175  * int remotePort = 4000;
176  *
177  * rtpInRef = streamMedia_OpenAudioRtpRx(localPort);
178  * rtpOutRef = streamMedia_OpenAudioRtpTx(localPort, remoteAddress, remotePort);
179  *
180  * mdmRxAudioRef = le_audio_OpenModemVoiceRx();
181  * mdmTxAudioRef = le_audio_OpenModemVoiceTx();
182  *
183  * audioInputConnectorRef = le_audio_CreateConnector();
184  * audioOutputConnectorRef = le_audio_CreateConnector();
185  *
186  * le_audio_Connect(audioOutputConnectorRef, mdmTxAudioRef);
187  * le_audio_Connect(audioInputConnectorRef, mdmRxAudioRef);
188  *
189  * le_audio_Connect(audioOutputConnectorRef, rtpInRef);
190  * streamMedia_Start(rtpInRef);
191  *
192  * le_audio_Connect(audioInputConnectorRef, rtpOutRef);
193  * streamMedia_Start(rtpOutRef);
194  *
195  * streamMedia_AddRtcpHandler(rtpInRef, MyRtcpEventHandler, NULL);
196  *
197  * le_mcc_AddCallEventHandler(MyCallEventHandler, NULL);
198  * callRef=le_mcc_Create(destinationNumber);
199  * le_mcc_Start(callRef);
200  * }
201  *
202  * @endcode
203  *
204  * This sample code shows how to connect RTP to microphone and speaker.
205  *
206  * @code
207  *
208  * // Peer 2 : connection between a RTP session and microphone and speaker.
209  *
210  * static void MyRtcpEventHandler
211  * (
212  * le_audio_StreamRef_t streamRef,
213  * streamMedia_RtcpEvent_t event,
214  * void* contextPtr
215  * )
216  * {
217  * switch (event)
218  * {
219  * case STREAMMEDIA_RTCP_BYE:
220  * DisconnectAllAudio(); // Not showed here, would disconnect all audio.
221  * break;
222  * default:
223  * LE_INFO("Other event");
224  * break;
225  * }
226  * }
227  *
228  * void RecordFileFromRtp
229  * (
230  * void
231  * )
232  * {
233  * static le_audio_ConnectorRef_t audioInputConnectorRef = NULL;
234  * static le_audio_ConnectorRef_t audioOutputConnectorRef = NULL;
235  * static le_audio_StreamRef_t rtpInRef = NULL;
236  * static le_audio_StreamRef_t rtpOutRef = NULL;
237  * static le_audio_StreamRef_t micAudioRef = NULL;
238  * static le_audio_StreamRef_t speakerAudioRef = NULL;
239  * const char* remoteAddress = "10.40.58.2";
240  * int localPort = 4000;
241  * int remotePort = 4000;
242  *
243  * rtpInRef = streamMedia_OpenAudioRtpRx(localPort);
244  * rtpOutRef = streamMedia_OpenAudioRtpTx(localPort, remoteAddress, remotePort);
245  *
246  * micAudioRef = le_audio_OpenMic();
247  * speakerAudioRef = le_audio_OpenSpeaker();
248  *
249  * audioInputConnectorRef = le_audio_CreateConnector();
250  * audioOutputConnectorRef = le_audio_CreateConnector();
251  *
252  * le_audio_Connect(audioOutputConnectorRef, speakerAudioRef);
253  * le_audio_Connect(audioInputConnectorRef, micAudioRef);
254  *
255  * le_audio_Connect(audioOutputConnectorRef, rtpInRef);
256  * streamMedia_Start(rtpInRef);
257  *
258  * le_audio_Connect(audioInputConnectorRef, rtpOutRef);
259  * streamMedia_Start(rtpOutRef);
260  *
261  * streamMedia_AddRtcpHandler(rtpInRef, MyRtcpEventHandler, NULL);
262  * }
263  *
264  * @endcode
265  *
266  * @section streamMedia_warning Known limitations
267  *
268  * The RTP interface must be connected and disconnected in this specific order :
269  * - First connect the RTP reception stream, and then the transmission one.
270  * - When disconnecting it, start by the transmission stream, and then disconnect the reception one.
271  *
272  * The streamMedia API provided by the streamMedia sample application is not suitable for
273  * real-time communication applications because of the too high latency.
274  * A delay of 500 ms has been measured on a one-sided RTP session (RTP transmission only) on a WP85
275  * module. Thus, the "Audio over IP" use case described above shows a latency of more than one
276  * second due to the two-sided RTP session (transmission on one module and reception on the other).
277  * However, the streamMedia API can be used for any streaming purposes where a delay of one second
278  * is acceptable.
279  *
280  * The streamMedia application has been tested on WP85 and AR8652.
281  *
282  * <HR>
283  *
284  * Copyright (C) Sierra Wireless Inc.
285  */
286 /**
287  * @file streamMedia_interface.h
288  *
289  * Legato @ref sampleApps_streamMedia include file.
290  *
291  * Copyright (C) Sierra Wireless Inc.
292  */
293 
294 #ifndef STREAMMEDIA_INTERFACE_H_INCLUDE_GUARD
295 #define STREAMMEDIA_INTERFACE_H_INCLUDE_GUARD
296 
297 
298 #include "legato.h"
299 
300 // Interface specific includes
301 #include "le_audio_interface.h"
302 
303 // Internal includes for this interface
304 #include "streamMedia_common.h"
305 //--------------------------------------------------------------------------------------------------
306 /**
307  * Type for handler called when a server disconnects.
308  */
309 //--------------------------------------------------------------------------------------------------
310 typedef void (*streamMedia_DisconnectHandler_t)(void *);
311 
312 //--------------------------------------------------------------------------------------------------
313 /**
314  *
315  * Connect the current client thread to the service providing this API. Block until the service is
316  * available.
317  *
318  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
319  * called before any other functions in this API. Normally, ConnectService is automatically called
320  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
321  *
322  * This function is created automatically.
323  */
324 //--------------------------------------------------------------------------------------------------
326 (
327  void
328 );
329 
330 //--------------------------------------------------------------------------------------------------
331 /**
332  *
333  * Try to connect the current client thread to the service providing this API. Return with an error
334  * if the service is not available.
335  *
336  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
337  * called before any other functions in this API. Normally, ConnectService is automatically called
338  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
339  *
340  * This function is created automatically.
341  *
342  * @return
343  * - LE_OK if the client connected successfully to the service.
344  * - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
345  * bound.
346  * - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
347  * - LE_COMM_ERROR if the Service Directory cannot be reached.
348  */
349 //--------------------------------------------------------------------------------------------------
351 (
352  void
353 );
354 
355 //--------------------------------------------------------------------------------------------------
356 /**
357  * Set handler called when server disconnection is detected.
358  *
359  * When a server connection is lost, call this handler then exit with LE_FATAL. If a program wants
360  * to continue without exiting, it should call longjmp() from inside the handler.
361  */
362 //--------------------------------------------------------------------------------------------------
364 (
365  streamMedia_DisconnectHandler_t disconnectHandler,
366  void *contextPtr
367 );
368 
369 //--------------------------------------------------------------------------------------------------
370 /**
371  *
372  * Disconnect the current client thread from the service providing this API.
373  *
374  * Normally, this function doesn't need to be called. After this function is called, there's no
375  * longer a connection to the service, and the functions in this API can't be used. For details, see
376  * @ref apiFilesC_client.
377  *
378  * This function is created automatically.
379  */
380 //--------------------------------------------------------------------------------------------------
382 (
383  void
384 );
385 
386 
387 //--------------------------------------------------------------------------------------------------
388 /**
389  * RTCP packet reception events, related to the RTCP packet type. See
390  * <a href="https://tools.ietf.org/pdf/rfc3550.pdf">RFC-3550</a> for more details.
391  */
392 //--------------------------------------------------------------------------------------------------
393 
394 
395 //--------------------------------------------------------------------------------------------------
396 /**
397  * Handler for RTCP packet reception.
398  *
399  */
400 //--------------------------------------------------------------------------------------------------
401 
402 
403 //--------------------------------------------------------------------------------------------------
404 /**
405  * Reference type used by Add/Remove functions for EVENT 'streamMedia_Rtcp'
406  */
407 //--------------------------------------------------------------------------------------------------
408 
409 
410 //--------------------------------------------------------------------------------------------------
411 /**
412  * Open the received audio stream of the RTP interface.
413  *
414  * @return Reference to the input audio stream, NULL if the function fails.
415  */
416 //--------------------------------------------------------------------------------------------------
417 le_audio_StreamRef_t streamMedia_OpenAudioRtpRx
418 (
419  int32_t localPort
420  ///< [IN] The local UDP socket port for the RTP session.
421 );
422 
423 //--------------------------------------------------------------------------------------------------
424 /**
425  * Open the transmitted audio stream of the RTP interface.
426  *
427  * @return Reference to the output audio stream, NULL if the function fails.
428  */
429 //--------------------------------------------------------------------------------------------------
430 le_audio_StreamRef_t streamMedia_OpenAudioRtpTx
431 (
432  int32_t localPort,
433  ///< [IN] The local UDP socket port for the RTP
434  ///< session.
435  const char* LE_NONNULL remoteIpAddress,
436  ///< [IN] The IP address of the remote peer.
437  int32_t remotePort
438  ///< [IN] The port of the remote peer.
439 );
440 
441 //--------------------------------------------------------------------------------------------------
442 /**
443  * Start the RTP stream. This must be called after connecting the RTP interface to start
444  * RTP reception or transmission.
445  *
446  * @return LE_FAULT Function failed.
447  * @return LE_OK Function succeeded.
448  */
449 //--------------------------------------------------------------------------------------------------
451 (
452  le_audio_StreamRef_t streamRef
453  ///< [IN] Audio stream reference.
454 );
455 
456 //--------------------------------------------------------------------------------------------------
457 /**
458  * Stop the RTP stream.
459  *
460  * @return LE_FAULT Function failed.
461  * @return LE_OK Function succeeded.
462  */
463 //--------------------------------------------------------------------------------------------------
465 (
466  le_audio_StreamRef_t streamRef
467  ///< [IN] Audio stream reference.
468 );
469 
470 //--------------------------------------------------------------------------------------------------
471 /**
472  * Send a RTCP Session Description packet (SDES) using
473  * <a href="http://www.pjsip.org/pjmedia/docs/html/group__PJMED__RTCP.htm#
474  * ga8ddca87e2b3ab0b02635edd66d7de748">pjmedia_rtcp_build_rtcp_sdes()</a>.
475  *
476  * @return LE_FAULT Function failed.
477  * @return LE_OK Function succeeded.
478  */
479 //--------------------------------------------------------------------------------------------------
481 (
482  le_audio_StreamRef_t streamRef,
483  ///< [IN] Audio stream reference.
484  const char* LE_NONNULL cname,
485  ///< [IN] The optional source canonical name.
486  const char* LE_NONNULL name,
487  ///< [IN] The optional source name.
488  const char* LE_NONNULL email,
489  ///< [IN] The optional source email.
490  const char* LE_NONNULL phone,
491  ///< [IN] The optional source phone.
492  const char* LE_NONNULL loc,
493  ///< [IN] The optional source location.
494  const char* LE_NONNULL tool,
495  ///< [IN] The optional source tool.
496  const char* LE_NONNULL note
497  ///< [IN] The optional source note.
498 );
499 
500 //--------------------------------------------------------------------------------------------------
501 /**
502  * Send a RTCP BYE packet using
503  * <a href="http://www.pjsip.org/pjmedia/docs/html/group__PJMED__RTCP.htm#
504  * ga9eb25597d5815cee68fe7fdc3b4cd9e9">pjmedia_rtcp_build_rtcp_bye()</a>.
505  *
506  * @return LE_FAULT Function failed.
507  * @return LE_OK Function succeeded.
508  */
509 //--------------------------------------------------------------------------------------------------
511 (
512  le_audio_StreamRef_t streamRef,
513  ///< [IN] Audio stream reference.
514  const char* LE_NONNULL reason
515  ///< [IN] The optional BYE reason.
516 );
517 
518 //--------------------------------------------------------------------------------------------------
519 /**
520  * Close an RTP stream.
521  *
522  */
523 //--------------------------------------------------------------------------------------------------
525 (
526  le_audio_StreamRef_t streamRef
527  ///< [IN] Audio stream reference.
528 );
529 
530 //--------------------------------------------------------------------------------------------------
531 /**
532  * Add handler function for EVENT 'streamMedia_Rtcp'
533  *
534  * This event provides information on RTCP packet type.
535  *
536  */
537 //--------------------------------------------------------------------------------------------------
538 streamMedia_RtcpHandlerRef_t streamMedia_AddRtcpHandler
539 (
540  le_audio_StreamRef_t streamRef,
541  ///< [IN] Audio stream reference.
542  streamMedia_RtcpHandlerFunc_t handlerPtr,
543  ///< [IN]
544  void* contextPtr
545  ///< [IN]
546 );
547 
548 //--------------------------------------------------------------------------------------------------
549 /**
550  * Remove handler function for EVENT 'streamMedia_Rtcp'
551  */
552 //--------------------------------------------------------------------------------------------------
554 (
555  streamMedia_RtcpHandlerRef_t handlerRef
556  ///< [IN]
557 );
558 
559 #endif // STREAMMEDIA_INTERFACE_H_INCLUDE_GUARD
le_result_t streamMedia_SendRtcpBye(le_audio_StreamRef_t streamRef, const char *LE_NONNULL reason)
le_result_t
Definition: le_basics.h:35
void(* streamMedia_DisconnectHandler_t)(void *)
Definition: streamMedia_interface.h:310
le_audio_StreamRef_t streamMedia_OpenAudioRtpRx(int32_t localPort)
streamMedia_RtcpHandlerRef_t streamMedia_AddRtcpHandler(le_audio_StreamRef_t streamRef, streamMedia_RtcpHandlerFunc_t handlerPtr, void *contextPtr)
le_result_t streamMedia_Stop(le_audio_StreamRef_t streamRef)
void streamMedia_DisconnectService(void)
le_result_t streamMedia_Start(le_audio_StreamRef_t streamRef)
LE_FULL_API void streamMedia_SetServerDisconnectHandler(streamMedia_DisconnectHandler_t disconnectHandler, void *contextPtr)
void streamMedia_RemoveRtcpHandler(streamMedia_RtcpHandlerRef_t handlerRef)
le_audio_StreamRef_t streamMedia_OpenAudioRtpTx(int32_t localPort, const char *LE_NONNULL remoteIpAddress, int32_t remotePort)
le_result_t streamMedia_TryConnectService(void)
void streamMedia_ConnectService(void)
#define LE_FULL_API
Definition: le_basics.h:288
void streamMedia_Close(le_audio_StreamRef_t streamRef)
le_result_t streamMedia_SendRtcpSdes(le_audio_StreamRef_t streamRef, const char *LE_NONNULL cname, const char *LE_NONNULL name, const char *LE_NONNULL email, const char *LE_NONNULL phone, const char *LE_NONNULL loc, const char *LE_NONNULL tool, const char *LE_NONNULL note)