diff --git a/docs/user/media/FileInterface.dox b/docs/user/media/FileInterface.dox new file mode 100644 index 00000000000..c91dd3a61e2 --- /dev/null +++ b/docs/user/media/FileInterface.dox @@ -0,0 +1,175 @@ +/* + * Copyright 2012 Haiku, Inc. All Rights Reserved. + * Distributed under the terms of the MIT License. + * + * Authors: + * John Scipione, jscipione@gmail.com + * + * Corresponds to: + * /trunk/headers/os/media/FileInterface.h hrev45081 + * /trunk/src/kits/media/FileInterface.cpp hrev45081 + */ + + +/*! + \file FileInterface.h + \brief Provides BFileInterface abstract class. +*/ + + +/*! + \class BFileInterface + \ingroup media + \ingroup libbe + \brief A node that can read and write data to a file on disk. + + You should derive your subclass from BFileInterface so that your + application may specify the file that the node will reference. + The Media Server will then call upon the node to try to identify + and work with files that are hereunto unknown to it. + + Your node must also derive from BBufferConsumer or BBufferProducer, + in addition to BFileInterface. +*/ + + +/*! + \fn BFileInterface::BFileInterface() + \brief Constructor. +*/ + + +/*! + \fn BFileInterface::~BFileInterface() + \brief Destructor. +*/ + + +/*! + \fn status_t BFileInterface::HandleMessage(int32 message, + const void *data, size_t size) + \brief Dispatches a message to the appropriate BMediaNode hook method + given a message received on the control port. Implement this method + to handle messages that arrive on your control port. + + \param message The message identifier. + \param data The message data. + \param size The size of the message data in bytes. + + \returns A status code. + \retval B_OK Message was dispatched. + \retval B_ERROR There was an error dispatching the message, possibly + because it doesn't correspond to a hook function. + + \see BMediaNode::HandleMessage() for details. +*/ + + +/*! + \fn status_t BFileInterface::GetNextFileFormat(int32* cookie, + media_file_format* _format) = 0; + \brief Implement this method to fill out information about a file format + indexed by \a cookie. + + The first time this method is called \a cookie will be set to 0. + In your implementation you should set information about the first + file format you support in \a _format and set \a cookie to some + meaningful non-zero value to track your positing in the list of + supported formats, then return \c B_OK. + + On successive calls return successive file format information and update + \a cookie to track your position in the list. Each time you return new + information about a file format return \c B_OK. + + Once you run out of formats return \c B_ERROR. + + \param cookie Index of file format to fill out. + \param _format Pointer to a preallocated \c media_file_format object to + fill out. + + \return \c B_OK if a file format was filled out for \a cookie, \c B_ERROR + or an appropriate error code otherwise. +*/ + + +/*! + \fn void BFileInterface::DisposeFileFormatCookie(int32 cookie) = 0; + \brief Implement this method to dispose of a file format supported by your + node indexed by \a cookie. + + You are responsible for freeing any data blocks associated with this + \a cookie before returning. + + \param cookie Index of the cookie you wish to dispose of. +*/ + + +/*! + \fn status_t BFileInterface::GetDuration(bigtime_t* _time) = 0; + \brief Implement this method to fill out the duration in microseconds of + the media data contained in the currently referenced file in + \a _time. + + \param _time The duration parameter to fill out. + + \return A status code, typically \c B_OK on success and \c B_ERROR + or another error code on error. +*/ + + +/*! + \fn status_t BFileInterface::SniffRef(const entry_ref& file, + char* _mimeType, float* _quality) = 0; + \brief Implement this method to allow the Media Roster to identify + a file format associated with this node. + + If you can handle the format, set \a _mimeType to the MIME type + of the file format and set \a _quality to indicate how well you + can process the file. + + A \a _quality of 0.0 means that you can't handle the file format + at all and an \a _quality of 1.0 means you have total control over + the file format. + + \param file The file being sniffed. + \param _mimeType Fill this out with the appropriate MIME type. + \param _quality How well you are able to handle the file format + from 0.0 to 1.0. + + \return \c B_OK if you can identify the file's contents, otherwise return + an appropriate error code. If you can't handle the file format at + all, you should return \c B_MEDIA_NO_HANDLER. +*/ + + +/*! + \fn status_t BFileInterface::SetRef(const entry_ref& file, bool create, + bigtime_t* _time) = 0; + \brief Used when an application wants your node to use a specific file. + + The file specified by \a file may or may not exist. + + If create is \c false you should try to open the existing file, and if + successful you should write the running time of the file into \a _time. + If you the file does not exist you should return \c B_ENTRY_NOT_FOUND. + + If \a create is \c true you should create a new file, initialize the file + for writing, and store 0 in \a _time. You should overwrite the file if + it already exists. + + \return \c B_OK on success or an appropriate error code such as \c B_ERROR + or \c B_ENTRY_NOT_FOUND on error. +*/ + + +/*! + \fn status_t BFileInterface::GetRef(entry_ref* _ref, char* _mimeType) = 0; + \brief Implement to set the \c entry_ref and the MIME type of the file + referenced by the current node. + + \param _ref Set to the \c entry_ref of the file. + \param _mimeType Set to the MIME type of the current file. + + \return \c B_OK on success or an appropriate error code such as \c B_ERROR + on error. +*/