source: XIOS/trunk/extern/src_netcdf4/oc.h @ 409

/* Copyright 2009, UCAR/Unidata and OPeNDAP, Inc.
   See the COPYRIGHT dap for more information. */

/*
Draft OC External Interface
Created: 4/4/2009
Last Revised: 4/14/2009
*/

#ifndef OC_H
#define OC_H

#include <stdlib.h>
#include <stdio.h>

/* if defined, use magic numbers for consistency]) */
#define OC_FASTCONSISTENCY

/* OC_MAX_DIMS should be greater or equal to max allowed by dap or netcdf*/
#define OC_MAX_DIMS 1024

/* Specifies the OCtype.*/
/* Primitives = Duplicate of the NODE_Byte..Node_URL union nc_type*/

typedef unsigned long OCtype;

/* Note: use #define rather than enum so we can extend if needed
   more easily */
/* Primitives*/
/* OC_Ubyte, OC_Char, OC_Int64 and OC_UInt64 are defined for future extension*/
#define OC_NAT ((OCtype)0)
#define OC_Char ((OCtype)1)
#define OC_Byte ((OCtype)2)
#define OC_UByte ((OCtype)3)
#define OC_Int16 ((OCtype)4)
#define OC_UInt16 ((OCtype)5)
#define OC_Int32 ((OCtype)6)
#define OC_UInt32 ((OCtype)7)
#define OC_Int64 ((OCtype)8)
#define OC_UInt64 ((OCtype)9)
#define OC_Float32 ((OCtype)10)
#define OC_Float64 ((OCtype)11)
#define OC_String ((OCtype)12)
#define OC_URL ((OCtype)13)

/* Non-primitives*/
#define OC_Dataset      ((OCtype)100)
#define OC_Sequence     ((OCtype)101)
#define OC_Grid         ((OCtype)102)
#define OC_Structure    ((OCtype)103)
#define OC_Dimension    ((OCtype)104)
#define OC_Attribute    ((OCtype)105)
#define OC_Attributeset ((OCtype)106)
#define OC_Primitive    ((OCtype)107)
#define OC_Group        ((OCtype)108)
#define OC_Type         ((OCtype)109)

/* Define a set of error
  positive are system errors
  (needs work)
*/

typedef int OCerror;
#define OC_NOERR        (0)
#define OC_EBADID       (-1)
#define OC_ECHAR        (-2)
#define OC_EDIMSIZE     (-3)
#define OC_EEDGE        (-4)
#define OC_EINVAL       (-5)
#define OC_EINVALCOORDS (-6)
#define OC_ENOMEM       (-7)
#define OC_ENOTVAR      (-8)
#define OC_EPERM        (-9)
#define OC_ESTRIDE      (-10)
#define OC_EDAP         (-11)
#define OC_EXDR         (-12)
#define OC_ECURL        (-13)
#define OC_EBADURL      (-14)
#define OC_EBADVAR      (-15)
#define OC_EOPEN        (-16)
#define OC_EIO          (-17)
#define OC_ENODATA      (-18)
#define OC_EDAPSVC      (-19)
#define OC_ENAMEINUSE   (-20)
#define OC_EDAS         (-21)
#define OC_EDDS         (-22)
#define OC_EDATADDS     (-23)
#define OC_ERCFILE      (-24)
#define OC_ENOFILE      (-25)

/* Define the classes of DAP DXD objects */
typedef int OCdxd;
#define OCDDS     0
#define OCDAS     1
#define OCDATADDS 2
#define OCDATA OCDATADDS

/* Define flags */
typedef int OCflags;
#define OCONDISK 1

typedef enum OCmode {
OCNULLMODE = 0,
OCFIELDMODE = 1,
OCSEQUENCEMODE = 2,
OCARRAYMODE = 3,
OCPRIMITIVEMODE = 4,
OCEMPTYMODE = 0x8000000 /* internal use only */
} OCmode;


/* Define an unsigned alternative to off(64)_t*/
typedef unsigned long long ocoffset_t;

/* Define a wrapper for dimension sizes */
typedef size_t ocindex_t;

/* Define the effective API */

#ifndef OCINTERNAL_H

/* The OCobject type references a component of a DAS or DDS
   (e.g. Sequence, Grid, Dataset, etc). These objects
   are nested, so most objects reference a container object
   and subnode objects.
*/


#ifdef OC_FASTCONSISTENCY
/* Use unsigned int * so we can dereference to get magic number */
typedef unsigned int* OCobject;
#define OCNULL NULL
#else
typedef unsigned long OCobject;
#define OCNULL ((OCobject)0)
#endif

/* These are the two critical types*/
/* Think of OClink as analogous to the C stdio FILE structure;
   it "holds" all the other state info about
   a connection to the server, the url request, and the DAS/DDS/DATADDSinfo.
*/
/* Renamed from OCconnection because of confusion about term "connection"
   3/24/2010 by dmh
*/
typedef OCobject OClink;

