MISR Toolkit  1.5.1
mfan.h
Go to the documentation of this file.
1 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
2  * Copyright by The HDF Group. *
3  * Copyright by the Board of Trustees of the University of Illinois. *
4  * All rights reserved. *
5  * *
6  * This file is part of HDF. The full HDF copyright notice, including *
7  * terms governing use, modification, and redistribution, is contained in *
8  * the files COPYING and Copyright.html. COPYING can be found at the root *
9  * of the source code distribution tree; Copyright.html can be found at *
10  * http://hdfgroup.org/products/hdf4/doc/Copyright.html. If you do not have *
11  * access to either file, you may request a copy from help@hdfgroup.org. *
12  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
13 
14 /* $Id: mfan.h 5454 2010-08-27 17:24:55Z bmribler $ */
15 
16 /*------------------------------------------------------------------------------
17  * File: mfan.h
18  * Author: GeorgeV
19  * Purpose: header file for the Multi-file Annotation Interface
20  * Invokes:
21  * Contents:
22  * Structure definitions: ANnode, ANentry
23  * Constant definitions: AN_DATA_LABEL, AN_DATA_DESC
24  * (-moved to hdf.h) AN_FILE_LABEL, AN_FILE_DESC
25  *
26  *----------------------------------------------------------------------------*/
27 
28 #ifndef _MFAN_H /* avoid re-inclusion */
29 #define _MFAN_H
30 
31 #include "H4api_adpt.h"
32 
33 #include "hdf.h"
34 
35 #if 0
36 /* enumerated types of the varous annotation types
37  * NOTE: moved to hdf.h since they are used by end users. */
38 typedef enum
39 {
40  AN_DATA_LABEL = 0, /* Data label */
41  AN_DATA_DESC, /* Data description */
42  AN_FILE_LABEL, /* File label */
43  AN_FILE_DESC /* File description */
44 } ann_type;
45 #endif
46 
47 #if defined MFAN_MASTER | defined MFAN_TESTER
48 /* WE ARE IN MAIN ANNOTATION SOURCE FILE "mfan.c" */
49 
50 /* PRIVATE variables and definitions */
51 
52 /* This sturcture is used to find which file the annotation belongs to
53  * and use the subsequent file specific annotation 'key' to find the
54  * annotation. The annotation atom group(ANIDGROUP) keeps track of
55  * all anotations across the file. */
56 typedef struct ANnode
57 {
58  int32 file_id; /* which file this annotation belongs to */
59  int32 ann_key; /* type/ref: used to find annotation in corresponding
60  TBBT in filerec_t->tree[]. */
61  intn new_ann; /* flag */
62 } ANnode;
63 
64 /*
65  * This structure is an entry in the label/desc tree
66  * for a label/desc in the file, it gives the ref of the label/desc,
67  * and the tag/ref of the data item to which the label/desc relates
68  * The filerec_t->an_tree[] TBBT members will contain these entries.
69  **/
70 typedef struct ANentry
71 {
72  int32 ann_id; /* annotation id */
73  uint16 annref; /* ref of annotation */
74  uint16 elmtag; /* tag of data */
75  uint16 elmref; /* ref of data */
76 } ANentry;
77 
78 
79 /* This is the size of the hash tables used for annotation IDs */
80 #define ANATOM_HASH_SIZE 64
81 
82 /* Used to create unique 32bit keys from annotation type and reference number
83  * This key is used to add nodes to a corresponding TBBT in
84  * filrerec_t->an_tree[].
85  * ----------------------------
86  * | type(16bits) | ref(16bits) |
87  * -----------------------------*/
88 #define AN_CREATE_KEY(t,r) ((((int32)t & 0xffff) << 16) | r)
89 
90 /* Obtain Reference number from key */
91 #define AN_KEY2REF(k) ((uint16)((int32)k & 0xffff))
92 
93 /* Obtain Annotation type from key */
94 #define AN_KEY2TYPE(k) ((int32)((int32)k >> 16))
95 
96 #else /* !defined MFAN_MASTER && !defined MFAN_TESTER */
97 /* WE are NOT in main ANNOTATION source file
98  * Nothing EXPORTED except Public fcns */
99 
100 
101 /******************************************************************************
102  NAME
103  ANstart - open file for annotation handling
104 
105  DESCRIPTION
106  Start annotation handling on the file return a annotation ID to the file.
107 
108  RETURNS
109  A file ID or FAIL.
110 *******************************************************************************/
111 HDFLIBAPI int32 ANstart(int32 file_id /* IN: file to start annotation access on */);
112 
113 /******************************************************************************
114  NAME
115  ANfileinfo - Report high-level information about the ANxxx interface for a given file.
116 
117  DESCRIPTION
118  Reports general information about the number of file and object(i.e. data)
119  annotations in the file. This routine is generally used to find
120  the range of acceptable indices for ANselect calls.
121 
122  RETURNS
123  Returns SUCCEED if successful and FAIL othewise
124 
125 *******************************************************************************/
126 HDFLIBAPI intn ANfileinfo(int32 an_id, /* IN: annotation interface id */
127  int32 *n_file_label, /* OUT: the # of file labels */
128  int32 *n_file_desc, /* OUT: the # of file descriptions */
129  int32 *n_obj_label, /* OUT: the # of object labels */
130  int32 *n_obj_desc /* OUT: the # of object descriptions */);
131 
132 /******************************************************************************
133  NAME
134  ANend - End annotation access to file file
135 
136  DESCRIPTION
137  End annotation access to file.
138 
139  RETURNS
140  SUCCEED if successful and FAIL otherwise.
141 *******************************************************************************/
142 HDFLIBAPI int32 ANend(int32 an_id /* IN: Annotation ID of file to close */);
143 
144 /******************************************************************************
145  NAME
146  ANcreate - create a new element annotation and return a handle(id)
147 
148  DESCRIPTION
149  Creates a data annotation, returns an 'an_id' to work with the new
150  annotation which can either be a label or description.
151  Valid annotation types are AN_DATA_LABEL for data labels and
152  AN_DATA_DESC for data descriptions.
153 
154  RETURNS
155  An ID to an annotation which can either be a label or description.
156 *******************************************************************************/
157 HDFLIBAPI int32 ANcreate(int32 an_id, /* IN: annotation interface ID */
158  uint16 elem_tag, /* IN: tag of item to be assigned annotation */
159  uint16 elem_ref, /* IN: reference number of itme to be assigned ann*/
160  ann_type type /* IN: annotation type */);
161 
162 
163 /******************************************************************************
164  NAME
165  ANcreatef - create a new file annotation and return a handle(id)
166 
167  DESCRIPTION
168  Creates a file annotation, returns an 'an_id' to work with the new
169  file annotation which can either be a label or description.
170  Valid annotation types are AN_FILE_LABEL for file labels and
171  AN_FILE_DESC for file descritpions.
172 
173  RETURNS
174  An ID to an annotation which can either be a file label or description
175 *******************************************************************************/
176 HDFLIBAPI int32 ANcreatef(int32 an_id, /* IN: annotation interface ID */
177  ann_type type /* IN: annotation type */);
178 
179 /******************************************************************************
180  NAME
181  ANselect - get an annotation ID from index of 'type'
182 
183  DESCRIPTION
184  Get an annotation Id from index of 'type'.
185  The position index is ZERO based
186 
187  RETURNS
188  An ID to an annotation type which can either be a label or description
189 *******************************************************************************/
190 HDFLIBAPI int32 ANselect(int32 an_id, /* IN: annotation interface ID */
191  int32 index, /* IN: index of annottion to get ID for */
192  ann_type type /* IN: annotation type */);
193 
194 /******************************************************************************
195  NAME
196  ANnumann - find number of annotation of 'type' that match the given element tag/ref
197 
198  DESCRIPTION
199  Find number of annotation of 'type' for the given element
200  tag/ref pair.Should not be used for File labels and
201  descriptions.
202 
203  RETURNS
204  number of annotation found if successful and FAIL (-1) otherwise
205 
206 *******************************************************************************/
207 HDFLIBAPI intn ANnumann(int32 an_id, /* IN: annotation interface id */
208  ann_type type, /* IN: annotation type */
209  uint16 elem_tag, /* IN: tag of item of which this is annotation */
210  uint16 elem_ref /* IN: ref of item of which this is annotation*/);
211 
212 /******************************************************************************
213  NAME
214  ANannlist - generate list of annotation ids of 'type' that match the given element tag/ref
215 
216  DESCRIPTION
217  Find and generate list of annotation ids of 'type' for the given
218  element tag/ref pair.Should not be used for File labels and
219  descriptions.
220 
221  RETURNS
222  number of annotations ids found if successful and FAIL (-1) otherwise
223 
224 *******************************************************************************/
225 HDFLIBAPI intn ANannlist(int32 an_id, /* IN: annotation interface id */
226  ann_type type, /* IN: annotation type */
227  uint16 elem_tag, /* IN: tag of item of which this is annotation */
228  uint16 elem_ref, /* IN: ref of item of which this is annotation*/
229  int32 ann_list[] /* OUT: array of ann_id's that match criteria.*/);
230 
231 /******************************************************************************
232  NAME
233  ANannlen - get length of annotation givne annotation id
234 
235  DESCRIPTION
236  Uses the annotation id to find ann_key & file_id
237 
238  RETURNS
239  length of annotation if successful and FAIL (-1) otherwise
240 
241 *******************************************************************************/
242 HDFLIBAPI int32 ANannlen(int32 ann_id /* IN: annotation id */);
243 
244 /******************************************************************************
245  NAME
246  ANwriteann - write annotation given ann_id
247 
248  DESCRIPTION
249  Checks for pre-existence of given annotation, replacing old one if it
250  exists. Writes out annotation.
251 
252  RETURNS
253  SUCCEED (0) if successful and FAIL (-1) otherwise
254 
255 *******************************************************************************/
256 HDFLIBAPI int32 ANwriteann(int32 ann_id, /* IN: annotation id */
257  const char *ann, /* IN: annotation to write */
258  int32 annlen /* IN: length of annotation*/);
259 
260 /******************************************************************************
261  NAME
262  ANreadann - read annotation given ann_id
263 
264  DESCRIPTION
265  Gets tag and ref of annotation. Finds DD for that annotation.
266  Reads the annotation, taking care of NULL terminator, if necessary.
267 
268  RETURNS
269  SUCCEED (0) if successful and FAIL (-1) otherwise
270 
271 *******************************************************************************/
272 HDFLIBAPI int32 ANreadann(int32 ann_id, /* IN: annotation id (handle) */
273  char *ann, /* OUT: space to return annotation in */
274  int32 maxlen /* IN: size of space to return annotation in */);
275 
276 /******************************************************************************
277  NAME
278  ANendaccess - end access to an annotation given it's id
279 
280  DESCRIPTION
281  Terminates access to an annotation. For now does nothing
282 
283  RETURNS
284  SUCCEED(0) or FAIL(-1)
285 *******************************************************************************/
286 HDFLIBAPI intn ANendaccess(int32 ann_id /* IN: annotation id */);
287 
288 /******************************************************************************
289  NAME
290  ANget_tagref - get tag/ref pair for annotation based on type and index
291 
292  DESCRIPTION
293  Get the tag/ref of the annotation based on the type and index of the
294  annotation. The position index is zero based
295 
296  RETURNS
297  A tag/ref pairt to an annotation type which can either be a
298  label or description.
299 
300 *******************************************************************************/
301 HDFLIBAPI int32 ANget_tagref(int32 an_id, /* IN: annotation interface ID */
302  int32 index, /* IN: index of annotation to get tag/ref for*/
303  ann_type type, /* IN: annotation type */
304  uint16 *ann_tag,/* OUT: Tag for annotation */
305  uint16 *ann_ref /* OUT: ref for annotation */);
306 
307 /******************************************************************************
308  NAME
309  ANid2tagref -- get tag/ref given annotation id
310 
311  DESCRIPTION
312  Uses the annotation id to find ann_node entry which contains ann_ref
313 
314  RETURNS
315  SUCCEED(0) if successful and FAIL (-1) otherwise.
316 *******************************************************************************/
317 HDFLIBAPI int32 ANid2tagref(int32 ann_id, /* IN: annotation id */
318  uint16 *ann_tag, /* OUT: Tag for annotation */
319  uint16 *ann_ref /* OUT: ref for annotation */);
320 
321 /******************************************************************************
322  NAME
323  ANtagref2id -- get annotation id given tag/ref
324 
325  DESCRIPTION
326  Gets the annotation id of the annotation given the tag/ref of
327  the annotation itself and the annotation interface id.
328 
329  RETURNS
330  Annotation id of annotation if successful and FAIL(-1) otherwise.
331 *******************************************************************************/
332 HDFLIBAPI int32 ANtagref2id(int32 an_id, /* IN Annotation interface id */
333  uint16 ann_tag, /* IN: Tag for annotation */
334  uint16 ann_ref /* IN: ref for annotation */);
335 
336 /******************************************************************************
337  NAME
338  ANatype2tag - annotation type to corresponding annotation TAG
339 
340  DESCRIPTION
341  Translate annotation type to corresponding TAG.
342 
343  RETURNS
344  Returns TAG corresponding to annotatin type.
345 *******************************************************************************/
346 HDFLIBAPI uint16 ANatype2tag(ann_type atype /* IN: Annotation type */);
347 
348 /******************************************************************************
349  NAME
350  ANtag2atype - annotation TAG to corresponding annotation type
351 
352  DESCRIPTION
353  Translate annotation TAG to corresponding atype
354 
355  RETURNS
356  Returns type corresponding to annotatin TAG.
357 *******************************************************************************/
358 HDFLIBAPI ann_type ANtag2atype(uint16 atag /* IN: annotation tag */);
359 
360 
361 #endif /* !defined MFAN_MASTER && !MFAN_TESTER */
362 
363 #endif /* _MFAN_H */
HDFLIBAPI int32 ANstart(int32 file_id)
HDFLIBAPI uint16 ANatype2tag(ann_type atype)
HDFLIBAPI int32 ANcreatef(int32 an_id, ann_type type)
HDFLIBAPI int32 ANcreate(int32 an_id, uint16 elem_tag, uint16 elem_ref, ann_type type)
HDFLIBAPI int32 ANid2tagref(int32 ann_id, uint16 *ann_tag, uint16 *ann_ref)
HDFFCLIBAPI intf intf intf * atype
HDFLIBAPI int32 ANselect(int32 an_id, int32 index, ann_type type)
HDFLIBAPI int32 ANreadann(int32 ann_id, char *ann, int32 maxlen)
HDFLIBAPI int32 ANannlen(int32 ann_id)
HDFLIBAPI int32 ANget_tagref(int32 an_id, int32 index, ann_type type, uint16 *ann_tag, uint16 *ann_ref)
HDFFCLIBAPI intf intf _fcd intf * annlen
HDFLIBAPI intn ANnumann(int32 an_id, ann_type type, uint16 elem_tag, uint16 elem_ref)
HDFFCLIBAPI _fcd ann
HDFLIBAPI intn ANfileinfo(int32 an_id, int32 *n_file_label, int32 *n_file_desc, int32 *n_obj_label, int32 *n_obj_desc)
HDFLIBAPI ann_type ANtag2atype(uint16 atag)
HDFLIBAPI intn ANendaccess(int32 ann_id)
HDFLIBAPI int32 ANend(int32 an_id)
HDFLIBAPI int32 ANtagref2id(int32 an_id, uint16 ann_tag, uint16 ann_ref)
HDFFCLIBAPI intf intf intf * type
ann_type
Definition: hdf.h:33
HDFFCLIBAPI intf intf _fcd intf * maxlen
HDFLIBAPI int32 ANwriteann(int32 ann_id, const char *ann, int32 annlen)
#define HDFLIBAPI
Definition: H4api_adpt.h:195
HDFFCLIBAPI intf * index
HDFLIBAPI intn ANannlist(int32 an_id, ann_type type, uint16 elem_tag, uint16 elem_ref, int32 ann_list[])

MISR Toolkit - Copyright © 2005 - 2020 Jet Propulsion Laboratory
Generated on Fri Jun 19 2020 22:49:52