This version of this document is no longer maintained. For the latest documentation, see http://www.qnx.com/developers/docs.

`MediaInput`

Functions for a filter with an input channel

Synopsis:

static MediaInput media_input =
{
  IterateChannels,
  AcquireChannel,
  ReleaseChannel,
  RateFormat,
  SetFormat,
  SetMediaOutput,
  SetInputStream
};

Description:

This interface defines the functionality required by any filter that gets its input data from another filter, either streaming or buffered.

IterateChannels()

MmChannel_t *(*IterateChannels)(const MmFilter_t *filter,
                                int32_t * const cookie);

This function should iterate through all the input channels in the filter. Set the value of cookie to 0 for the first call. IterateChannels() returns NULL to indicate that there are no more channels. This function doesn't discriminate between acquired and nonacquired channels. To determine whether a channel is acquired, check its flags member. See MmChannel_t in the Structure Reference chapter for more information.

If your filter has only one channel, you can use singleIterateInputChannels() from the convenience library, which returns the input channel the first time it's called, and NULL thereafter.

MmChannel_t *singleIterateInputChannels(const MmFilter_t *f,
                                        int32_t * const cookie);

AcquireChannel()

int32_t (*AcquireChannel)(MmChannel_t *channel);

This function should acquire the channel, and set its flags member to MM_CHANNEL_ACQUIRED. This locks the channel for exclusive use. You can release it with ReleaseChannel().

This function should return 0 if successful, and nonzero if it can't acquire the channel.

If your filter has only one input channel, you can use singleAcquireInputChannel() from the convenience library. This function acquires the channel c by setting its flags member to MM_CHANNEL_ACQUIRED. This locks the channel for exclusive use.

int32_t singleAcquireInputChannel(MmChannel_t *c);

ReleaseChannel()

int32_t (*ReleaseChannel)(MmChannel_t *channel);

This function should release the channel. It is then available to be acquired later.

This function should return 0 if successful, and nonzero if it can't release the channel.

If your filter has only one input channel, you can use ReleaseChannel() from the convenience library. This function releases the channel c, which makes it available for use by another filter.

singleReleaseInputChannel()

int32_t singleReleaseInputChannel(MmChannel_t *c);

RateFormat()

int32_t (*RateFormat)(MmChannel_t *channel,
                      MmFormat_t *format,
                      int32_t *const cookie);

This function should rate the multimedia format, depending on how well the filter is able to process data in that format. If the format isn't specific enough (some members may be 0 to indicate it can take any value), the function can use the cookie to go through the permutations of the formats the filter can process. When there are no more permutations, or if the filter can't process the given format at all, the function should return a rating of 0.

The parameter cookie must be initialized to 0 for the first call to the function.

Use RateFormat() only for buffered channels, not streamed channels.

If your filter doesn't connect to the buffered output of another filter (for example, if it connects to streaming or unparsed data), you can use the placeholder noRateInputFormat() from the convenience library. It simply returns 0.

int32_t noRateInputFormat(MmChannel_t *c,
                          MmFormat_t *f,
                          int32_t * const cookie);

SetFormat()

int32_t (*SetFormat)(MmChannel_t *channel,
                     const MmFormat_t *format);

This function should set the channel's format to format. When negotiation is performed, the format in the two channels that you want to connect should both be set to the same format, so that they can share buffers.

Use SetFormat() only for buffered channels, not streamed channels.

If successful, this function should return 0.

If your filter doesn't need to connect an input channel to the buffered output channel of another filter (for example, if it connects to streaming or unparsed data), it can use the placeholder noSetInputFormat() from the convenience library. It simply returns -1.

int32_t noSetInputFormat(MmChannel_t *c,
                         const MmFormat_t *f);

SetMediaOutput()

int32_t (*SetMediaOutput)(MmChannel_t *channel,
                          const MediaOutput *mo);

This function should give the channel the MediaOutput interface, mo, that it can use to retrieve buffer data from its connected output channel. It should also set the channel's flags member to MM_CHANNEL_OUTPUTSET.

Use SetMediaOutput() only for buffered channels, not streamed channels.

If successful, this function should return 0.

If your filter doesn't need to connect an input channel to the buffered output channel of another filter (for example, if it connects to streaming or unparsed data), you can use the placeholder noSetMediaOutput() method in the convenience library. It simply returns -1.

int32_t noSetMediaOutput(MmChannel_t *c,
                         const MediaOutput *m);

SetInputStream()

int32_t (*SetInputStream)(MmChannel_t *channel,
                          const AOStream_t *stream);

This function should set the channel's input to stream. It should also set the channel's flags member to MM_CHANNEL_INPUTSET.

Use SetInputStream() only for buffered channels, not streamed channels.

A filter that doesn't connect its input channel(s) to streamed data (for example, if it connects to a buffered channel) can use the placeholder noSetInputStream() method from the convenience library. It simply returns -1.

int32_t noSetInputStream(MmChannel_t *c,
                         AOIStream_t *sobj);

Classification:

Neutrino