Changeset 1230 for branches/4.2/include/napi.h

Timestamp:

14/04/09 18:56:40 (3 years ago)

Author:

Freddie Akeroyd

Message:

Merg in r1212:r1222 from trunk. Refs #115.

File:

• branches/4.2/include/napi.h (modified) (41 diffs)

branches/4.2/include/napi.h

@@ -27 +27 @@
 /** \file 
  * Documentation for the NeXus-API version 4.2
- * 2000-2007, the NeXus group 
+ * 2000-2007, the NeXus group
+ * \defgroup c_main C API 
+ * \defgroup c_types Data Types
+ * \ingroup c_main
+ * \defgroup c_init General Initialisation and shutdown
+ * \ingroup c_main
+ * \defgroup c_readwrite Reading and Writing
+ * \ingroup c_main
+ * \defgroup c_metadata Meta data routines
+ * \ingroup c_main
+ * \defgroup c_linking Linking and Group hierarchy
+ * \ingroup c_main
+ * \defgroup c_memory Memory allocation
+ * \ingroup c_main
+ * \defgroup c_external External linking
+ * \ingroup c_main
+ * \defgroup cpp_main C++ API
  */
   
@@ -95 +111 @@
 
 /** \var NeXus data types
+ * \ingroup c_types
  * \li NX_FLOAT32     32 bit float
  * \li NX_FLOAT64     64 nit float == double
@@ -182 +199 @@
 
 #    define NXgetinfo           MANGLE(nxigetinfo)
+#    define NXgetrawinfo        MANGLE(nxigetrawinfo)
 #    define NXgetnextentry      MANGLE(nxigetnextentry)
 #    define NXgetdata           MANGLE(nxigetdata)
@@ -243 +261 @@
    * \param pHandle A file handle which will be initialized upon successfull completeion of NXopen.
    * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_init
    */
 extern  NXstatus  NXopen(CONSTCHAR * filename, NXaccess access_method, NXhandle* pHandle);
+
   /**
    * close a NeXus file
@@ -250 +270 @@
    * call.
    * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_init
    */
 extern  NXstatus  NXclose(NXhandle* pHandle);
+
   /**
    * flush data to disk
    * \param pHandle A NeXus file handle as initialized by NXopen. 
    * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_readwrite
    */
 extern  NXstatus  NXflush(NXhandle* pHandle);
@@ -266 +289 @@
    * \param NXclass the class name of the group. Should start with the prefix NX
    * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_init
    */
 extern  NXstatus  NXmakegroup (NXhandle handle, CONSTCHAR *name, CONSTCHAR* NXclass);
+
   /**
    * Step into a group. All further access will be within the opened group.
@@ -274 +299 @@
    * \param NXclass the class name of the group. Should start with the prefix NX
    * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_init
    */
 extern  NXstatus  NXopengroup (NXhandle handle, CONSTCHAR *name, CONSTCHAR* NXclass);
+
   /**
    * Open the NeXus object with the path specified
@@ -283 +310 @@
    * Example: /entry1/sample/name 
    * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_init
    */
 extern  NXstatus  NXopenpath (NXhandle handle, CONSTCHAR *path);
+
   /**
    * Opens the group in which the NeXus object with the specified path exists
@@ -292 +321 @@
    * Example: /entry1/sample/name 
    * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_readwrite
    */
 extern  NXstatus  NXopengrouppath (NXhandle handle, CONSTCHAR *path);
+
   /**
    * Closes the currently open group and steps one step down in the NeXus file 
    * hierarchy.
    * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_init
    */
 extern  NXstatus  NXclosegroup(NXhandle handle);
+
   /**
    * Create a multi dimensional data array or dataset. The dataset is NOT opened. 
@@ -309 +342 @@
    * can be NX_UNLIMITED. Data can be appended to such a dimension using NXputslab. 
    * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_init
    */
 extern  NXstatus  NXmakedata (NXhandle handle, CONSTCHAR* label, int datatype, int rank, int dim[]);
+
   /**
    * Create a compressed dataset. The dataset is NOT opened. Data from this set will automatically be compressed when 
@@ -329 +364 @@
    * should be the same as the data dimension. If you write it in slabs, this is your preferred slab size. 
    * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_init
    */
 extern  NXstatus  NXcompmakedata (NXhandle handle, CONSTCHAR* label, int datatype, int rank, int dim[], int comp_typ, int bufsize[]);
+
   /**
    * Switch compression on. This routine is superseeded by NXcompmakedata and thus 
@@ -340 +377 @@
    * \li NX_COMP_RLE run length encoding (only HDF-4)
    * \li NX_COMP_HUF Huffmann encoding (only HDF-4)
+   * \ingroup c_init
    */
 extern  NXstatus  NXcompress (NXhandle handle, int compr_type);
