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 /** @addtogroup streamMedia streamMedia API Reference
306  * @{
307  * @file streamMedia_common.h
308  * @file streamMedia_interface.h **/
309 //--------------------------------------------------------------------------------------------------
310 /**
311  * Type for handler called when a server disconnects.
312  */
313 //--------------------------------------------------------------------------------------------------
314 typedef void (*streamMedia_DisconnectHandler_t)(void *);
315 
316 //--------------------------------------------------------------------------------------------------
317 /**
318  *
319  * Connect the current client thread to the service providing this API. Block until the service is
320  * available.
321  *
322  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
323  * called before any other functions in this API. Normally, ConnectService is automatically called
324  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
325  *
326  * This function is created automatically.
327  */
328 //--------------------------------------------------------------------------------------------------
330 (
331  void
332 );
333 
334 //--------------------------------------------------------------------------------------------------
335 /**
336  *
337  * Try to connect the current client thread to the service providing this API. Return with an error
338  * if the service is not available.
339  *
340  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
341  * called before any other functions in this API. Normally, ConnectService is automatically called
342  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
343  *
344  * This function is created automatically.
345  *
346  * @return
347  * - LE_OK if the client connected successfully to the service.
348  * - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
349  * bound.
350  * - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
351  * - LE_COMM_ERROR if the Service Directory cannot be reached.
352  */
353 //--------------------------------------------------------------------------------------------------
355 (
356  void
357 );
358 
359 //--------------------------------------------------------------------------------------------------
360 /**
361  * Set handler called when server disconnection is detected.
362  *
363  * When a server connection is lost, call this handler then exit with LE_FATAL. If a program wants
364  * to continue without exiting, it should call longjmp() from inside the handler.
365  */
366 //--------------------------------------------------------------------------------------------------
368 (
369  streamMedia_DisconnectHandler_t disconnectHandler,
370  void *contextPtr
371 );
372 
373 //--------------------------------------------------------------------------------------------------
374 /**
375  *
376  * Disconnect the current client thread from the service providing this API.
377  *
378  * Normally, this function doesn't need to be called. After this function is called, there's no
379  * longer a connection to the service, and the functions in this API can't be used. For details, see
380  * @ref apiFilesC_client.
381  *
382  * This function is created automatically.
383  */
384 //--------------------------------------------------------------------------------------------------
386 (
387  void
388 );
389 
390 
391 //--------------------------------------------------------------------------------------------------
392 /**
393  * RTCP packet reception events, related to the RTCP packet type. See
394  * <a href="https://tools.ietf.org/pdf/rfc3550.pdf">RFC-3550</a> for more details.
395  */
396 //--------------------------------------------------------------------------------------------------
397 
398 
399 //--------------------------------------------------------------------------------------------------
400 /**
401  * Handler for RTCP packet reception.
402  *
403  */
404 //--------------------------------------------------------------------------------------------------
405 
406 
407 //--------------------------------------------------------------------------------------------------
408 /**
409  * Reference type used by Add/Remove functions for EVENT 'streamMedia_Rtcp'
410  */
411 //--------------------------------------------------------------------------------------------------
412 
413 
414 //--------------------------------------------------------------------------------------------------
415 /**
416  * Open the received audio stream of the RTP interface.
417  *
418  * @return Reference to the input audio stream, NULL if the function fails.
419  */
420 //--------------------------------------------------------------------------------------------------
422 (
423  int32_t localPort
424  ///< [IN] The local UDP socket port for the RTP session.
425 );
426 
427 //--------------------------------------------------------------------------------------------------
428 /**
429  * Open the transmitted audio stream of the RTP interface.
430  *
431  * @return Reference to the output audio stream, NULL if the function fails.
432  */
433 //--------------------------------------------------------------------------------------------------
435 (
436  int32_t localPort,
437  ///< [IN] The local UDP socket port for the RTP
438  ///< session.
439  const char* LE_NONNULL remoteIpAddress,
440  ///< [IN] The IP address of the remote peer.
441  int32_t remotePort
442  ///< [IN] The port of the remote peer.
443 );
444 
445 //--------------------------------------------------------------------------------------------------
446 /**
447  * Start the RTP stream. This must be called after connecting the RTP interface to start
448  * RTP reception or transmission.
449  *
450  * @return LE_FAULT Function failed.
451  * @return LE_OK Function succeeded.
452  */
453 //--------------------------------------------------------------------------------------------------
455 (
456  le_audio_StreamRef_t streamRef
457  ///< [IN] Audio stream reference.
458 );
459 
460 //--------------------------------------------------------------------------------------------------
461 /**
462  * Stop the RTP stream.
463  *
464  * @return LE_FAULT Function failed.
465  * @return LE_OK Function succeeded.
466  */
467 //--------------------------------------------------------------------------------------------------
469 (
470  le_audio_StreamRef_t streamRef
471  ///< [IN] Audio stream reference.
472 );
473 
474 //--------------------------------------------------------------------------------------------------
475 /**
476  * Send a RTCP Session Description packet (SDES) using
477  * <a href="http://www.pjsip.org/pjmedia/docs/html/group__PJMED__RTCP.htm#
478  * ga8ddca87e2b3ab0b02635edd66d7de748">pjmedia_rtcp_build_rtcp_sdes()</a>.
479  *
480  * @return LE_FAULT Function failed.
481  * @return LE_OK Function succeeded.
482  */
483 //--------------------------------------------------------------------------------------------------
485 (
486  le_audio_StreamRef_t streamRef,
487  ///< [IN] Audio stream reference.
488  const char* LE_NONNULL cname,
489  ///< [IN] The optional source canonical name.
490  const char* LE_NONNULL name,
491  ///< [IN] The optional source name.
492  const char* LE_NONNULL email,
493  ///< [IN] The optional source email.
494  const char* LE_NONNULL phone,
495  ///< [IN] The optional source phone.
496  const char* LE_NONNULL loc,
497  ///< [IN] The optional source location.
498  const char* LE_NONNULL tool,
499  ///< [IN] The optional source tool.
500  const char* LE_NONNULL note
501  ///< [IN] The optional source note.
502 );
503 
504 //--------------------------------------------------------------------------------------------------
505 /**
506  * Send a RTCP BYE packet using
507  * <a href="http://www.pjsip.org/pjmedia/docs/html/group__PJMED__RTCP.htm#
508  * ga9eb25597d5815cee68fe7fdc3b4cd9e9">pjmedia_rtcp_build_rtcp_bye()</a>.
509  *
510  * @return LE_FAULT Function failed.
511  * @return LE_OK Function succeeded.
512  */
513 //--------------------------------------------------------------------------------------------------
515 (
516  le_audio_StreamRef_t streamRef,
517  ///< [IN] Audio stream reference.
518  const char* LE_NONNULL reason
519  ///< [IN] The optional BYE reason.
520 );
521 
522 //--------------------------------------------------------------------------------------------------
523 /**
524  * Close an RTP stream.
525  *
526  */
527 //--------------------------------------------------------------------------------------------------
529 (
530  le_audio_StreamRef_t streamRef
531  ///< [IN] Audio stream reference.
532 );
533 
534 //--------------------------------------------------------------------------------------------------
535 /**
536  * Add handler function for EVENT 'streamMedia_Rtcp'
537  *
538  * This event provides information on RTCP packet type.
539  *
540  */
541 //--------------------------------------------------------------------------------------------------
543 (
544  le_audio_StreamRef_t streamRef,
545  ///< [IN] Audio stream reference.
547  ///< [IN]
548  void* contextPtr
549  ///< [IN]
550 );
551 
552 //--------------------------------------------------------------------------------------------------
553 /**
554  * Remove handler function for EVENT 'streamMedia_Rtcp'
555  */
556 //--------------------------------------------------------------------------------------------------
558 (
560  ///< [IN]
561 );
562 
563 /** @} **/
564 
565 #endif // STREAMMEDIA_INTERFACE_H_INCLUDE_GUARD
LE_FULL_API void streamMedia_SetServerDisconnectHandler(streamMedia_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_result_t
Definition: le_basics.h:46
void streamMedia_RemoveRtcpHandler(streamMedia_RtcpHandlerRef_t handlerRef)
void streamMedia_ConnectService(void)
le_audio_StreamRef_t streamMedia_OpenAudioRtpRx(int32_t localPort)
void streamMedia_DisconnectService(void)
void(* streamMedia_RtcpHandlerFunc_t)(le_audio_StreamRef_t streamRef, streamMedia_RtcpEvent_t event, void *contextPtr)
Definition: streamMedia_common.h:96
le_result_t streamMedia_TryConnectService(void)
le_result_t streamMedia_Stop(le_audio_StreamRef_t streamRef)
void(* streamMedia_DisconnectHandler_t)(void *)
Definition: streamMedia_interface.h:314
le_result_t streamMedia_SendRtcpBye(le_audio_StreamRef_t streamRef, const char *LE_NONNULL reason)
#define LE_FULL_API
Definition: le_apiFeatures.h:40
le_result_t streamMedia_Start(le_audio_StreamRef_t streamRef)
struct le_audio_Stream * le_audio_StreamRef_t
Definition: le_audio_common.h:191
le_audio_StreamRef_t streamMedia_OpenAudioRtpTx(int32_t localPort, const char *LE_NONNULL remoteIpAddress, int32_t remotePort)
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)
void streamMedia_Close(le_audio_StreamRef_t streamRef)
streamMedia_RtcpHandlerRef_t streamMedia_AddRtcpHandler(le_audio_StreamRef_t streamRef, streamMedia_RtcpHandlerFunc_t handlerPtr, void *contextPtr)
struct streamMedia_RtcpHandler * streamMedia_RtcpHandlerRef_t
Definition: streamMedia_common.h:86