92543558a19e559672412775af0f228516a3c853
[blender-staging.git] / source / blender / blenlib / BLI_bfile.h
1 /*
2  * $Id$
3  *
4  * ***** BEGIN GPL LICENSE BLOCK *****
5  *
6  * This program is free software; you can redistribute it and/or
7  * modify it under the terms of the GNU General Public License
8  * as published by the Free Software Foundation; either version 2
9  * of the License, or (at your option) any later version.
10  *
11  * This program is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14  * GNU General Public License for more details.
15  *
16  * You should have received a copy of the GNU General Public License
17  * along with this program; if not, write to the Free Software Foundation,
18  * Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
19  *
20  * The Original Code is Copyright (C) 2009 by Stichting Blender Foundation.
21  * All rights reserved.
22  *
23  * ***** END GPL LICENSE BLOCK *****
24  * BFILE* based abstraction of file access.
25  */
26
27 #ifndef BLI_BFILE_H
28 #define BLI_BFILE_H
29
30 /* For fopen's FILE */
31 #include <stdio.h>
32
33 /**
34  Defines for the bflags param.
35  */
36 /* Special handling: */
37 /* For "symmetry" of flags */
38 #define BFILE_NORMAL (0)
39 /* No supervision, just translate // if needed, RISKY */
40 #define BFILE_RAW    (1<<0)
41 /* Path is relative to config dirs */
42 #define BFILE_CONFIG (1<<1)
43 /* Path is for current session temp file */
44 #define BFILE_TEMP   (1<<2)
45
46 /* Config handling, special cases: */
47 #define BFILE_USERONLY (1<<3)
48 #define BFILE_SYSONLY  (1<<4)
49
50 /* Compression to apply on close: */
51 #define BFILE_GZIP (1<<5)
52
53 /**
54  File descriptor for Blender abstracted file access.
55  */
56 typedef struct {
57         FILE *stream;
58         int fd;
59
60         /* Anything below should not be touched directly */
61         int uflags;  /* Special options requested by upper level, copy of bflags */
62         char *fpath; /* Final/requested path name */
63         char *tpath; /* Temp path name if applicable */
64         int type;    /* Own flags, common classification of open and fopen */
65         int error;   /* An op caused an error, unsafe to replace older files */
66 } BFILE;
67
68 /**
69  Open a BFILE* with fopen()-like syntax.
70  */
71 BFILE *BLI_bfile_fopen(const char *path, const char *mode, int bflags);
72
73 /**
74  Open a BFILE* with open()-like syntax.
75  */
76 BFILE *BLI_bfile_open(const char *pathname, int flags, int bflags);
77
78 /**
79  Get the FILE* associated with the BFILE*.
80  */
81 FILE *BLI_bfile_file_from_bfile(BFILE *bfile);
82
83 /**
84  Get the fd associated with the BFILE*.
85  */
86 int BLI_bfile_fd_from_bfile(BFILE *bfile);
87
88 /**
89  write()-like using BFILE*.
90  */
91 ssize_t BLI_bfile_write(BFILE *f, const void *buf, size_t count);
92
93 /**
94  read()-like using BFILE*.
95  */
96 ssize_t BLI_bfile_read(BFILE *f, void *buf, size_t count);
97
98 /**
99  fwrite()-like using BFILE*.
100  */
101 size_t BLI_bfile_fwrite(const void *ptr, size_t size, size_t nmemb, BFILE *f);
102
103 /**
104  fread()-like using BFILE*.
105  */
106 size_t BLI_bfile_fread(void *ptr, size_t size, size_t nmemb, BFILE *f);
107
108 /**
109  Close a BFILE, to match close() and fclose().
110  */
111 void BLI_bfile_close(BFILE *bfile);
112
113 /**
114  Clear error status.
115  Call it only if the error has been really handled.
116  */
117 void BLI_bfile_clear_error(BFILE *bfile);
118
119 /**
120  Set the error status.
121  Call it to mark writing by a 3rd party failed (libjpeg reported error, ie).
122  */
123 void BLI_bfile_set_error(BFILE *bfile, int error);
124
125 /*
126 TODO
127 Maybe also provide more OS/libc things like:
128 fflush
129 fprintf and related
130 fscanf
131 fgetc/fputc and related
132 fseek and related
133
134 Probably good to do:
135 readdir (compacted list showing all files for a "directory" (user versions on top of system's))
136 */
137
138 #endif /* ifndef BLI_BFILE_H */