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*/ 178