/* Keep old name for back compatibility */
typedef OClink OCconnection; /*Deprecated*/

/* Tag kind of log entry*/
#define OCLOGNOTE 0
#define OCLOGWARN 1
#define OCLOGERR 2
#define OCLOGDBG 3

/**************************************************/

#ifdef __cplusplus
extern "C" {
#endif

extern int oc_dumpnode(OClink conn, OCobject root0);

/**************************************************/
/* Link management */

extern OCerror oc_open(const char* url, OClink*);
extern OCerror oc_close(OClink);

/**************************************************/
/* Root management */
/* Fetch and parse a given class of DXD the server specified
   at open time, and using a specified set of constraints
   and flags.
   Return the root node of the parsed tree of objects.
*/
extern OCerror oc_fetchf(OClink,
                        const char* constraints,
                        OCdxd,
                        OCflags,
                        OCobject* rootp);


/*
  Equivalent to oc_fetchf with zero flag parameter
*/
extern OCerror oc_fetch(OClink,
                        const char* constraints,
                        OCdxd,
                        OCobject* rootp);

/* Release/reclaim the tree of objects associated with a given root */
extern OCerror oc_root_free(OClink, OCobject root);

/* Return the # of  OCobjects associated with a tree with specified root */
extern unsigned int oc_inq_nobjects(OClink, OCobject root);

/* Return all the OCobjects associated with a tree with specified root */
extern OCobject* oc_inq_objects(OClink, OCobject root);

/* Return the text of the DDS or DAS as received from the server */
extern const char* oc_inq_text(OClink, OCobject root);

/**************************************************/
/* Object Management */

/* Any of the pointers may be NULL in the following procedure call;
  If the object is of type Dataset, then return # of global attributes
  If the object is of type Attribute, then return the # of values in nattrp.
  The caller must free the resulting name string.
*/
extern OCerror oc_inq_object(OClink, OCobject,
                  char** namep,
                  OCtype* typep,
                  OCtype* primitivetypep, /* if objecttype == OC_Primitive */
                  OCobject* parentp,
                  unsigned int* rankp,
                  unsigned int* nsubnodesp,
                  unsigned int* nattrp);

/* Also define some more individual accessors */

extern OCerror oc_inq_name(OClink,OCobject,char**);
extern OCerror oc_inq_class(OClink,OCobject,OCtype*);
extern OCerror oc_inq_type(OClink,OCobject,OCtype*); /*alias for oc_inq_class*/
extern OCerror oc_inq_primtype(OClink,OCobject,OCtype*);
extern OCerror oc_inq_nsubnodes(OClink,OCobject,unsigned int*);
extern OCerror oc_inq_rank(OClink,OCobject,unsigned int*);
extern OCerror oc_inq_nattr(OClink,OCobject,unsigned int*);
extern OCerror oc_inq_root(OClink,OCobject,OCobject*);
extern OCerror oc_inq_container(OClink,OCobject,OCobject*);

/* Return the subnode objects, if any, associated with a given object.
Caller must free the returned subnodes memory.
*/
extern OCerror oc_inq_subnodes(OClink,OCobject,OCobject** subnodes);

/* Return the i'th subnode object, if any, associated with a given object */
/* If there is none such, then return OC_EINVAL */
extern OCerror oc_inq_ith(OClink,OCobject, unsigned int, OCobject*);

/* Return the dimension objects, if any, associated with a given object */
/* Caller must free returned vector for dimids */
/* If there are no dimensions (i.e. rank == 0), then return NULL */
extern OCerror oc_inq_dimset(OClink,OCobject, OCobject** dimids);

/* Return the i'th dim object, if any, associated with a given object */
/* If there is no such dim, then return OC_EINVAL */
extern OCerror oc_inq_ithdim(OClink,OCobject, unsigned int, OCobject*);

/* Return the size and name associated with a given dimension object
   as defined in the DDS
*/
extern OCerror oc_inq_dim(OClink,OCobject,ocindex_t*,char**);

/* Attribute Management */

/* Added: 11/2/2009 DMH:
   Provide access to DDS node attributes
   in the form of the original underlying
   DAS string.
   One specifies the DDS root to get the global attributes.
   Caller must free returned strings.
*/

extern OCerror oc_inq_attrstrings(OClink,OCobject, unsigned int i,
                           char** name, OCtype* octype,
                           unsigned int* nvalues,char*** stringvalues);

/* Obtain the attributes associated with a given DDS OCobject.
   One specifies the DDS root to get the global attributes
   This code takes the DAS strings and does a default
   conversion to binary values.
*/
extern OCerror oc_inq_attr(OClink,OCobject, unsigned int i,
                           char** name,OCtype* octype,
                           unsigned int* nvalues,void** values);

/* Convenience function to simplify reclaiming the allocated attribute
   value memory
*/
extern void oc_attr_reclaim(OCtype, unsigned int nvalues, void* values);

/* Access ith value string of a DAS object.
   OCtype of the object is assumed to be OC_Attribute.
   Note that this is  different than the above inq_attr
   and inq_attrstrings, which work on DDS
   objects. Note also that the return value is always a string.
   Caller must free returned string.
*/

extern OCerror oc_inq_dasattr_nvalues(OClink, OCobject,
                        unsigned int* nvaluesp);

extern OCerror oc_inq_dasattr(OClink,OCobject, unsigned int,
                              OCtype* primtypep, char** valuep);

/**************************************************/
/* Data management */

/*
These procedures allow for the location and extraction
of data from the data packet part of a DATADDS.
See ocuserman.html for detailed description.
*/

typedef OCobject OCdata;

/* Obtain the OCdata object that references the
   whole data from a DATADDS fetch request specified
   by the root object. This does not access the server.
*/
extern OCerror oc_data_root(OClink, OCobject root, OCdata);

/* Create an empty OCdata object */
extern OCdata oc_data_new(OClink);

/* Reclaim a no longer needed OCdata object */
extern OCerror oc_data_free(OClink, OCdata);

/* Given an OCdata object, set the nested subnode OCdata object
   to refer to the data associated with the i'th element of
   the parent data object. NOTE: if the i'th element is not
   present then this function will return OC_ENODATA.
   See the user's manual for details on mapping multi-
   dimensional arrays to single indices.
*/
extern OCerror oc_data_ith(OClink,
                                OCdata parentdata,
                                ocindex_t index,
                                OCdata subdata);

/* Return the actual data values associated with the specified OCdata.
   The OCdata is assumed to be referencing either a scalar
   primitive value or a (1d) array of primitive values.
   If scalar, then index must be 0 and count must be 1.
*/
extern OCerror oc_data_get(OClink,OCdata,
                         void* memory, size_t memsize,
                         ocindex_t index, ocindex_t count);

/* Return the OCdata's current index */
extern OCerror oc_data_index(OClink,OCdata, ocindex_t*);

/* Return the mode associated the specified OCdata object */
extern OCerror oc_data_mode(OClink,OCdata, OCmode*);

/* Return the OCobject associated the specified OCdata object */
extern OCerror oc_data_object(OClink,OCdata, OCobject*);

/* Compute the the count associated with the specified OCdata
   instance. Note: this is potentially computationally costly
   when computing # records.
*/
extern OCerror oc_data_count(OClink, OCdata, ocindex_t*);

/**************************************************/
/* Misc. OCtype-related functions */

/* Return size of the given type (Primitive only) */
extern size_t oc_typesize(OCtype);

/* Return a canonical printable string describing a given type:
   e.g. Byte, Int16, etc.
*/
extern const char* oc_typetostring(OCtype);

/* Given a value of a primitive OC type, provide a canonical
   string representing that value
*/
extern OCerror oc_typeprint(OCtype, char* buf, size_t bufsize, void* value);

/**************************************************/
/* Logging */

extern void oc_loginit(void);
extern void oc_setlogging(int onoff); /* 1=>start logging 0=>stop */
extern void oc_logopen(const char* logfilename);
extern void oc_logclose(void);

extern void oc_logtext(int tag, const char* text);

extern void oc_log(int tag, const char* fmt, ...);

/**************************************************/
/* Miscellaneous */

/* Convert an OCerror to a human readable string */
extern const char* oc_errstring(int err);

/* Get client parameters from the URL
   DO NOT free the result
*/
extern const char* oc_clientparam_get(OClink, const char* param);

extern OCerror oc_clientparam_delete(OClink, const char* param);
extern OCerror oc_clientparam_insert(OClink, const char* param, const char* value);
extern OCerror oc_clientparam_replace(OClink, const char* param, const char* value);

/**************************************************/
/* Merging operations */

/* Merge a specified DAS into a specified DDS or DATADDS */
extern OCerror oc_attach_das(OClink, OCobject dasroot, OCobject ddsroot);

/**************************************************/
/* Debugging */
extern OCerror oc_dd(OClink,OCobject,int level);
extern OCerror oc_ddnode(OClink,OCobject);

/* When a server error is detected, then it is possible
   to get the server error info using this procedure */
extern OCerror oc_svcerrordata(OClink link, char** codep,
                               char** msgp, long* httpp);



/**************************************************/
/* Experimental */

/* New 10/31/2009: return raw information about a datadds
*/

extern OCerror oc_raw_xdrsize(OClink, OCobject, size_t*);

/* Resend a url as a head request to check the Last-Modified time */
extern OCerror oc_update_lastmodified_data(OClink);

/* Get last known modification time; -1 => data unknown */
extern long oc_get_lastmodified_data(OClink);

extern OCerror oc_ping(const char* url);

/**************************************************/

#endif /*OCINTERNAL_H*/

#ifdef __cplusplus
}
#endif

#endif /*OC_H*/