source: trunk/include/napi.h @ 1822

Revision 1797, 40.7 KB checked in by Freddie Akeroyd, 4 months ago (diff)
  • Fix issue of only writing links to output HDF5 files
  • Also speed up conversion to definition by using NXgetslab/NXputslab

Refs #320,#321
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
Line 
1/*---------------------------------------------------------------------------
2  NeXus - Neutron & X-ray Common Data Format
3 
4  Application Program Interface Header File
5 
6  Copyright (C) 2000-2011 Mark Koennecke, Uwe Filges
7 
8  This library is free software; you can redistribute it and/or
9  modify it under the terms of the GNU Lesser General Public
10  License as published by the Free Software Foundation; either
11  version 2 of the License, or (at your option) any later version.
12 
13  This library is distributed in the hope that it will be useful,
14  but WITHOUT ANY WARRANTY; without even the implied warranty of
15  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
16  Lesser General Public License for more details.
17 
18  You should have received a copy of the GNU Lesser General Public
19  License along with this library; if not, write to the Free Software
20  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
21 
22  For further information, see <http://www.nexusformat.org>
23 
24  $Id$
25
26 ----------------------------------------------------------------------------*/
27/** \file
28 * Documentation for the NeXus-API version 4.3
29 * 2000-2011, the NeXus International Advisory Commitee
30 * \defgroup c_main C API
31 * \defgroup c_types Data Types
32 * \ingroup c_main
33 * \defgroup c_init General Initialisation and shutdown
34 * \ingroup c_main
35 * \defgroup c_group Reading and Writing Groups
36 * \ingroup c_main
37 * \defgroup c_readwrite Reading and Writing Data
38 * \ingroup c_main
39 * \defgroup c_navigation General File navigation
40 * \ingroup c_main
41 * \defgroup c_metadata Meta data routines
42 * \ingroup c_main
43 * \defgroup c_linking Linking
44 * \ingroup c_main
45 * \defgroup c_memory Memory allocation
46 * \ingroup c_main
47 * \defgroup c_external External linking
48 * \ingroup c_main
49 */
50 
51#ifndef NEXUSAPI
52#define NEXUSAPI
53
54#include <stdint.h>
55
56/* NeXus HDF45 */
57#define NEXUS_VERSION   "4.3.0"                /* major.minor.patch */
58
59#define CONSTCHAR       const char
60
61typedef void* NXhandle;         /* really a pointer to a NexusFile structure */
62typedef int NXstatus;
63typedef char NXname[128];
64
65/*
66 * Any new NXaccess_mode options should be numbered in 2^n format
67 * (8, 16, 32, etc) so that they can be bit masked and tested easily.
68 *
69 * To test older non bit masked options (values below 8) use e.g.
70 *
71 *       if ( (mode & NXACCMASK_REMOVEFLAGS) == NXACC_CREATE )
72 *
73 * To test new (>=8) options just use normal bit masking e.g.
74 *
75 *       if ( mode & NXACC_NOSTRIP )
76 *
77 */
78#define NXACCMASK_REMOVEFLAGS (0x7) /* bit mask to remove higher flag options */
79
80/** \enum NXaccess_mode
81 * NeXus file access codes.
82 * \li NXACC_READ read-only
83 * \li NXACC_RDWR open an existing file for reading and writing.
84 * \li NXACC_CREATE create a NeXus HDF-4 file
85 * \li NXACC_CREATE4 create a NeXus HDF-4 file
86 * \li NXACC_CREATE5 create a NeXus HDF-5 file.
87 * \li NXACC_CREATEXML create a NeXus XML file.
88 * \li NXACC_CHECKNAMESYNTAX Check names conform to NeXus allowed characters.
89 */
90typedef enum {NXACC_READ=1, NXACC_RDWR=2, NXACC_CREATE=3, NXACC_CREATE4=4, 
91              NXACC_CREATE5=5, NXACC_CREATEXML=6, NXACC_TABLE=8, NXACC_NOSTRIP=128, NXACC_CHECKNAMESYNTAX=256 } NXaccess_mode;
92
93/**
94 * A combination of options from #NXaccess_mode
95 */
96typedef int NXaccess;
97
98typedef struct {
99                char *iname;
100                int   type;
101               }info_type, *pinfo; 
102 
103#define NX_OK 1
104#define NX_ERROR 0
105#define NX_EOD -1
106
107#define NX_UNLIMITED -1
108
109#define NX_MAXRANK 32
110#define NX_MAXNAMELEN 64
111#define NX_MAXPATHLEN 1024
112
113
114/**
115 * \ingroup c_types
116 * \def NX_FLOAT32     
117 * 32 bit float
118 * \def NX_FLOAT64     
119 * 64 bit float == double
120 * \def NX_INT8       
121 * 8 bit integer == byte
122 * \def NX_UINT8       
123 * 8 bit unsigned integer
124 * \def NX_INT16       
125 * 16 bit integer
126 * \def NX_UINT16     
127 * 16 bit unsigned integer
128 * \def NX_INT32       
129 * 32 bit integer
130 * \def NX_UINT32     
131 * 32 bit unsigned integer
132 * \def NX_CHAR       
133 * 8 bit character
134 * \def NX_BINARY     
135 * lump of binary data == NX_UINT8
136*/
137/*--------------------------------------------------------------------------*/
138
139/* Map NeXus to HDF types */
140#define NX_FLOAT32   5
141#define NX_FLOAT64   6
142#define NX_INT8     20 
143#define NX_UINT8    21
144#define NX_BOOLEAN NX_UINT
145#define NX_INT16    22 
146#define NX_UINT16   23
147#define NX_INT32    24
148#define NX_UINT32   25
149#define NX_INT64    26
150#define NX_UINT64   27
151#define NX_CHAR      4
152#define NX_BINARY   21
153
154/* Map NeXus compression methods to HDF compression methods */
155#define NX_CHUNK     0
156#define NX_COMP_NONE 100
157#define NX_COMP_LZW 200
158#define NX_COMP_RLE 300
159#define NX_COMP_HUF 400 
160
161/* to test for these we use ((value / 100) == NX_COMP_LZW) */
162#define NX_COMP_LZW_LVL0 (100*NX_COMP_LZW + 0)
163#define NX_COMP_LZW_LVL1 (100*NX_COMP_LZW + 1)
164#define NX_COMP_LZW_LVL2 (100*NX_COMP_LZW + 2)
165#define NX_COMP_LZW_LVL3 (100*NX_COMP_LZW + 3)
166#define NX_COMP_LZW_LVL4 (100*NX_COMP_LZW + 4)
167#define NX_COMP_LZW_LVL5 (100*NX_COMP_LZW + 5)
168#define NX_COMP_LZW_LVL6 (100*NX_COMP_LZW + 6)
169#define NX_COMP_LZW_LVL7 (100*NX_COMP_LZW + 7)
170#define NX_COMP_LZW_LVL8 (100*NX_COMP_LZW + 8)
171#define NX_COMP_LZW_LVL9 (100*NX_COMP_LZW + 9)
172
173typedef struct {
174                long iTag;          /* HDF4 variable */
175                long iRef;          /* HDF4 variable */
176                char targetPath[1024]; /* path to item to link */
177                int linkType;          /* HDF5: 0 for group link, 1 for SDS link */
178               } NXlink;
179
180#define NXMAXSTACK 50
181
182#define CONCAT(__a,__b) __a##__b        /* token concatenation */
183
184#    ifdef __VMS
185#        define MANGLE(__arg)   __arg
186#    else
187#        define MANGLE(__arg)   CONCAT(__arg,_)
188#    endif
189
190#    define NXopen              MANGLE(nxiopen)
191#    define NXreopen            MANGLE(nxireopen)
192#    define NXclose             MANGLE(nxiclose)
193#    define NXmakegroup         MANGLE(nximakegroup)
194#    define NXopengroup         MANGLE(nxiopengroup)
195#    define NXopenpath          MANGLE(nxiopenpath)
196#    define NXgetpath           MANGLE(nxigetpath)
197#    define NXopengrouppath     MANGLE(nxiopengrouppath)
198#    define NXclosegroup        MANGLE(nxiclosegroup)
199#    define NXmakedata          MANGLE(nximakedata)
200#    define NXmakedata64        MANGLE(nximakedata64)
201#    define NXcompmakedata      MANGLE(nxicompmakedata)
202#    define NXcompmakedata64    MANGLE(nxicompmakedata64)
203#    define NXcompress          MANGLE(nxicompress)
204#    define NXopendata          MANGLE(nxiopendata)
205#    define NXclosedata         MANGLE(nxiclosedata)
206#    define NXputdata           MANGLE(nxiputdata)
207#    define NXputslab           MANGLE(nxiputslab)
208#    define NXputslab64         MANGLE(nxiputslab64)
209#    define NXputattr           MANGLE(nxiputattr)
210#    define NXgetdataID         MANGLE(nxigetdataid)
211#    define NXmakelink          MANGLE(nximakelink)
212#    define NXmakenamedlink     MANGLE(nximakenamedlink)
213#    define NXopensourcegroup   MANGLE(nxiopensourcegroup)
214#    define NXmalloc            MANGLE(nximalloc)
215#    define NXmalloc64          MANGLE(nximalloc64)
216#    define NXfree              MANGLE(nxifree)
217#    define NXflush             MANGLE(nxiflush)
218
219#    define NXgetinfo           MANGLE(nxigetinfo)
220#    define NXgetinfo64         MANGLE(nxigetinfo64)
221#    define NXgetrawinfo        MANGLE(nxigetrawinfo)
222#    define NXgetrawinfo64      MANGLE(nxigetrawinfo64)
223#    define NXgetnextentry      MANGLE(nxigetnextentry)
224#    define NXgetdata           MANGLE(nxigetdata)
225
226#    define NXgetslab           MANGLE(nxigetslab)
227#    define NXgetslab64         MANGLE(nxigetslab64)
228#    define NXgetnextattr       MANGLE(nxigetnextattr)
229#    define NXgetattr           MANGLE(nxigetattr)
230#    define NXgetattrinfo       MANGLE(nxigetattrinfo)
231#    define NXgetgroupID        MANGLE(nxigetgroupid)
232#    define NXgetgroupinfo      MANGLE(nxigetgroupinfo)
233#    define NXsameID            MANGLE(nxisameid)
234#    define NXinitgroupdir      MANGLE(nxiinitgroupdir)
235#    define NXinitattrdir       MANGLE(nxiinitattrdir)
236#    define NXsetnumberformat   MANGLE(nxisetnumberformat)
237#    define NXsetcache          MANGLE(nxisetcache)
238#    define NXinquirefile       MANGLE(nxiinquirefile)
239#    define NXisexternalgroup   MANGLE(nxiisexternalgroup)
240#    define NXisexternaldataset   MANGLE(nxiisexternaldataset)
241#    define NXlinkexternal      MANGLE(nxilinkexternal)
242#    define NXlinkexternaldataset      MANGLE(nxilinkexternaldataset)
243#    define NXgetversion        MANGLE(nxigetversion)
244
245/*
246 * FORTRAN helpers - for NeXus internal use only
247 */
248#    define NXfopen             MANGLE(nxifopen)
249#    define NXfclose            MANGLE(nxifclose)
250#    define NXfflush            MANGLE(nxifflush)
251#    define NXfmakedata         MANGLE(nxifmakedata)
252#    define NXfcompmakedata     MANGLE(nxifcompmakedata)
253#    define NXfcompress         MANGLE(nxifcompress)
254#    define NXfputattr          MANGLE(nxifputattr)
255#    define NXfgetpath          MANGLE(nxifgetpath)
256
257/*
258 * Standard interface
259 *
260 * Functions added here are not automatically exported from
261 * a shared library/dll - the symbol name must also be added
262 * to the file   src/nexus_symbols.txt
263 *
264 */
265
266#ifdef __cplusplus
267extern "C" {
268#endif /* __cplusplus */
269  /**
270   * Open a NeXus file.
271   * NXopen honours full path file names. But it also searches
272   * for files in all the paths given in the NX_LOAD_PATH environment variable.
273   * NX_LOAD_PATH is supposed to hold a list of path string separated by the platform
274   * specific path separator. For unix this is the : , for DOS the ; . Please note
275   * that crashing on an open NeXus file will result in corrupted data. Only after a NXclose
276   * or a NXflush will the data file be valid.
277   * \param filename The name of the file to open
278   * \param access_method The file access method. This can be:
279   * \li NXACC__READ read access
280   * \li NXACC_RDWR read write access
281   * \li NXACC_CREATE, NXACC_CREATE4 create a new HDF-4 NeXus file
282   * \li NXACC_CREATE5 create a new HDF-5 NeXus file
283   * \li NXACC_CREATEXML create an XML NeXus file.
284   * see #NXaccess_mode
285   * Support for HDF-4 is deprecated.
286   * \param pHandle A file handle which will be initialized upon successfull completeion of NXopen.
287   * \return NX_OK on success, NX_ERROR in the case of an error.   
288   * \ingroup c_init
289   */
290extern  NXstatus  NXopen(CONSTCHAR * filename, NXaccess access_method, NXhandle* pHandle);
291
292  /**
293   * Opens an existing NeXus file a second time for e.g. access from another thread.
294   * \return NX_OK on success, NX_ERROR in the case of an error.   
295   * \ingroup c_init
296   */
297extern  NXstatus  NXreopen(NXhandle pOrigHandle, NXhandle* pNewHandle);
298
299  /**
300   * close a NeXus file
301   * \param pHandle A NeXus file handle as returned from NXopen. pHandle is invalid after this
302   * call.
303   * \return NX_OK on success, NX_ERROR in the case of an error.   
304   * \ingroup c_init
305   */
306extern  NXstatus  NXclose(NXhandle* pHandle);
307
308  /**
309   * flush data to disk
310   * \param pHandle A NeXus file handle as initialized by NXopen.
311   * \return NX_OK on success, NX_ERROR in the case of an error.   
312   * \ingroup c_readwrite
313   */
314extern  NXstatus  NXflush(NXhandle* pHandle);
315
316  /**
317   * NeXus groups are NeXus way of structuring information into a hierarchy.
318   * This function creates a group but does not open it.
319   * \param handle A NeXus file handle as initialized NXopen.
320   * \param name The name of the group
321   * \param NXclass the class name of the group. Should start with the prefix NX
322   * \return NX_OK on success, NX_ERROR in the case of an error.   
323   * \ingroup c_group
324   */
325extern  NXstatus  NXmakegroup (NXhandle handle, CONSTCHAR *name, CONSTCHAR* NXclass);
326
327  /**
328   * Step into a group. All further access will be within the opened group.
329   * \param handle A NeXus file handle as initialized by NXopen.
330   * \param name The name of the group
331   * \param NXclass the class name of the group. Should start with the prefix NX
332   * \return NX_OK on success, NX_ERROR in the case of an error.   
333   * \ingroup c_group
334   */
335extern  NXstatus  NXopengroup (NXhandle handle, CONSTCHAR *name, CONSTCHAR* NXclass);
336
337  /**
338   * Open the NeXus object with the path specified
339   * \param handle A NeXus file handle as returned from NXopen.
340   * \param path A unix like path string to a NeXus group or dataset. The path string
341   * is a list of group names and SDS names separated with / (slash).
342   * Example: /entry1/sample/name
343   * \return NX_OK on success, NX_ERROR in the case of an error.   
344   * \ingroup c_navigation
345   */
346extern  NXstatus  NXopenpath (NXhandle handle, CONSTCHAR *path);
347
348  /**
349   * Opens the group in which the NeXus object with the specified path exists
350   * \param handle A NeXus file handle as initialized by NXopen.
351   * \param path A unix like path string to a NeXus group or dataset. The path string
352   * is a list of group names and SDS names separated with / (slash).
353   * Example: /entry1/sample/name
354   * \return NX_OK on success, NX_ERROR in the case of an error.   
355   * \ingroup c_navigation
356   */
357extern  NXstatus  NXopengrouppath (NXhandle handle, CONSTCHAR *path);
358
359  /**
360   * Retrieve the current path in the NeXus file
361   * \param handle a NeXus file handle
362   * \param path A buffer to copy the path too
363   * \param  pathlen The maximum number of characters to copy into path
364   * \return NX_OK or NX_ERROR
365   * \ingroup c_navigation
366   */
367extern NXstatus NXgetpath(NXhandle handle, char *path, int pathlen);
368
369  /**
370   * Closes the currently open group and steps one step down in the NeXus file
371   * hierarchy.
372   * \return NX_OK on success, NX_ERROR in the case of an error.   
373   * \ingroup c_group
374   */
375extern  NXstatus  NXclosegroup(NXhandle handle);
376
377  /**
378   * Create a multi dimensional data array or dataset. The dataset is NOT opened.
379   * \param handle A NeXus file handle as initialized by NXopen.
380   * \param label The name of the dataset
381   * \param datatype The data type of this data set.
382   * \param rank The number of dimensions this dataset is going to have
383   * \param dim An array of size rank holding the size of the dataset in each dimension. The first dimension
384   * can be NX_UNLIMITED. Data can be appended to such a dimension using NXputslab.
385   * \return NX_OK on success, NX_ERROR in the case of an error.   
386   * \ingroup c_readwrite
387   */
388extern  NXstatus  NXmakedata (NXhandle handle, CONSTCHAR* label, int datatype, int rank, int dim[]);
389
390
391  /**
392   * @copydoc NXmakedata()
393   */
394extern  NXstatus  NXmakedata64 (NXhandle handle, CONSTCHAR* label, int datatype, int rank, int64_t dim[]);
395
396
397/**
398   * Create a compressed dataset. The dataset is NOT opened. Data from this set will automatically be compressed when
399   * writing and decompressed on reading.
400   * \param handle A NeXus file handle as initialized by NXopen.
401   * \param label The name of the dataset
402   * \param datatype The data type of this data set.
403   * \param rank The number of dimensions this dataset is going to have
404   * \param comp_typ The compression scheme to use. Possible values:
405   * \li NX_COMP_NONE no compression
406   * \li NX_COMP_LZW lossless Lempel Ziv Welch compression (recommended)
407   * \li NX_COMP_RLE run length encoding (only HDF-4)
408   * \li NX_COMP_HUF Huffmann encoding (only HDF-4)
409   * \param dim An array of size rank holding the size of the dataset in each dimension. The first dimension
410   * can be NX_UNLIMITED. Data can be appended to such a dimension using NXputslab.
411   * \param bufsize The dimensions of the subset of the data which usually be writen in one go.
412   * This is a parameter used by HDF for performance optimisations. If you write your data in one go, this
413   * should be the same as the data dimension. If you write it in slabs, this is your preferred slab size.
414   * \return NX_OK on success, NX_ERROR in the case of an error.   
415   * \ingroup c_readwrite
416   */
417extern  NXstatus  NXcompmakedata (NXhandle handle, CONSTCHAR* label, int datatype, int rank, int dim[], int comp_typ, int bufsize[]);
418
419
420/**
421  * @copydoc NXcompmakedata()
422  */
423extern  NXstatus NXcompmakedata64 (NXhandle handle, CONSTCHAR* label, int datatype, int rank, int64_t dim[], int comp_typ, int64_t chunk_size[]);
424
425
426  /**
427   * Switch compression on. This routine is superseeded by NXcompmakedata and thus
428   * is deprecated.
429   * \param handle A NeXus file handle as initialized by NXopen.
430   * \param compr_type The compression scheme to use. Possible values:
431   * \li NX_COMP_NONE no compression
432   * \li NX_COMP_LZW lossless Lempel Ziv Welch compression (recommended)
433   * \li NX_COMP_RLE run length encoding (only HDF-4)
434   * \li NX_COMP_HUF Huffmann encoding (only HDF-4)
435   * \ingroup c_readwrite
436   */
437extern  NXstatus  NXcompress (NXhandle handle, int compr_type);
438
439  /**
440   * Open access to a dataset. After this call it is possible to write and read data or
441   * attributes to and from the dataset.
442   * \param handle A NeXus file handle as initialized by NXopen.
443   * \param label The name of the dataset
444   * \return NX_OK on success, NX_ERROR in the case of an error.   
445   * \ingroup c_readwrite
446   */
447extern  NXstatus  NXopendata (NXhandle handle, CONSTCHAR* label);
448
449  /**
450   * Close access to a dataset.
451   * \param handle A NeXus file handle as initialized by NXopen.
452   * \return NX_OK on success, NX_ERROR in the case of an error.   
453   * \ingroup c_readwrite
454   */
455extern  NXstatus  NXclosedata(NXhandle handle);
456
457  /**
458   * Write data to a datset which has previouly been opened with NXopendata.
459   * This writes all the data in one go. Data should be a pointer to a memory
460   * area matching the datatype and dimensions of the dataset.
461   * \param handle A NeXus file handle as initialized by NXopen.
462   * \param data Pointer to data to write.
463   * \return NX_OK on success, NX_ERROR in the case of an error.   
464   * \ingroup c_readwrite
465   */
466extern  NXstatus  NXputdata(NXhandle handle, const void* data);
467
468  /**
469   * Write an attribute. The kind of attribute written depends on the 
470   * poistion in the file: at root level, a global attribute is written, if
471   * agroup is open but no dataset, a group attribute is written, if a dataset is
472   * open, a dataset attribute is written.
473   * \param handle A NeXus file handle as initialized by NXopen.
474   * \param name The name of the attribute.
475   * \param data A pointer to the data to write for the attribute.
476   * \param iDataLen The length of the data in data in bytes.
477   * \param iType The NeXus data type of the attribute.
478   * \return NX_OK on success, NX_ERROR in the case of an error.   
479   * \ingroup c_readwrite
480   */
481extern  NXstatus  NXputattr(NXhandle handle, CONSTCHAR* name, const void* data, int iDataLen, int iType);
482
483  /**
484   * Write  a subset of a multi dimensional dataset.
485   * \param handle A NeXus file handle as initialized by NXopen.
486   * \param data A pointer to a memory area holding the data to write.
487   * \param start An array holding the start indices where to start the data subset.
488   * \param size An array holding the size of the data subset to write in each dimension.
489   * \return NX_OK on success, NX_ERROR in the case of an error.   
490   * \ingroup c_readwrite
491   */
492extern  NXstatus  NXputslab(NXhandle handle, const void* data, const int start[], const int size[]);   
493
494  /**
495   * @copydoc NXputdata()
496   */
497extern  NXstatus  NXputslab64(NXhandle handle, const void* data, const int64_t start[], const int64_t size[]);   
498
499  /**
500   * Retrieve link data for a dataset. This link data can later on be used to link this
501   * dataset into a different group.
502   * \param handle A NeXus file handle as initialized by NXopen.
503   * \param pLink A link data structure which will be initialized with the required information
504   * for linking.
505   * \return NX_OK on success, NX_ERROR in the case of an error.   
506   * \ingroup c_linking
507   */
508extern  NXstatus  NXgetdataID(NXhandle handle, NXlink* pLink);
509
510  /**
511   * Create a link to the group or dataset described by pLink in the currently open
512   * group.
513   * \param handle A NeXus file handle as initialized by NXopen.
514   * \param pLink A link data structure describing the object to link. This must have been initialized
515   * by either a call to NXgetdataID or NXgetgroupID.
516   * \return NX_OK on success, NX_ERROR in the case of an error.   
517   * \ingroup c_linking
518   */
519extern  NXstatus  NXmakelink(NXhandle handle, NXlink* pLink);
520
521  /**
522   * Create a link to the group or dataset described by pLink in the currently open
523   * group. But give the linked item a new name.
524   * \param handle A NeXus file handle as initialized by NXopen.
525   * \param newname The new name of the item in the currently open group.
526   * \param pLink A link data structure describing the object to link. This must have been initialized
527   * by either a call to NXgetdataID or NXgetgroupID.
528   * \return NX_OK on success, NX_ERROR in the case of an error.   
529   * \ingroup c_linking
530   */
531extern  NXstatus  NXmakenamedlink(NXhandle handle, CONSTCHAR* newname, NXlink* pLink);
532
533  /**
534   * Open the source group of a linked group or dataset. Returns an error when the item is
535   * not a linked item.
536   * \param handle A NeXus file handle as initialized by NXopen.
537   * \return NX_OK on success, NX_ERROR in the case of an error.   
538   * \ingroup c_navigation
539   */
540extern  NXstatus  NXopensourcegroup(NXhandle handle);
541
542  /**
543   * Read a complete dataset from the currently open dataset into memory.
544   * \param handle A NeXus file handle as initialized by NXopen.
545   * \param data A pointer to the memory area where to read the data, too. Data must point to a memory
546   * area large enough to accomodate the data read. Otherwise your program may behave in unexpected
547   * and unwelcome ways.
548   * \return NX_OK on success, NX_ERROR in the case of an error.   
549   * \ingroup c_readwrite
550   */
551extern  NXstatus  NXgetdata(NXhandle handle, void* data);
552
553  /**
554   * Retrieve information about the curretly open dataset.
555   * \param handle A NeXus file handle as initialized by NXopen.
556   * \param rank A pointer to an integer which will be filled with the rank of
557   * the dataset.
558   * \param dimension An array which will be initialized with the size of the dataset in any of its
559   * dimensions. The array must have at least the size of rank.
560   * \param datatype A pointer to an integer which be set to the NeXus data type code for this dataset.
561   * \return NX_OK on success, NX_ERROR in the case of an error.   
562   * \ingroup c_metadata
563   */
564extern  NXstatus  NXgetinfo(NXhandle handle, int* rank, int dimension[], int* datatype);
565
566  /**
567   * @copydoc NXgetinfo()
568   */
569extern  NXstatus  NXgetinfo64(NXhandle handle, int* rank, int64_t dimension[], int* datatype);
570
571  /**
572   * Get the next entry in the currently open group. This is for retrieving infromation about the
573   * content of a NeXus group. In order to search a group #NXgetnextentry is called in a loop until
574   * #NXgetnextentry returns NX_EOD which indicates that there are no further items in the group.
575   * Reset search using #NXinitgroupdir
576   * \param handle A NeXus file handle as initialized by NXopen.
577   * \param name The name of the object
578   * \param nxclass The NeXus class name for a group or the string SDS for a dataset.
579   * \param datatype The NeXus data type if the item is a SDS.
580   * \return NX_OK on success, NX_ERROR in the case of an error, NX_EOD when there are no more items.   
581   * \ingroup c_navigation
582   */
583extern  NXstatus  NXgetnextentry(NXhandle handle, NXname name, NXname nxclass, int* datatype);
584
585  /**
586   * Read a subset of data from file into memory.
587   * \param handle A NeXus file handle as initialized by NXopen.
588   * \param data A pointer to the memory data where to copy the data too. The pointer must point
589   * to a memory area large enough to accomodate the size of the data read.
590   * \param start An array holding the start indices where to start reading the data subset.
591   * \param size An array holding the size of the data subset to read for each dimension.
592   * \return NX_OK on success, NX_ERROR in the case of an error.   
593   * \ingroup c_readwrite
594   */
595extern  NXstatus  NXgetslab(NXhandle handle, void* data, const int start[], const int size[]);
596
597
598  /**
599   * @copydoc NXgetslab()
600   */
601extern  NXstatus  NXgetslab64(NXhandle handle, void* data, const int64_t start[], const int64_t size[]);
602
603/**
604   * Iterate over global, group or dataset attributes depending on the currently open group or
605   * dataset. In order to search attributes multiple calls to #NXgetnextattr are performed in a loop
606   * until #NXgetnextattr returns NX_EOD which indicates that there are no further attributes.
607   * reset search using #NXinitattrdir
608   * \param handle A NeXus file handle as initialized by NXopen.
609   * \param pName The name of the attribute
610   * \param iLength A pointer to an integer which be set to the length of the attribute data.
611   * \param iType A pointer to an integer which be set to the NeXus data type of the attribute.
612   * \return NX_OK on success, NX_ERROR in the case of an error, NX_EOD when there are no more items.   
613   * \ingroup c_readwrite
614   */
615extern  NXstatus  NXgetnextattr(NXhandle handle, NXname pName, int *iLength, int *iType);
616
617  /**
618   * Read an attribute.
619   * \param handle A NeXus file handle as initialized by NXopen.
620   * \param name The name of the atrribute to read.
621   * \param data A pointer to a memory area large enough to hold the attributes value.
622   * \param iDataLen The length of data in bytes.
623   * \param iType A pointer to an integer which will had been set to the NeXus data type of the attribute.
624   * \return NX_OK on success, NX_ERROR in the case of an error.   
625   * \ingroup c_readwrite
626   */
627extern  NXstatus  NXgetattr(NXhandle handle, char* name, void* data, int* iDataLen, int* iType);
628
629  /**
630   * Get the count of attributes in the currently open dataset, group or global attributes when at root level.
631   * \param handle A NeXus file handle as initialized by NXopen.
632   * \param no_items A pointer to an integer which be set to the number of attributes available.
633   * \return NX_OK on success, NX_ERROR in the case of an error.   
634   * \ingroup c_metadata
635   */
636extern  NXstatus  NXgetattrinfo(NXhandle handle, int* no_items);
637
638  /**
639   * Retrieve link data for the currently open group. This link data can later on be used to link this
640   * group into a different group.
641   * \param handle A NeXus file handle as initialized by NXopen.
642   * \param pLink A link data structure which will be initialized with the required information
643   * for linking.
644   * \return NX_OK on success, NX_ERROR in the case of an error.   
645   * \ingroup c_linking
646   */
647extern  NXstatus  NXgetgroupID(NXhandle handle, NXlink* pLink);
648
649  /**
650   * Retrieve information about the currently open group.
651   * \param handle A NeXus file handle as initialized by NXopen.
652   * \param no_items A pointer to an integer which will be set to the count
653   *   of group elements available. This is the count of other groups and
654   * data sets in this group. 
655   * \param name The name of the group.
656   * \param nxclass The NeXus class name of the group.
657   * \return NX_OK on success, NX_ERROR in the case of an error.   
658   * \ingroup c_metadata
659   */
660extern  NXstatus  NXgetgroupinfo(NXhandle handle, int* no_items, NXname name, NXname nxclass);
661
662  /**
663   * Tests if two link data structures describe the same item.
664   * \param handle A NeXus file handle as initialized by NXopen.
665   * \param pFirstID The first link data for the test.
666   * \param pSecondID The second link data structure.
667   * \return NX_OK when both link data structures describe the same item, NX_ERROR else.   
668   * \ingroup c_linking
669   */
670extern  NXstatus  NXsameID(NXhandle handle, NXlink* pFirstID, NXlink* pSecondID);
671
672  /**
673   * Resets a pending group search to the start again. To be called in a #NXgetnextentry loop when
674   * a group search has to be restarted.
675   * \param handle A NeXus file handle as initialized by NXopen.
676   * \return NX_OK on success, NX_ERROR in the case of an error.   
677   * \ingroup c_navigation
678   */
679extern  NXstatus  NXinitgroupdir(NXhandle handle);
680
681  /**
682   * Resets a pending attribute search to the start again. To be called in a #NXgetnextattr loop when
683   * an attribute search has to be restarted.
684   * \param handle A NeXus file handle as initialized by NXopen.
685   * \return NX_OK on success, NX_ERROR in the case of an error.   
686   * \ingroup c_navigation
687   */
688extern  NXstatus  NXinitattrdir(NXhandle handle);
689
690  /**
691   * Sets the format for number printing. This call has only an effect when using the XML physical file
692   * format.
693   * \param handle A NeXus file handle as initialized by NXopen.
694   * \param type The NeXus data type to set the format for.
695   * \param format The C-language format string to use for this data type.
696   * \return NX_OK on success, NX_ERROR in the case of an error.   
697   * \ingroup c_readwrite
698   */
699extern  NXstatus  NXsetnumberformat(NXhandle handle, int type, char *format);
700
701  /**
702   * Inquire the filename of the currently open file. FilenameBufferLength of the file name
703   * will be copied into the filename buffer.
704   * \param handle A NeXus file handle as initialized by NXopen.
705   * \param filename The buffer to hold the filename.
706   * \param  filenameBufferLength The length of the filename buffer.
707   * \return NX_OK on success, NX_ERROR in the case of an error.   
708   * \ingroup c_metadata
709   */
710extern  NXstatus  NXinquirefile(NXhandle handle, char *filename, int filenameBufferLength);
711
712  /**
713   * Test if a group is actually pointing to an external file. If so, retrieve the URL of the
714   * external file.
715   * \param handle A NeXus file handle as initialized by NXopen.
716   * \param name The name of the group to test.
717   * \param nxclass The class name of the group to test.
718   * \param url A buffer to copy the URL too.
719   * \param urlLen The length of the Url buffer. At maximum urlLen bytes will be copied to url.
720   * \return NX_OK when the group is pointing to an external file, NX_ERROR else.
721   * \ingroup c_external
722   */
723extern  NXstatus  NXisexternalgroup(NXhandle handle, CONSTCHAR *name, CONSTCHAR *nxclass, char *url, int urlLen); 
724
725
726  /**
727   * Test if a dataset is actually pointing to an external file. If so, retrieve the URL of the
728   * external file.
729   * \param handle A NeXus file handle as initialized by NXopen.
730   * \param name The name of the dataset to test.
731   * \param url A buffer to copy the URL too.
732   * \param urlLen The length of the Url buffer. At maximum urlLen bytes will be copied to url.
733   * \return NX_OK when the dataset is pointing to an external file, NX_ERROR else.
734   * \ingroup c_external
735   */
736extern  NXstatus  NXisexternaldataset(NXhandle handle, CONSTCHAR *name, char *url, int urlLen); 
737
738  /**
739   * Create a link to a group in an external file. This works by creating a NeXus group under the current level in
740   * the hierarchy which actually points to a group in another file.
741   * \param handle A NeXus file handle as initialized by NXopen.
742   * \param name The name of the group which points to the external file.
743   * \param nxclass The class name of the group which points to the external file.
744   * \param url The URL of the external file. Currently only one URL format is supported: nxfile://path-tofile\#path-in-file.
745   * This consists of two parts: the first part is of course the path to the file. The second part, path-in-file, is the
746   * path to the group in the external file which appears in the first file. 
747   * \return NX_OK on success, NX_ERROR in the case of an error.   
748   * \ingroup c_external
749   */
750extern  NXstatus  NXlinkexternal(NXhandle handle, CONSTCHAR *name, CONSTCHAR *nxclass, CONSTCHAR *url);
751
752
753  /**
754   * Create a link to a dataset in an external file. This works by creating a dataset under the current level in
755   * the hierarchy which actually points to a dataset in another file.
756   * \param handle A NeXus file handle as initialized by NXopen.
757   * \param name The name of the dataset which points to the external file.
758   * \param url The URL of the external file. Currently only one URL format is supported: nxfile://path-tofile\#path-in-file.
759   * This consists of two parts: the first part is of course the path to the file. The second part, path-in-file, is the
760   * path to the dataset in the external file which appears in the first file. 
761   * \return NX_OK on success, NX_ERROR in the case of an error.   
762   * \ingroup c_external
763   */
764extern  NXstatus  NXlinkexternaldataset(NXhandle handle, CONSTCHAR *name, CONSTCHAR *url);
765
766  /**
767   * Utility function which allocates a suitably sized memory area for the dataset characteristics specified.
768   * \param data A pointer to a pointer which will be initialized with a pointer to a suitably sized memory area.
769   * \param rank the rank of the data.
770   * \param dimensions An array holding the size of the data in each dimension.
771   * \param datatype The NeXus data type of the data.
772   * \return NX_OK when allocation succeeds, NX_ERROR in the case of an error.   
773   * \ingroup c_memory
774   */ 
775extern  NXstatus  NXmalloc(void** data, int rank, const int dimensions[], int datatype);
776
777  /**
778   * @copydoc NXmalloc()
779   */ 
780extern  NXstatus  NXmalloc64(void** data, int rank, const int64_t dimensions[], int datatype);
781
782
783  /**
784   * Utility function to return NeXus version
785   * \return pointer to string in static storage. Version in
786   * same format as NEXUS_VERSION string in napi.h i.e. "major.minor.patch"
787   * \ingroup c_metadata
788   */
789extern  const char* NXgetversion();
790
791  /**
792   * Utility function to release the memory for data.
793   * \param data A pointer to a pointer to free.
794   * \return NX_OK on success, NX_ERROR in the case of an error.   
795   * \ingroup c_memory
796   */
797extern  NXstatus  NXfree(void** data);
798
799
800/*-----------------------------------------------------------------------
801    NAPI internals
802------------------------------------------------------------------------*/
803  /**
804   * Retrieve information about the currently open dataset. In contrast to the main function below,
805   * this function does not try to find out about the size of strings properly.
806   * \param handle A NeXus file handle as initialized by NXopen.
807   * \param rank A pointer to an integer which will be filled with the rank of
808   * the dataset.
809   * \param dimension An array which will be initialized with the size of the dataset in any of its
810   * dimensions. The array must have at least the size of rank.
811   * \param datatype A pointer to an integer which be set to the NeXus data type code for this dataset.
812   * \return NX_OK on success, NX_ERROR in the case of an error.   
813   * \ingroup c_metadata
814   */
815extern  NXstatus  NXgetrawinfo(NXhandle handle, int* rank, int dimension[], int* datatype);
816
817 /**
818  * @copydoc NXgetrawinfo
819  */
820extern  NXstatus  NXgetrawinfo64(NXhandle handle, int* rank, int64_t dimension[], int* datatype);
821
822/** \typedef void (*ErrFunc)(void *data, char *text)
823 * All NeXus error reporting happens through this special function, the
824 * ErrFunc. The NeXus-API allows to replace this error reporting function
825 * through a user defined implementation. The default error function prints to stderr. User
826 * defined ones may pop up dialog boxes or whatever.
827 * \param data A pointer to some user defined data structure
828 * \param text The text of the error message to display.
829 */
830typedef void (*ErrFunc)(void *data, char *text);
831
832  /**
833   * Set a global error function.
834   * Not threadsafe.
835   * \param pData A pointer to a user defined data structure which be passed to
836   * the error display function.
837   * \param newErr The new error display function.
838   */
839extern  void  NXMSetError(void *pData, ErrFunc newErr);
840
841  /**
842   * Set an error function for the current thread.
843   * When used this overrides anything set in NXMSetError (for the current thread).
844   * Use this method in threaded applications.
845   * \param pData A pointer to a user defined data structure which be passed to
846   * the error display function.
847   * \param newErr The new error display function.
848   */
849extern  void  NXMSetTError(void *pData, ErrFunc newErr);
850
851  /**
852   * Retrieve the current error display function
853   * \return The current error display function.
854   */
855extern ErrFunc NXMGetError();
856
857  /**
858   * Suppress error reports from the NeXus-API
859   */
860extern  void  NXMDisableErrorReporting();
861
862  /**
863   * Enable error reports from the NeXus-API
864   */
865extern  void  NXMEnableErrorReporting();
866
867 /**
868  * Dispatches the error message to the error function defined by NXMSetTError
869  */
870extern void NXReportError(char *text);
871
872 /**
873  * Do not use, first parameter should be set by NXMSetTError
874  */
875extern void NXIReportError(void *pData,char *text);
876/* extern void *NXpData; */
877extern char *NXIformatNeXusTime();
878extern  NXstatus  NXIprintlink(NXhandle fid, NXlink* link);
879
880/**
881 * A function for setting the default cache size for HDF-5
882 * \ingroup c_init
883 */
884extern  NXstatus  NXsetcache(long newVal);
885
886  typedef struct {
887        NXhandle pNexusData;   
888        NXstatus ( *nxreopen)(NXhandle pOrigHandle, NXhandle* pNewHandle);
889        NXstatus ( *nxclose)(NXhandle* pHandle);
890        NXstatus ( *nxflush)(NXhandle* pHandle);
891        NXstatus ( *nxmakegroup) (NXhandle handle, CONSTCHAR *name, CONSTCHAR* NXclass);
892        NXstatus ( *nxopengroup) (NXhandle handle, CONSTCHAR *name, CONSTCHAR* NXclass);
893        NXstatus ( *nxclosegroup)(NXhandle handle);
894        NXstatus ( *nxmakedata64) (NXhandle handle, CONSTCHAR* label, int datatype, int rank, int64_t dim[]);
895        NXstatus ( *nxcompmakedata64) (NXhandle handle, CONSTCHAR* label, int datatype, int rank, int64_t dim[], int comp_typ, int64_t bufsize[]);
896        NXstatus ( *nxcompress) (NXhandle handle, int compr_type);
897        NXstatus ( *nxopendata) (NXhandle handle, CONSTCHAR* label);
898        NXstatus ( *nxclosedata)(NXhandle handle);
899        NXstatus ( *nxputdata)(NXhandle handle, const void* data);
900        NXstatus ( *nxputattr)(NXhandle handle, CONSTCHAR* name, const void* data, int iDataLen, int iType);
901        NXstatus ( *nxputslab64)(NXhandle handle, const void* data, const int64_t start[], const int64_t size[]);   
902        NXstatus ( *nxgetdataID)(NXhandle handle, NXlink* pLink);
903        NXstatus ( *nxmakelink)(NXhandle handle, NXlink* pLink);
904        NXstatus ( *nxmakenamedlink)(NXhandle handle, CONSTCHAR *newname, NXlink* pLink);
905        NXstatus ( *nxgetdata)(NXhandle handle, void* data);
906        NXstatus ( *nxgetinfo64)(NXhandle handle, int* rank, int64_t dimension[], int* datatype);
907        NXstatus ( *nxgetnextentry)(NXhandle handle, NXname name, NXname nxclass, int* datatype);
908        NXstatus ( *nxgetslab64)(NXhandle handle, void* data, const int64_t start[], const int64_t size[]);
909        NXstatus ( *nxgetnextattr)(NXhandle handle, NXname pName, int *iLength, int *iType);
910        NXstatus ( *nxgetattr)(NXhandle handle, char* name, void* data, int* iDataLen, int* iType);
911        NXstatus ( *nxgetattrinfo)(NXhandle handle, int* no_items);
912        NXstatus ( *nxgetgroupID)(NXhandle handle, NXlink* pLink);
913        NXstatus ( *nxgetgroupinfo)(NXhandle handle, int* no_items, NXname name, NXname nxclass);
914        NXstatus ( *nxsameID)(NXhandle handle, NXlink* pFirstID, NXlink* pSecondID);
915        NXstatus ( *nxinitgroupdir)(NXhandle handle);
916        NXstatus ( *nxinitattrdir)(NXhandle handle);
917        NXstatus ( *nxsetnumberformat)(NXhandle handle, int type, char *format);
918        NXstatus ( *nxprintlink)(NXhandle handle, NXlink* link);
919        NXstatus ( *nxnativeexternallink)(NXhandle handle, CONSTCHAR* name, CONSTCHAR* externalfile, CONSTCHAR* remotetarget);
920        NXstatus ( *nxnativeinquirefile)(NXhandle handle, char* externalfile, const int filenamelength);
921        NXstatus ( *nxnativeisexternallink)(NXhandle handle, CONSTCHAR* name, char* url, int urllen);
922        int stripFlag;
923        int checkNameSyntax;
924  } NexusFunction, *pNexusFunction;
925  /*---------------------*/
926  extern long nx_cacheSize;
927
928/* FORTRAN internals */
929
930  extern NXstatus  NXfopen(char * filename, NXaccess* am, 
931                                        NXhandle pHandle);
932  extern NXstatus  NXfclose (NXhandle pHandle);
933  extern NXstatus  NXfputattr(NXhandle fid, const char *name, const void *data, 
934                                   int *pDatalen, int *pIType);
935  extern NXstatus  NXfcompress(NXhandle fid, int *compr_type);
936  extern NXstatus  NXfcompmakedata(NXhandle fid, char *name, 
937                int *pDatatype,
938                int *pRank, int dimensions[],
939                int *compression_type, int chunk[]);
940  extern NXstatus  NXfmakedata(NXhandle fid, char *name, int *pDatatype,
941                int *pRank, int dimensions[]);
942  extern NXstatus  NXfflush(NXhandle pHandle);
943  extern NXstatus  NXfgetpath(NXhandle fid, char *path, int *pathlen);
944#ifdef __cplusplus
945}
946#endif /* __cplusplus */
947
948/**
949 * Freddie Akeroyd 11/8/2009
950 * Add NeXus schema support - this uses BASE.xsd as the initial file
951 */
952#define NEXUS_SCHEMA_VERSION    "3.1"   /**< version of NeXus definition schema */
953#define NEXUS_SCHEMA_ROOT       "http://definition.nexusformat.org/schema/"     /**< XML schema namespace specified by xmlns */
954#define NEXUS_SCHEMA_NAMESPACE  NEXUS_SCHEMA_ROOT NEXUS_SCHEMA_VERSION  /**< XML schema namespace specified by xmlns */
955#define NEXUS_SCHEMA_BASE       "BASE"
956#define NEXUS_SCHEMA_FILE       NEXUS_SCHEMA_BASE ".xsd" /**< default schema file for namespace */
957#define NEXUS_SCHEMA_URL        NEXUS_SCHEMA_NAMESPACE "/" NEXUS_SCHEMA_FILE /**< location of default schema file for namespace */
958
959#endif /*NEXUSAPI*/
Note: See TracBrowser for help on using the repository browser.