Group PJMED_TXT_STRM

group PJMED_TXT_STRM

Text communication via the network.

A text stream is a bidirectional real-time text (RTT) communication between two endpoints as specified in RFC 4103. It corresponds to a text media description (“m=text” line) in SDP session descriptor.

A text stream consists of two unidirectional channels:

  • encoding channel, which transmits unidirectional text to remote, and

  • decoding channel, which receives unidirectional text from remote.

A text stream internally manages the following objects:

Text streams are created by calling pjmedia_txt_stream_create(), specifying pjmedia_txt_stream_info structure in the parameter. Application can construct the pjmedia_txt_stream_info structure manually, or use pjmedia_txt_stream_info_from_sdp() function to construct the pjmedia_txt_stream_info from local and remote SDP session descriptors.

Typedefs

typedef struct pjmedia_txt_stream pjmedia_txt_stream

Functions

pj_status_t pjmedia_txt_stream_info_from_sdp(pjmedia_txt_stream_info *si, pj_pool_t *pool, pjmedia_endpt *endpt, const pjmedia_sdp_session *local, const pjmedia_sdp_session *remote, unsigned stream_idx)

This function will initialize the text stream info based on information in both SDP session descriptors for the specified text stream index.

Parameters:

  • si – Text stream info structure to be initialized.

  • pool – Pool to allocate memory.

  • endpt – PJMEDIA endpoint instance.

  • local – Local SDP session descriptor.

  • remote – Remote SDP session descriptor.

  • stream_idx – Text media stream index in the session descriptor.

Returns:

PJ_SUCCESS if stream info is successfully initialized.

pj_status_t pjmedia_txt_stream_create(pjmedia_endpt *endpt, pj_pool_t *pool, const pjmedia_txt_stream_info *info, pjmedia_transport *tp, void *user_data, pjmedia_txt_stream **p_stream)

Create a text stream based on the specified parameter.

Parameters:

  • endpt – Media endpoint.

  • pool – Pool to allocate memory for the stream.

  • info – Stream information.

  • tp – Media transport instance used to transmit and receive RTP/RTCP packets to/from the underlying transport.

  • user_data – Arbitrary user data (for future callback feature).

  • p_stream – Pointer to receive the text stream.

Returns:

PJ_SUCCESS on success.

pj_status_t pjmedia_txt_stream_destroy(pjmedia_txt_stream *stream)

Destroy the text stream.

Parameters:

stream – The text stream.

Returns:

PJ_SUCCESS on success.

pj_status_t pjmedia_txt_stream_send_text(pjmedia_txt_stream *stream, const pj_str_t *text)

Send text using the text stream.

Parameters:

  • stream – The text stream.

  • text – Text to be sent.

Returns:

PJ_SUCCESS on success.

pj_status_t pjmedia_txt_stream_start(pjmedia_txt_stream *stream)

Start the text stream. This will start the appropriate channels in the text stream, depending on the media direction that was set when the stream was created.

Parameters:

stream – The text stream.

Returns:

PJ_SUCCESS on success.

pj_status_t pjmedia_txt_stream_set_rx_callback(pjmedia_txt_stream *stream, void (*cb)(pjmedia_txt_stream*, void *user_data, const pjmedia_txt_stream_data *data), void *user_data, unsigned option)

Set callback to be called upon receiving text data.

IMPORTANT: Application shall not destroy the text stream from within the callback.

Parameters:

  • stream – The text stream.

  • cb – Callback to be called upon receiving text data. See pjmedia_txt_stream_data.

  • user_data – User data to be returned back when the callback is called.

  • option – Option, must be 0 for now.

Returns:

PJ_SUCCESS on success.

pj_status_t pjmedia_txt_stream_get_info(const pjmedia_txt_stream *stream, pjmedia_txt_stream_info *info)

Get the stream info.

Parameters:

  • stream – The text stream.

  • info – Stream info.

Returns:

PJ_SUCCESS on success.

struct pjmedia_txt_stream_info
#include <txt_stream.h>

This structure describes text stream information. Each text stream corresponds to one “m=text” line in SDP session descriptor, and it has its own RTP/RTCP socket pair.

Public Members

pjmedia_codec_info fmt

Incoming codec format info.

pjmedia_codec_fmtp enc_fmtp

Encoder’s fmtp params.

pjmedia_codec_fmtp dec_fmtp

Decoder’s fmtp params.

unsigned buffer_time

Buffering time.

struct pjmedia_txt_stream_data
#include <txt_stream.h>

This structure describes the text data passed in the callback set via pjmedia_txt_stream_set_rx_callback().

Public Members

int seq

Sequence.

pj_uint32_t ts

Timestamp.

pj_str_t text

The incoming text data.