1 /******************************************************************* 2 * 3 * ttfile.h 1.3 4 * 5 * File I/O Component (specification). 6 * 7 * Copyright 1996-1999 by 8 * David Turner, Robert Wilhelm, and Werner Lemberg. 9 * 10 * This file is part of the FreeType project, and may only be used 11 * modified and distributed under the terms of the FreeType project 12 * license, LICENSE.TXT. By continuing to use, modify, or distribute 13 * this file you indicate that you have read the license and 14 * understand and accept it fully. 15 * 16 * Changes between 1.3 and 1.2: 17 * 18 * - all functions report error values now 19 * 20 * - the stream semantics have also changed 21 * 22 * Changes between 1.2 and 1.1: 23 * 24 * - added macros to support re-entrant builds 25 * 26 * - added the TT_Duplicate_File function to duplicate streams 27 * (re-entrant builds only) 28 * 29 ******************************************************************/ 30 31 #ifndef TTFILE_H 32 #define TTFILE_H 33 34 #include "ttconfig.h" 35 #include "freetype.h" 36 #include "ttengine.h" 37 #include "ttdebug.h" 38 39 #ifdef __cplusplus 40 extern "C" { 41 #endif 42 43 /* Initialize file component */ 44 LOCAL_DEF 45 TT_Error TTFile_Init( PEngine_Instance engine ); 46 47 /* Done with file component */ 48 LOCAL_DEF 49 TT_Error TTFile_Done( PEngine_Instance engine ); 50 51 52 /**********************************************************************/ 53 /* */ 54 /* Stream functions. */ 55 /* */ 56 /**********************************************************************/ 57 58 /* Open a file and return a stream handle for it. */ 59 /* Should only be used for a new face object's main stream. */ 60 61 LOCAL_DEF 62 TT_Error TT_Open_Stream( const TT_Text* name, 63 TT_Stream* stream ); 64 65 66 /* Closes, then discards, a stream when it's no longer needed. */ 67 /* Should only be used for a stream opend with TT_Open_Stream(). */ 68 69 LOCAL_DEF 70 TT_Error TT_Close_Stream( TT_Stream* stream ); 71 72 73 /* Informs the component that we're going to use the file */ 74 /* opened in 'org_stream', and report errors to the 'error' */ 75 /* variable. */ 76 77 /* in non re-entrant builds, 'org_stream' is simply copied */ 78 /* to 'stream'. Otherwise, the latter is a duplicate handle */ 79 /* for the file opened with 'org_stream' */ 80 81 EXPORT_DEF 82 TT_Error TT_Use_Stream( TT_Stream org_stream, 83 TT_Stream* stream ); 84 85 /* Informs the component that we don't need to perform file */ 86 /* operations on the stream 'stream' anymore. This must be */ 87 /* used with streams "opened" with TT_Use_Stream() only! */ 88 89 /* in re-entrant builds, this will really discard the stream */ 90 91 EXPORT_DEF 92 TT_Error TT_Done_Stream( TT_Stream* stream ); 93 94 /* Closes the stream's file handle to release system resources */ 95 /* The function TT_Use_Stream automatically re-activates a */ 96 /* flushed stream when it uses one */ 97 98 EXPORT_DEF 99 TT_Error TT_Flush_Stream( TT_Stream* stream ); 100 101 /* The macros STREAM_ARGS and STREAM_ARG let us build a thread-safe */ 102 /* or re-entrant implementation depending on a single configuration */ 103 /*define. */ 104 105 #ifdef TT_CONFIG_OPTION_THREAD_SAFE 106 107 #define STREAM_ARGS TT_Stream stream, 108 #define STREAM_ARG TT_Stream stream 109 110 #else 111 112 #define STREAM_ARGS /* void */ 113 #define STREAM_ARG void 114 115 #endif /* TT_CONFIG_OPTION_THREAD_SAFE */ 116 117 118 /****************************************************************/ 119 /* */ 120 /* File Functions. */ 121 /* */ 122 /* The following functions perform file operations on the */ 123 /* currently 'used' stream. In thread-safe builds, only one */ 124 /* stream can be used at a time. Synchronisation is performed */ 125 /* through the Use_Stream()/Done_Stream() functions. */ 126 /* */ 127 /****************************************************************/ 128 129 /* Read 'count' bytes from file into 'buffer' */ 130 131 EXPORT_DEF 132 TT_Error TT_Read_File( STREAM_ARGS void* buffer, 133 Long count ); 134 135 136 /* Seek file cursor to a given position */ 137 138 EXPORT_DEF 139 TT_Error TT_Seek_File( STREAM_ARGS Long position ); 140 141 142 /* Skip the next 'distance' bytes in file */ 143 144 EXPORT_DEF 145 TT_Error TT_Skip_File( STREAM_ARGS Long distance ); 146 147 148 /* Read the 'count' bytes at 'position' into 'buffer' */ 149 150 EXPORT_DEF 151 TT_Error TT_Read_At_File( STREAM_ARGS Long position, 152 void* buffer, 153 Long count ); 154 155 /* Return current file position */ 156 157 EXPORT_DEF 158 Long TT_File_Pos( STREAM_ARG ); 159 160 /* Return length of a given stream, even if it is flushed */ 161 162 EXPORT_DEF 163 Long TT_Stream_Size( TT_Stream stream ); 164 165 166 /********************************************************************/ 167 /* */ 168 /* Frame operations. */ 169 /* */ 170 /* For a comprehensive explanation of frames, please refer to the */ 171 /* documentation files. */ 172 /* */ 173 /********************************************************************/ 174 175 /* Frame type declaration.*/ 176 177 struct TFileFrame_ 178 { 179 Byte* address; /* frame buffer */ 180 Byte* cursor; /* current cursor position in frame */ 181 Long size; /* frame size */ 182 }; 183 184 typedef struct TFileFrame_ TFileFrame; 185 186 EXPORT_DEF 187 const TFileFrame TT_Null_FileFrame; 188 189 190 /* The macro ZERO_Frame is used to define and init a frame. */ 191 /* It is important to have a default frame of { NULL, NULL, 0 } */ 192 /* before a call to TT_Access_Frame(). Otherwise, the call will */ 193 /* fail with a TT_Err_Nested_Frame_Accesses error. */ 194 195 #define ZERO_Frame( frame ) \ 196 { \ 197 (frame).address = NULL; \ 198 (frame).cursor = NULL; \ 199 (frame).size = 0; \ 200 } 201 202 203 /* The macros FRAME_ARGS and FRAME_ARG let us build a thread-safe */ 204 /* or re-entrant implementation depending on a single configuration */ 205 /* define */ 206 207 #ifdef TT_CONFIG_OPTION_THREAD_SAFE 208 209 #define FRAME_ARGS TFileFrame* frame, 210 #define FRAME_ARG TFileFrame* frame 211 212 #else 213 214 #define FRAME_ARGS /* void */ 215 #define FRAME_ARG void 216 217 #endif /* TT_CONFIG_OPTION_THREAD_SAFE */ 218 219 220 /* Access the next 'size' bytes from current position. */ 221 /* Fails if all bytes cannot be read/accessed. */ 222 223 EXPORT_DEF 224 TT_Error TT_Access_Frame( STREAM_ARGS FRAME_ARGS Long size ); 225 226 227 /* Access the bytes located in the next 'size' bytes of the file. */ 228 /* Doesn't fail if less than 'size' bytes are accessible (like */ 229 /* at the end of the file). */ 230 231 EXPORT_DEF 232 TT_Error TT_Check_And_Access_Frame( STREAM_ARGS FRAME_ARGS Long size ); 233 234 /* Forget frame */ 235 236 EXPORT_DEF 237 TT_Error TT_Forget_Frame( FRAME_ARG ); 238 239 240 /* primitive routines for data accessing */ 241 242 EXPORT_DEF 243 Char TT_Get_Char ( FRAME_ARG ); 244 EXPORT_DEF 245 Short TT_Get_Short( FRAME_ARG ); 246 EXPORT_DEF 247 Long TT_Get_Long ( FRAME_ARG ); 248 249 #ifdef TT_CONFIG_OPTION_THREAD_SAFE 250 251 #define TT_Get_Byte( frame ) ( (Byte )TT_Get_Char ( frame ) ) 252 #define TT_Get_UShort( frame ) ( (UShort)TT_Get_Short( frame ) ) 253 #define TT_Get_ULong( frame ) ( (ULong )TT_Get_Long ( frame ) ) 254 255 #else 256 257 #define TT_Get_Byte() ( (Byte )TT_Get_Char () ) 258 #define TT_Get_UShort() ( (UShort)TT_Get_Short() ) 259 #define TT_Get_ULong() ( (ULong )TT_Get_Long () ) 260 261 #endif /* TT_CONFIG_OPTION_THREAD_SAFE */ 262 263 264 #ifdef __cplusplus 265 } 266 #endif 267 268 #endif /* TTFILE_H */ 269 270 271 /* END */ 272