mmOpenStream

Opens a stream in a multimedia file for read or write operations.

Prototype

DWORD mmOpenStream ( MMFILE *pMMFile, DWORD streamID, WORD streamType, WORD codec, DATA_FORMAT_DESC *pDataFormatDesc, MMSTREAM *pMMStream, DATA_FORMAT_INFO *pDataFormatInfo)

Argument Description

pMMFile

A pointer to the object that controls the multimedia file.
streamID

The ID of the stream to open. For a:

  • Read operation, a value of 0 (zero) specifies that the first stream found of a given type and codec should be opened.

  • Write operation, this parameter is ignored, and the stream ID is set automatically. NMS Communications recommends setting this value to NULL for a write operation.
streamType The type of stream to open. Valid values for streamType depend on the mode:
Mode Valid values
Read

Valid values are:

  • STREAM_TYPE_UNKNWN - An unsupported or unrecognized stream.

  • STREAM_TYPE_AUDIO - An audio stream.

  • STREAM_TYPE_VIDEO - A video stream.

If you specify STREAM_TYPE_UNKNWN, the codec is ignored and the stream is selected with the stream ID.
Write Valid values for streamType include all of the values listed for Read mode, except for STREAM_TYPE_UNKNWN. You must explicitly specify the stream type, if you invoked the function in write mode.
codec

The codec of the stream to open. Valid values for codec depend on the mode.

Mode

Valid values

Read

Valid values are:

  • S_CODEC_AMR - Audio stream AMR codec.

  • S_CODEC_H263 - Video stream, H.263 codec.

  • S_CODEC_H264 - Video stream, H.264 codec.

  • S_CODEC_MPEG4 - Video stream, MPEG-4 codec.

  • S_CODEC_UNKNWN - An unsupported or unrecognized codec.

If you specify STREAM_TYPE_UNKNWN, the codec is ignored, and the stream is selected by the stream type and ID.

Write

Valid values include all of the values listed for Read mode, except for S_CODEC_UNKNWN. You must explicitly specify the codec for a write operation.
pDataFormatDesc

A pointer to the DATA_FORMAT_DESC structure that determines the format of the data, including whether it is raw or NMS packetized. A NULL value indicates that the default format (NMS_PACKETIZED) is used.

The structure definition is:

typedef struct
{
    WORD    format;
#define FORMAT_NMS_PACKETIZED 0
#define FORMAT_RAW 1 /*
    DWORD   flags; //!< Format flags (bitmap).
#define FORMAT_FLAG_AMR_IF2         0x001
#define FORMAT_FLAG_AMR_DTX         0x002
#define FORMAT_FLAG_H263_2190       0x004
#define FORMAT_FLAG_RTP_HINTS       0x008
#define FORMAT_FLAG_RTP_SETTINGS    0x0010
#define FORMAT_FLAG_HEADER_CHECK    0x0020
#define FORMAT_FLAG_MEM_CHUNKS      0x0080
#define FORMAT_FLAG_DCI_INFO      0x0100
#define FORMAT_WRITE_SYNC_POINTS    0x2000
    WORD      rtpTimestampOffset;
    WORD      rtpSequenceOffset;
    WORD      rtpPayloadType;
#define DEFAULT_PAYLOAD_TYPE 0
    WORD      rtpPayloadSize;
#define DEFAULT_PAYLOAD_SIZE 0
    BYTE      videoProfile;
    BYTE      videoLevel;
    BYTE      *pdciInfo;
    int       dciInfoSize;
WORD       videoAggregationThreshold;
} DATA_FORMAT_DESC;

For information about the fields in this structure, see DATA_FORMAT_DESC.
pMMStream

A pointer to the returned MMSTREAM data structure that is used to access the multimedia stream. The structure definition is:

typedef struct mm_stream
{
    unsigned              state;
    unsigned              streamID;
    void                 *msp;
    struct mm_stream     *pNext;
    struct mm_file       *pMMFile;
} MMSTREAM;
pDataFormatInfo

An optional pointer to the DATA_FORMAT_INFO structure that provides size characteristics for the opened stream. The structure definition is:

typedef struct
{
    DWORD estTotalStreamSize;
    DWORD minReadBufferSize;
} DATA_FORMAT_INFO;

For information about the fields in this structure, see DATA_FORMAT_INFO.

Return values

Return value

Description

SUCCESS

 

MMERR_FILE_FORMAT

(Read mode only) Error in file format.

MMERR_FILE_READ_FAILURE

(Read mode only) File read failure.

MMERR_FILE_WRITE_FAILURE

(Write mode only) File write failure.

MMERR_INTERNAL_RESOURCE

Error on internal resource.

MMERR_INVALID_FILE

pMMFile is invalid.

MMERR_INVALID_FORMAT_DESC

Invalid field in format descriptor.

MMERR_INVALID_POINTER

pMMStream is NULL.

MMERR_INVALID_STREAM

Stream not found. The stream may already be opened, or may be incorrectly specified.

MMERR_MAX_STREAM

Maximum number of opened streams reached.

MMERR_NO_LICENSE_AVAILABLE

No license is available.

Events

None.

Details

The mode that mmOpenStream uses to open a stream depends on how the file containing the stream was opened.

For a read operation, the stream can be selected by any combination of type, codec, or ID. Typically, an application selects a stream with the ID only or with the type and codec.

Example

DWORD ret;
MMSTREAM mmStream;
DATA_FORMAT_INFO dataFormatInfo;
DATA_FORMAT_DESC dataFormatDesc;

streamID = 1;
streamType = STREAM_TYPE_VIDEO;
codec = S_CODEC_MPEG4;
dataFormatDesc. format = FORMAT_NMS_PACKETIZED;
dataFormatDesc. flags   = FORMAT_FLAG_AMR_IF2;
dataFormatDesc. videoLevel = 0;
dataFormatDesc. videoProfile = 0;

ret = mmOpenStream(&mmFile, streamID,  streamType, codec, &dataFormatDesc,
                   &mmStream, &dataFormatInfo);

if( ret != SUCCESS )
{
    printf ("\nERROR in mmOpenStream for stream ID (%lu), ret=(%d)\n",
    streamID, ret );
    return -1;
}