MediaSocket

primo::avblocks::MediaSocket

class MediaSocket : public primo::Reference

An input or output point of the Transcoder.

A MediaSocket object describes either a container (WAV, AVI, MP4, etc.) with one or more streams or simply an elementary stream (MP3, M2V, etc.).

When MediaSocket describes a container the child collection of media pins can contain one or more items (for each contained stream). The socket stream type designates the container type.

When MediaSocket describes an elementary stream the child collection of media pins contains a single item which is the elementary stream itself. The socket stream type is the same as the pin stream type.

See also

Library::createMediaSocket

See also

Object Management

Public Functions

virtual MediaSocket *clone() const = 0

Creates a deep copy of this object.

Remark

When cloned an immutable object becomes mutable.

See also

Object Management

Returns:

A new MediaSocket

object.

The caller is responsible for releasing the new object when it is not needed anymore.

Returns:

NULL if there is not enough memory to clone the object.

virtual bool_t setFile(const char_t *filename) = 0

Sets the file associated with the media socket.

Parameters:

filename – [in] a filename as a Unicode zero terminated string. If NULL the filename is cleared. When not NULL the filename is copied internally and is not required after the method returns.

Returns:

TRUE if the file name is successfully set, otherwise FALSE.

virtual const char_t *file() const = 0

Returns the file associated with the media socket and previously set via setFile().

Returns:

A filename as a Unicode zero terminated string. Can be NULL if the file is not set. The default value is NULL.

virtual bool_t setStream(primo::Stream *stream) = 0

Sets the user stream associated with the media socket.

This is an alternative to setFile().

When both a file and a user stream are associated with a socket the transcoder prefers the stream.

See also

Object Management

Parameters:

stream – [in] A pointer to a Stream object. If NULL the stream object is cleared. Internally the Stream object is retained by MediaSocket, so it is safe to release it after this method returns.

Returns:

TRUE if the stream is successfully set, otherwise FALSE.

virtual primo::Stream *stream() const = 0

Returns the associated user stream previously set via setStream().

Returns:

A Stream object. Can be NULL if the associated stream is not set. The default value is NULL.

virtual bool_t setStreamType(primo::codecs::StreamType::Enum streamType) = 0

Sets explicitly the format of the associated file or stream.

The Transcoder uses this format and the associated file or stream according to following rules:

File	Stream	Type	How MediaSocket is treated by Transcoder
Y	N	N	OK - the socket defines a file whose type is implicitly determined by the file extension.
Y	N	Y	OK - the socket defines a file whose type is explicitly specified by the stream type.
Y,N	Y	Y	OK - the socket defines a user stream whose type is explicitly specified.
Y,N	Y	N	Error - the socket defines a user stream but its type is unknown.
N	N	Y	OK - the socket does not have a physical storage. it only describes the input/output data. This is the required definition for input sockets when the push() method is used and also the required definition for output sockets when the pull() method is used.
N	N	N	Error - undefined socket.

See also

primo::codecs::StreamType

Parameters:

streamType – [in] stream type such as AVI, WAV, MP4, etc.

Returns:

TRUE if the stream type is successfully set, otherwise FALSE.

virtual primo::codecs::StreamType::Enum streamType() const = 0

Returns the stream type of the associated file or user stream.

Returns:

stream type. If not set StreamType::Unknown is returned.

virtual bool_t setStreamSubType(primo::codecs::StreamSubType::Enum streamSubType) = 0

Sets explicitly the stream subtype of the associated file or user stream.

Returns:

TRUE if the stream subtype is successfully set, otherwise FALSE.

virtual primo::codecs::StreamSubType::Enum streamSubType() const = 0

Returns the stream subtype of the associated file or user stream.

Returns:

stream subtype. If not set StreamSubType::Unknown is returned.

virtual ParameterList *params() const = 0

Returns a collection of socket parameters.

These parameters are used when splitting the input or multiplexing the output defined by this media socket.

The caller is not required to release the returned object.

See also

Object Management

Returns:

A ParameterList object. Can be NULL if the collection is not set. The default value is an empty list.

virtual bool_t setParams(ParameterList *params) = 0

Sets the socket parameters.

See also

Object Management

Parameters:

params – [in] A pointer to a ParameterList object. If NULL the stored collection is reset to NULL. Internally the ParameterList object is retained by MediaSocket, so it is safe to release it after this method returns.

virtual MediaPinList *pins() const = 0

Returns a modifiable collection with all the pins (elementary streams) that are defined for this socket.

The returned collection exists only in the context of MediaSocket. The caller cannot influence the lifetime of the returned object.

Returns:

A collection of MediaPin objects. The default value is an empty collection which can be modified but it cannot be replaced.

virtual bool_t setTimePosition(double time) = 0

Sets the socket time position.

This property can be used on an input socket to start reading / decoding from a specific point in time. The transcoder tries to seek in the input socket to the time position before the transcoding operation starts.

Seeking is not possible while transcoder is open. Transcoder need to be closed before setting new time possition.

Parameters:

time – [in] Time position in seconds.

Returns:

TRUE if the time position is successfully set, otherwise FALSE.

virtual double timePosition() const = 0

Returns the socket time position.

This property can be used on an input socket to start reading / decoding from a specific point in time. The transcoder tries to seek in the input socket to the time position before the transcoding operation starts.

Returns:

Time position in seconds.

virtual primo::codecs::Metadata *metadata() const = 0

Returns the socket metadata.

Returns:

A pointer to a Metadata object. Can be NULL if the socket has no metadata.

virtual bool_t setMetadata(primo::codecs::Metadata *metadata) = 0

Sets the socket metadata.

When an output socket has metadata the transcoder tries to generate it regardless of the input metadata. When an output socket has no metadata (NULL) but an input socket has metadata (not NULL) the transcoder uses the input metadata as if it is set for the output.

Parameters:

metadata – [in] A pointer to a Metadata object. Can be NULL in which case the metadata is cleared from the socket.

Returns:

TRUE if the metadata is successfully set, otherwise FALSE.

virtual bool_t immutable() const = 0

Returns whether the object is immutable.

An immmutable object cannot be modified and all modifying methods return FALSE.

Remark

An immutable object can be modified by the AVBlocks library.

Remark

Object immutability spreads to all nested objects. Therefore it is not possible to add/set an immutable object to a mutable object.

Remark

When cloned an immutable object becomes mutable.

Returns:

TRUE if the object is immutable, FALSE otherwise.