Fix documentation typo
[projects/chimara/chimara.git] / libchimara / gi_blorb.h
1 #ifndef _GI_BLORB_H
2 #define _GI_BLORB_H
3
4 /* gi_blorb.h: Blorb library layer for Glk API.
5     gi_blorb version 1.4.
6     Designed by Andrew Plotkin <erkyrath@eblong.com>
7     http://www.eblong.com/zarf/glk/index.html
8
9     This file is copyright 1998-2000 by Andrew Plotkin. You may copy,
10     distribute, and incorporate it into your own programs, by any means
11     and under any conditions, as long as you do not modify it. You may
12     also modify this file, incorporate it into your own programs,
13     and distribute the modified version, as long as you retain a notice
14     in your program or documentation which mentions my name and the URL
15     shown above.
16 */
17
18 /* Error type and error codes */
19 typedef glui32 giblorb_err_t;
20 #define giblorb_err_None (0)
21 #define giblorb_err_CompileTime (1)
22 #define giblorb_err_Alloc (2)
23 #define giblorb_err_Read (3)
24 #define giblorb_err_NotAMap (4)
25 #define giblorb_err_Format (5)
26 #define giblorb_err_NotFound (6)
27
28 /* Methods for loading a chunk */
29 #define giblorb_method_DontLoad (0)
30 #define giblorb_method_Memory (1)
31 #define giblorb_method_FilePos (2)
32
33 /* Four-byte constants */
34
35 #define giblorb_make_id(c1, c2, c3, c4)  \
36     (((c1) << 24) | ((c2) << 16) | ((c3) << 8) | (c4))
37
38 #define giblorb_ID_Snd       (giblorb_make_id('S', 'n', 'd', ' '))
39 #define giblorb_ID_Exec      (giblorb_make_id('E', 'x', 'e', 'c'))
40 #define giblorb_ID_Pict      (giblorb_make_id('P', 'i', 'c', 't'))
41 #define giblorb_ID_Copyright (giblorb_make_id('(', 'c', ')', ' '))
42 #define giblorb_ID_AUTH      (giblorb_make_id('A', 'U', 'T', 'H'))
43 #define giblorb_ID_ANNO      (giblorb_make_id('A', 'N', 'N', 'O'))
44
45 /* giblorb_map_t: Holds the complete description of an open Blorb 
46     file. This type is opaque for normal interpreter use. */
47 typedef struct giblorb_map_struct giblorb_map_t;
48
49 /* giblorb_result_t: Result when you try to load a chunk. */
50 typedef struct giblorb_result_struct {
51     glui32 chunknum; /* The chunk number (for use in 
52         giblorb_unload_chunk(), etc.) */
53     union {
54         void *ptr; /* A pointer to the data (if you used 
55             giblorb_method_Memory) */
56         glui32 startpos; /* The position in the file (if you 
57             used giblorb_method_FilePos) */
58     } data;
59     glui32 length; /* The length of the data */
60     glui32 chunktype; /* The type of the chunk. */
61 } giblorb_result_t;
62
63 extern giblorb_err_t giblorb_create_map(strid_t file, 
64     giblorb_map_t **newmap);
65 extern giblorb_err_t giblorb_destroy_map(giblorb_map_t *map);
66
67 extern giblorb_err_t giblorb_load_chunk_by_type(giblorb_map_t *map, 
68     glui32 method, giblorb_result_t *res, glui32 chunktype, 
69     glui32 count);
70 extern giblorb_err_t giblorb_load_chunk_by_number(giblorb_map_t *map, 
71     glui32 method, giblorb_result_t *res, glui32 chunknum);
72 extern giblorb_err_t giblorb_unload_chunk(giblorb_map_t *map, 
73     glui32 chunknum);
74
75 extern giblorb_err_t giblorb_load_resource(giblorb_map_t *map, 
76     glui32 method, giblorb_result_t *res, glui32 usage, 
77     glui32 resnum);
78 extern giblorb_err_t giblorb_count_resources(giblorb_map_t *map, 
79     glui32 usage, glui32 *num, glui32 *min, glui32 *max);
80
81 /* The following functions are part of the Glk library itself, not 
82     the Blorb layer (whose code is in gi_blorb.c). These functions 
83     are necessarily implemented in platform-dependent code. 
84 */
85 extern giblorb_err_t giblorb_set_resource_map(strid_t file);
86 extern giblorb_map_t *giblorb_get_resource_map(void);
87
88 #endif /* _GI_BLORB_H */