docs/user/media/FileInterface.dox

   1 /*
   2  * Copyright 2012 Haiku Inc. All rights reserved.
   3  * Distributed under the terms of the MIT License.
   4  *
   5  * Authors:
   6  *              John Scipione, jscipione@gmail.com
   7  *
   8  * Corresponds to:
   9  *              headers/os/media/FileInterface.h        hrev45081
  10  *              src/kits/media/FileInterface.cpp        hrev45081
  11  */
  12
  13
  14 /*!
  15         \file FileInterface.h
  16         \ingroup media
  17         \ingroup libbe
  18         \brief Provides BFileInterface abstract class.
  19 */
  20
  21
  22 /*!
  23         \class BFileInterface
  24         \ingroup media
  25         \ingroup libbe
  26         \brief A node that can read and write data to a file on disk.
  27
  28         You should derive your subclass from BFileInterface so that your
  29         application may specify the file that the node will reference.
  30         The Media Server will then call upon the node to try to identify
  31         and work with files that are hereunto unknown to it.
  32
  33         Your node must also derive from BBufferConsumer or BBufferProducer,
  34         in addition to BFileInterface.
  35 */
  36
  37
  38 /*!
  39         \fn BFileInterface::BFileInterface()
  40         \brief Constructor.
  41 */
  42
  43
  44 /*!
  45         \fn BFileInterface::~BFileInterface()
  46         \brief Destructor.
  47 */
  48
  49
  50 /*!
  51         \fn status_t BFileInterface::HandleMessage(int32 message,
  52                 const void *data, size_t size)
  53         \brief Dispatches a message to the appropriate BMediaNode hook method
  54                 given a message received on the control port. Implement this method
  55                 to handle messages that arrive on your control port.
  56
  57         \param message The message identifier.
  58         \param data The message data.
  59         \param size The size of the message data in bytes.
  60
  61         \returns A status code.
  62         \retval B_OK Message was dispatched.
  63         \retval B_ERROR There was an error dispatching the message, possibly
  64                         because it doesn't correspond to a hook function.
  65
  66         \see BMediaNode::HandleMessage() for details.
  67 */
  68
  69
  70 /*!
  71         \fn status_t BFileInterface::GetNextFileFormat(int32* cookie,
  72                 media_file_format* _format) = 0;
  73         \brief Implement this method to fill out information about a file format
  74                    indexed by \a cookie.
  75
  76         The first time this method is called \a cookie will be set to 0.
  77         In your implementation you should set information about the first
  78         file format you support in \a _format and set \a cookie to some
  79         meaningful non-zero value to track your positing in the list of
  80         supported formats, then return \c B_OK.
  81
  82         On successive calls return successive file format information and update
  83         \a cookie to track your position in the list. Each time you return new
  84         information about a file format return \c B_OK.
  85
  86         Once you run out of formats return \c B_ERROR.
  87
  88         \param cookie Index of file format to fill out.
  89         \param _format Pointer to a preallocated \c media_file_format object to
  90                    fill out.
  91
  92         \return \c B_OK if a file format was filled out for \a cookie, \c B_ERROR
  93                         or an appropriate error code otherwise.
  94 */
  95
  96
  97 /*!
  98         \fn void BFileInterface::DisposeFileFormatCookie(int32 cookie) = 0;
  99         \brief Implement this method to dispose of a file format supported by your
 100                    node indexed by \a cookie.
 101
 102         You are responsible for freeing any data blocks associated with this
 103         \a cookie before returning.
 104
 105         \param cookie Index of the cookie you wish to dispose of.
 106 */
 107
 108
 109 /*!
 110         \fn status_t BFileInterface::GetDuration(bigtime_t* _time) = 0;
 111         \brief Implement this method to fill out the duration in microseconds of
 112                    the media data contained in the currently referenced file in
 113                    \a _time.
 114
 115         \param _time The duration parameter to fill out.
 116
 117         \return A status code, typically \c B_OK on success and \c B_ERROR
 118                         or another error code on error.
 119 */
 120
 121
 122 /*!
 123         \fn status_t BFileInterface::SniffRef(const entry_ref& file,
 124                 char* _mimeType, float* _quality) = 0;
 125         \brief Implement this method to allow the Media Roster to identify
 126                    a file format associated with this node.
 127
 128         If you can handle the format, set \a _mimeType to the MIME type
 129         of the file format and set \a _quality to indicate how well you
 130         can process the file.
 131
 132         A \a _quality of 0.0 means that you can't handle the file format
 133         at all and an \a _quality of 1.0 means you have total control over
 134         the file format.
 135
 136         \param file The file being sniffed.
 137         \param _mimeType Fill this out with the appropriate MIME type.
 138         \param _quality How well you are able to handle the file format
 139                    from 0.0 to 1.0.
 140
 141         \return \c B_OK if you can identify the file's contents, otherwise return
 142                         an appropriate error code. If you can't handle the file format at
 143                         all, you should return \c B_MEDIA_NO_HANDLER.
 144 */
 145
 146
 147 /*!
 148         \fn status_t BFileInterface::SetRef(const entry_ref& file, bool create,
 149                 bigtime_t* _time) = 0;
 150         \brief Used when an application wants your node to use a specific file.
 151
 152         The file specified by \a file may or may not exist.
 153
 154         If create is \c false you should try to open the existing file, and if
 155         successful you should write the running time of the file into \a _time.
 156         If you the file does not exist you should return \c B_ENTRY_NOT_FOUND.
 157
 158         If \a create is \c true you should create a new file, initialize the file
 159         for writing, and store 0 in \a _time. You should overwrite the file if
 160         it already exists.
 161
 162         \return \c B_OK on success or an appropriate error code such as \c B_ERROR
 163                         or \c B_ENTRY_NOT_FOUND on error.
 164 */
 165
 166
 167 /*!
 168         \fn status_t BFileInterface::GetRef(entry_ref* _ref, char* _mimeType) = 0;
 169         \brief Implement to set the \c entry_ref and the MIME type of the file
 170                    referenced by the current node.
 171
 172         \param _ref Set to the \c entry_ref of the file.
 173         \param _mimeType Set to the MIME type of the current file.
 174
 175         \return \c B_OK on success or an appropriate error code such as \c B_ERROR
 176                         on error.
 177 */