+
   /**
    * Open access to a dataset. After this call it is possible to write and read data or 
@@ -348 +387 @@
    * \param label The name of the dataset
    * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_init
    */
 extern  NXstatus  NXopendata (NXhandle handle, CONSTCHAR* label);
+
   /**
    * Close access to a dataset. 
    * \param handle A NeXus file handle as initialized by NXopen. 
    * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_readwrite
    */
 extern  NXstatus  NXclosedata(NXhandle handle);
+
   /**
    * Write data to a datset which has previouly been opened with NXopendata. 
@@ -363 +406 @@
    * \param data Pointer to data to write.
    * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_init
    */
 extern  NXstatus  NXputdata(NXhandle handle, void* data);
+
   /**
    * Write an attribute. The kind of attribute written depends on the  
@@ -376 +421 @@
    * \param iType The NeXus data type of the attribute. 
    * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_readwrite
    */
 extern  NXstatus  NXputattr(NXhandle handle, CONSTCHAR* name, void* data, int iDataLen, int iType);
+
   /**
    * Write  a subset of a multi dimensional dataset.
@@ -385 +432 @@
    * \param size An array holding the size of the data subset to write in each dimension.
    * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_readwrite
    */
 extern  NXstatus  NXputslab(NXhandle handle, void* data, int start[], int size[]);    
+
   /**
    * Retrieve link data for a dataset. This link data can later on be used to link this 
@@ -394 +443 @@
    * for linking. 
    * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_readwrite
    */
 extern  NXstatus  NXgetdataID(NXhandle handle, NXlink* pLink);
+
   /**
    * Create a link to the group or dataset described by pLink in the currently open 
@@ -403 +454 @@
    * by either a call to NXgetdataID or NXgetgroupID.
    * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_readwrite
    */
 extern  NXstatus  NXmakelink(NXhandle handle, NXlink* pLink);
+
   /**
    * Create a link to the group or dataset described by pLink in the currently open 
@@ -413 +466 @@
    * by either a call to NXgetdataID or NXgetgroupID.
    * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_linking
    */
 extern  NXstatus  NXmakenamedlink(NXhandle handle, CONSTCHAR* newname, NXlink* pLink);
+
   /**
    * Open the source group of a linked group or dataset. Returns an error when the item is 
@@ -420 +475 @@
    * \param handle A NeXus file handle as initialized by NXopen.
    * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_linking
    */
 extern  NXstatus  NXopensourcegroup(NXhandle handle);
+
   /**
    * Read a complete dataset from the currently open dataset into memory. 
@@ -429 +486 @@
    * and unwelcome ways.
    * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_readwrite
    */
 extern  NXstatus  NXgetdata(NXhandle handle, void* data);
+
   /**
    * Retrieve information about the curretly open dataset.
@@ -440 +499 @@
    * \param datatype A pointer to an integer which be set to the NeXus data type code for this dataset.
    * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_metadata
    */
 extern  NXstatus  NXgetinfo(NXhandle handle, int* rank, int dimension[], int* datatype);
+
   /**
    * Get the next entry in the currently open group. This is for retrieving infromation about the 
@@ -451 +512 @@
    * \param datatype The NeXus data type if the item is a SDS. 
    * \return NX_OK on success, NX_ERROR in the case of an error, NX_EOD when there are no more items.   
+   * \ingroup c_readwrite
    */
 extern  NXstatus  NXgetnextentry(NXhandle handle, NXname name, NXname nxclass, int* datatype);
+
   /**
    * Read a subset of data from file into memory. 
@@ -461 +524 @@
    * \param size An array holding the size of the data subset to read for each dimension.
    * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_readwrite
    */
 extern  NXstatus  NXgetslab(NXhandle handle, void* data, int start[], int size[]);
+
   /**
    * Iterate over global, group or dataset attributes depending on the currently open group or 
@@ -472 +537 @@
    * \param iType A pointer to an integer which be set to the NeXus data type of the attribute.
    * \return NX_OK on success, NX_ERROR in the case of an error, NX_EOD when there are no more items.   
+   * \ingroup c_readwrite
    */
 extern  NXstatus  NXgetnextattr(NXhandle handle, NXname pName, int *iLength, int *iType);
+
   /**
    * Read an attribute.
@@ -482 +549 @@
    * \param iType A pointer to an integer which will had been set to the NeXus data type of the attribute.
    * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_readwrite
    */
 extern  NXstatus  NXgetattr(NXhandle handle, char* name, void* data, int* iDataLen, int* iType);
+
   /**
    * Get the count of attributes in the currently open dataset, group or global attributes when at root level.
@@ -489 +558 @@
    * \param no_items A pointer to an integer which be set to the number of attributes available.
    * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_readwrite
    */
 extern  NXstatus  NXgetattrinfo(NXhandle handle, int* no_items);
