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