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