+
   /**
    * Retrieve link data for the currently open group. This link data can later on be used to link this 
@@ -498 +569 @@
    * for linking. 
    * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_readwrite
    */
 extern  NXstatus  NXgetgroupID(NXhandle handle, NXlink* pLink);
+
   /**
    * Retrieve information about the currently open group.
@@ -509 +582 @@
    * \param nxclass The NeXus class name of the group.
    * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_readwrite
    */
 extern  NXstatus  NXgetgroupinfo(NXhandle handle, int* no_items, NXname name, NXname nxclass);
+
   /**
    * Tests if two link data structures describe the same item.
@@ -517 +592 @@
    * \param pSecondID The second link data structure.
    * \return NX_OK when both link data structures describe the same item, NX_ERROR else.   
+   * \ingroup c_readwrite
    */
 extern  NXstatus  NXsameID(NXhandle handle, NXlink* pFirstID, NXlink* pSecondID);
@@ -524 +600 @@
    * \param handle A NeXus file handle as initialized by NXopen.
    * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_readwrite
    */
 extern  NXstatus  NXinitgroupdir(NXhandle handle);
+
   /**
    * Resets a pending attribute search to the start again. To be called in a Nxgetnextattr loop when 
@@ -531 +609 @@
    * \param handle A NeXus file handle as initialized by NXopen.
    * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_readwrite
    */
 extern  NXstatus  NXinitattrdir(NXhandle handle);
+
   /**
    * Sets the format for number printing. This call has only an effect when using the XML physical file 
@@ -540 +620 @@
    * \param format The C-language format string to use for this data type.
    * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_readwrite
    */
 extern  NXstatus  NXsetnumberformat(NXhandle handle, int type, char *format);
+
   /**
    * Inquire the filename of the currently open file. FilenameBufferLength of the file name 
@@ -549 +631 @@
    * \param  filenameBufferLength The length of the filename buffer.
    * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_readwrite
    */
 extern  NXstatus  NXinquirefile(NXhandle handle, char *filename, int filenameBufferLength);
+
   /**
    * Test if a group is actually pointing to an external file. If so, retrieve the URL of the 
@@ -560 +644 @@
    * \param urlLen The length of the Url buffer. At maximum urlLen bytes will be copied to url.
    * \return NX_OK when the group is pointing to an external file, NX_ERROR else.
+   * \ingroup c_readwrite
    */
 extern  NXstatus  NXisexternalgroup(NXhandle handle, CONSTCHAR *name, CONSTCHAR *nxclass, char *url, int urlLen); 
+
   /**
    * Create a link to an external file. This works by creating a NeXus group under the current level in 
@@ -572 +658 @@
    * path to the group in the external file which appears in the first file.  
    * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_readwrite
    */
 extern  NXstatus  NXlinkexternal(NXhandle handle, CONSTCHAR *name, CONSTCHAR *nxclass, CONSTCHAR *url);
+
   /**
    * Utility function which allocates a suitably sized memory area for the dataset characteristics specified.
@@ -581 +669 @@
    * \param datatype The NeXus data type of the data.
    * \return NX_OK when allocation succeeds, NX_ERROR in the case of an error.   
+   * \ingroup c_memory
    */ 
 extern  NXstatus  NXmalloc(void** data, int rank, int dimensions[], int datatype);
+
   /**
    * Utility function to release the memory for data.
    * \param data A pointer to a pointer to free.
    * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_memory
    */
 extern  NXstatus  NXfree(void** data);
@@ -594 +685 @@
     NAPI internals 
 ------------------------------------------------------------------------*/
+  /**
+   * Retrieve information about the currently open dataset. In contrast to the main function below, 
+   * this function does not try to find out about the size of strings properly. 
+   * \param handle A NeXus file handle as initialized by NXopen.
+   * \param rank A pointer to an integer which will be filled with the rank of 
+   * the dataset.
+   * \param dimension An array which will be initialized with the size of the dataset in any of its 
+   * dimensions. The array must have at least the size of rank.
+   * \param datatype A pointer to an integer which be set to the NeXus data type code for this dataset.
+   * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_metadata
+   */
+extern  NXstatus  NXgetrawinfo(NXhandle handle, int* rank, int dimension[], int* datatype);
+
 /** \typedef void (*ErrFunc)(void *data, char *text)
  * All NeXus error reporting happens through this special function, the 
@@ -603 +708 @@
  */
 typedef void (*ErrFunc)(void *data, char *text);
+
   /**
    * Set an error function.
@@ -610 +716 @@
    */
 extern  void  NXMSetError(void *pData, ErrFunc newErr);
+
   /**
    * Retrieve the current error display function
@@ -615 +722 @@
    */
 extern ErrFunc NXMGetError();
+
   /**
    * Suppress error reports from the NeXus-API
    */
 extern  void  NXMDisableErrorReporting();
+
   /**
    * Enable error reports from the NeXus-API