mirror of
https://github.com/Unidata/netcdf-c.git
synced 2024-11-21 03:13:42 +08:00
cbb6df3232
User request to have all orphaned DAP2 attributes kept as netcdf global attributes. This is primarily a change in the oc code nplus testcase dataset changes. Result may be inconsistent with netcdf-Java output.
595 lines
18 KiB
C
595 lines
18 KiB
C
/* Copyright 2014, UCAR/Unidata and OPeNDAP, Inc.
|
|
See the COPYRIGHT dap for more information. */
|
|
|
|
/*
|
|
OC External Interface
|
|
Created: 4/4/2009
|
|
Last Revised: 12/23/2014
|
|
Version: 2.1
|
|
*/
|
|
|
|
#ifndef OC_H
|
|
#define OC_H
|
|
|
|
#include <stdlib.h>
|
|
#include <stdio.h>
|
|
#ifdef HAVE_SYS_TYPES_H
|
|
#include <sys/types.h>
|
|
#endif
|
|
|
|
/*!\file oc.h
|
|
*/
|
|
|
|
/*!\defgroup Definitions Constants, types, etc.
|
|
@{*/
|
|
|
|
/*! OC_MAX_DIMS is the maximum allowable
|
|
number of dimensions.
|
|
Ideally, it should be greater or equal to max allowed by dap or netcdf
|
|
*/
|
|
#define OC_MAX_DIMENSIONS 1024
|
|
|
|
/*!\enum OCdxd
|
|
Define the legal kinds of fetch: DAS, DDS, or DataDDS
|
|
*/
|
|
typedef enum OCdxd {
|
|
OCDDS=0,
|
|
OCDAS=1,
|
|
OCDATADDS=2
|
|
} OCdxd;
|
|
|
|
/*!\def OCDATA
|
|
Define an alias for OCDATADDS
|
|
*/
|
|
#define OCDATA OCDATADDS
|
|
|
|
/*!
|
|
\typedef OCflags
|
|
Define flags for oc_fetch.
|
|
*/
|
|
typedef int OCflags;
|
|
/*!\def OCONDISK
|
|
Cause oc_fetch to store the retrieved data on disk.
|
|
*/
|
|
|
|
#define OCONDISK 1
|
|
|
|
/**************************************************/
|
|
/* OCtype */
|
|
|
|
/*!\enum OCtype
|
|
Define the set of legal types. The set is divided
|
|
into two parts. The atomic types define
|
|
leaf nodes of the DDS. The non-atomic types
|
|
are used to tag internal nodes of the DDS tree.
|
|
*/
|
|
typedef enum OCtype {
|
|
/* Atomic Types */
|
|
/* OC_Ubyte, OC_Char, OC_Int64 and OC_UInt64 are defined for future extension*/
|
|
OC_NAT=0,
|
|
OC_Char=1,
|
|
OC_Byte=2,
|
|
OC_UByte=3,
|
|
OC_Int16=4,
|
|
OC_UInt16=5,
|
|
OC_Int32=6,
|
|
OC_UInt32=7,
|
|
OC_Int64=8,
|
|
OC_UInt64=9,
|
|
OC_Float32=10,
|
|
OC_Float64=11,
|
|
OC_String=12,
|
|
OC_URL=13,
|
|
|
|
/* Non-Atomic Types */
|
|
OC_Atomic=100,
|
|
OC_Dataset=101,
|
|
OC_Sequence=102,
|
|
OC_Grid=103,
|
|
OC_Structure=104,
|
|
OC_Dimension=105,
|
|
OC_Attribute=106,
|
|
OC_Attributeset=107,
|
|
OC_Map=108,
|
|
OC_Group=109,
|
|
} OCtype;
|
|
|
|
/*!\enum OCerror
|
|
Define the set of error return codes.
|
|
The set consists of oc errors (negative
|
|
values) plus the set of system errors, which
|
|
are positive.
|
|
*/
|
|
typedef enum OCerror {
|
|
OC_NOERR=0,
|
|
OC_EBADID=-1,
|
|
OC_ECHAR=-2,
|
|
OC_EDIMSIZE=-3,
|
|
OC_EEDGE=-4,
|
|
OC_EINVAL=-5,
|
|
OC_EINVALCOORDS=-6,
|
|
OC_ENOMEM=-7,
|
|
OC_ENOTVAR=-8,
|
|
OC_EPERM=-9,
|
|
OC_ESTRIDE=-10,
|
|
OC_EDAP=-11,
|
|
OC_EXDR=-12,
|
|
OC_ECURL=-13,
|
|
OC_EBADURL=-14,
|
|
OC_EBADVAR=-15,
|
|
OC_EOPEN=-16,
|
|
OC_EIO=-17,
|
|
OC_ENODATA=-18,
|
|
OC_EDAPSVC=-19,
|
|
OC_ENAMEINUSE=-20,
|
|
OC_EDAS=-21,
|
|
OC_EDDS=-22,
|
|
OC_EDATADDS=-23,
|
|
OC_ERCFILE=-24,
|
|
OC_ENOFILE=-25,
|
|
OC_EINDEX=-26,
|
|
OC_EBADTYPE=-27,
|
|
OC_ESCALAR=-28,
|
|
OC_EOVERRUN=-29,
|
|
OC_EAUTH=-30,
|
|
} OCerror;
|
|
|
|
/*!\def OCLOGNOTE
|
|
Tag a log entry as a note.
|
|
*/
|
|
#define OCLOGNOTE 0
|
|
/*!\def OCLOGWARN
|
|
Tag a log entry as a warning.
|
|
*/
|
|
#define OCLOGWARN 1
|
|
/*!\def OCLOGERR
|
|
Tag a log entry as an error.
|
|
*/
|
|
#define OCLOGERR 2
|
|
/*!\def OCLOGDBG
|
|
Tag a log entry as a debug note.
|
|
*/
|
|
#define OCLOGDBG 3
|
|
|
|
/**************************************************/
|
|
/* Define the opaque types */
|
|
|
|
/*!\typedef OCobject
|
|
Define a common opaque type.
|
|
*/
|
|
typedef void* OCobject;
|
|
|
|
/*!\typedef OCddsnode
|
|
The OCddsnode type provide a reference
|
|
to a component of a DAS or DDS tree:
|
|
e.g. Sequence, Grid, Dataset, etc.
|
|
These objects
|
|
are nested, so most objects reference a container object
|
|
and subnode objects. The term ddsnode is slightly misleading
|
|
since it also covers DAS nodes.
|
|
*/
|
|
|
|
typedef OCobject OCddsnode;
|
|
|
|
/*!\typedef OCdasnode
|
|
The OCdasnode is a alias for OCddsnode.
|
|
*/
|
|
|
|
typedef OCddsnode OCdasnode;
|
|
|
|
/* Data data type */
|
|
/*!\typedef OCdatanode
|
|
The OCdatanode type provide a reference
|
|
to a specific piece of data in the data
|
|
part of a Datadds.
|
|
*/
|
|
typedef OCobject OCdatanode;
|
|
|
|
/*!\typedef OClink
|
|
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.
|
|
3/24/210: Renamed from OCconnection because of confusion about
|
|
term "connection"
|
|
*/
|
|
typedef OCobject OClink;
|
|
|
|
/**@}*/
|
|
|
|
/**************************************************/
|
|
/* External API */
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/**************************************************/
|
|
/* Link management */
|
|
|
|
extern OCerror oc_open(const char* url, OClink*);
|
|
extern OCerror oc_close(OClink);
|
|
|
|
/**************************************************/
|
|
/* Tree Management */
|
|
|
|
extern OCerror oc_fetch(OClink,
|
|
const char* constraint,
|
|
OCdxd,
|
|
OCflags,
|
|
OCddsnode*);
|
|
|
|
extern OCerror oc_root_free(OClink, OCddsnode root);
|
|
extern const char* oc_tree_text(OClink, OCddsnode root);
|
|
|
|
/**************************************************/
|
|
/* Node Management */
|
|
|
|
extern OCerror oc_dds_properties(OClink, OCddsnode,
|
|
char** namep,
|
|
OCtype* typep,
|
|
OCtype* atomictypep, /* if octype == OC_Atomic */
|
|
OCddsnode* containerp, /* NULL if octype == OC_Dataset */
|
|
size_t* rankp, /* 0 if scalar */
|
|
size_t* nsubnodesp,
|
|
size_t* nattrp);
|
|
|
|
/* Define some individual accessors for convenience */
|
|
|
|
extern OCerror oc_dds_name(OClink,OCddsnode,char**);
|
|
extern OCerror oc_dds_class(OClink,OCddsnode,OCtype*);
|
|
extern OCerror oc_dds_atomictype(OClink,OCddsnode,OCtype*);
|
|
extern OCerror oc_dds_nsubnodes(OClink,OCddsnode,size_t*);
|
|
extern OCerror oc_dds_rank(OClink,OCddsnode,size_t*);
|
|
extern OCerror oc_dds_attr_count(OClink,OCddsnode,size_t*);
|
|
extern OCerror oc_dds_root(OClink,OCddsnode,OCddsnode*);
|
|
extern OCerror oc_dds_container(OClink,OCddsnode,OCddsnode*);
|
|
|
|
/* Aliases */
|
|
#define oc_dds_octype oc_dds_class
|
|
#define oc_dds_type oc_dds_class
|
|
|
|
/* Get the i'th field of the given (container) node; return OC_EINDEX
|
|
if there is no such node; return OC_EBADTYPE if node is not
|
|
a container
|
|
*/
|
|
extern OCerror oc_dds_ithfield(OClink, OCddsnode, size_t index, OCddsnode* ithfieldp);
|
|
|
|
/* Alias for oc_dds_ithfield */
|
|
extern OCerror oc_dds_ithsubnode(OClink, OCddsnode, size_t, OCddsnode*);
|
|
|
|
/* Convenience functions that are just combinations of ithfield with other functions */
|
|
|
|
/* Return the grid array dds node from the specified grid node*/
|
|
extern OCerror oc_dds_gridarray(OClink, OCddsnode grid, OCddsnode* arrayp);
|
|
|
|
/* Return the i'th grid map dds node from the specified grid dds node.
|
|
NOTE: Map indices start at ZERO.
|
|
*/
|
|
extern OCerror oc_dds_gridmap(OClink, OCddsnode grid, size_t index, OCddsnode* mapp);
|
|
|
|
/* Retrieve a dds node by name from a dds structure or dataset node.
|
|
return OC_EBADTYPE if node is not a container,
|
|
return OC_EINDEX if no field by the given name is found.
|
|
*/
|
|
extern OCerror oc_dds_fieldbyname(OClink, OCddsnode, const char* name, OCddsnode* fieldp);
|
|
|
|
|
|
/* Return the dimension nodes, if any, associated with a given DDS node */
|
|
/* Caller must allocate and free the vector for dimids */
|
|
/* If the node is scalar, then return OC_ESCALAR. */
|
|
extern OCerror oc_dds_dimensions(OClink, OCddsnode, OCddsnode* dimids);
|
|
|
|
/* Return the i'th dimension node, if any, associated with a given object */
|
|
/* If there is no such dimension, then return OC_EINVAL */
|
|
extern OCerror oc_dds_ithdimension(OClink,OCddsnode, size_t, OCddsnode*);
|
|
|
|
/* Return the size and name associated with a given dimension object
|
|
as defined in the DDS
|
|
*/
|
|
extern OCerror oc_dimension_properties(OClink,OCddsnode,size_t*,char**);
|
|
|
|
/* For convenience, return only the dimension sizes */
|
|
extern OCerror oc_dds_dimensionsizes(OClink,OCddsnode,size_t* dimsizes);
|
|
|
|
/* Attribute Management */
|
|
|
|
/* Obtain the attributes associated with a given DDS OCddsnode.
|
|
One specifies the DDS root to get the global attributes
|
|
The actual attribute strings are returned and the user
|
|
must do any required conversion based on the octype.
|
|
The strings vector must be allocated and freed by caller,
|
|
The contents of the strings vector must also be reclaimed
|
|
using oc_attr_reclaim(see below).
|
|
Standard practice is to call twice, once with the strings
|
|
argument == NULL so we get the number of values,
|
|
then the second time with an allocated char** vector.
|
|
|
|
*/
|
|
extern OCerror oc_dds_attr(OClink,OCddsnode, size_t i,
|
|
char** name, OCtype* octype,
|
|
size_t* nvalues, char** strings);
|
|
|
|
|
|
/* Access ith value string of a DAS OC_Attribute object.
|
|
OCddsnode of the object is assumed to be OC_Attribute.
|
|
Note that this is different than the above oc_dds_attr
|
|
that works on DDS nodes.
|
|
Note also that the return value is always a string.
|
|
Caller must free returned string.
|
|
*/
|
|
|
|
extern OCerror oc_das_attr_count(OClink, OCddsnode, size_t* countp);
|
|
|
|
extern OCerror oc_das_attr(OClink,OCddsnode, size_t, OCtype*, char**);
|
|
|
|
/**************************************************/
|
|
/* Free up a ddsnode that is no longer being used */
|
|
extern OCerror oc_dds_free(OClink, OCddsnode);
|
|
|
|
/**************************************************/
|
|
/* Data Procedures */
|
|
|
|
/* Given the DDS tree root, get the root data of datadds */
|
|
extern OCerror oc_dds_getdataroot(OClink, OCddsnode treeroot, OCdatanode* rootp);
|
|
|
|
/* Alias for oc_dds_getdataroot */
|
|
#define oc_data_getroot oc_dds_getdataroot
|
|
|
|
/* Return the data of the container for the specified data.
|
|
If it does not exist, then return NULL.
|
|
In effect this procedure allows one to walk up the datatree one level.
|
|
*/
|
|
extern OCerror oc_data_container(OClink, OCdatanode data, OCdatanode* containerp);
|
|
|
|
/* Return the root node of the data tree that contains the specified data node.
|
|
In effect this procedure allows one to walk to the root of the datatree
|
|
containing the specified datanode.
|
|
*/
|
|
extern OCerror oc_data_root(OClink, OCdatanode data, OCdatanode* rootp);
|
|
|
|
/*
|
|
There are multiple ways to walk down a level in a data tree
|
|
depending on what kind of node we are currently visiting.
|
|
The possibilities are:
|
|
1. current node is the data for a structure or dataset node:
|
|
=> oc_data_ithfield -- get the data node corresponding
|
|
to the ith field of the structure
|
|
2. current node is the data for a grid node:
|
|
=> oc_data_gridarray -- get the data node for the grid array
|
|
=> oc_data_gridmap -- get the data node for the ith grid map
|
|
3. current node is the data for an array of structures
|
|
=> oc_data_ithelement -- get the data node corresponding to
|
|
the i'th structure in the array
|
|
If the structure is scalar, then the indices
|
|
are ignored.
|
|
4. current node is the data for a sequence
|
|
=> oc_data_ithrecord -- get the data node corresponding to
|
|
the i'th record in the sequence
|
|
|
|
Note that the above only apply to compound objects. Once
|
|
you have the data node for an atomic types object (dimensioned
|
|
or scalar), you can read its contents using oc_data_read
|
|
or oc_data_readscalar.
|
|
*/
|
|
|
|
/* Return the data node for the i'th field of the specified container data */
|
|
extern OCerror oc_data_ithfield(OClink, OCdatanode container, size_t index,
|
|
OCdatanode* fieldp);
|
|
|
|
/* Retrieve the data node by name from a container data node */
|
|
extern OCerror oc_dat_fieldbyname(OClink, OCdatanode, const char* name, OCdatanode* fieldp);
|
|
|
|
/* Return the grid array data for the specified grid data */
|
|
extern OCerror oc_data_gridarray(OClink, OCdatanode grid, OCdatanode* arrayp);
|
|
|
|
/* Return the i'th grid map data for the specified grid data.
|
|
NOTE: Map indices start at ZERO.
|
|
*/
|
|
extern OCerror oc_data_gridmap(OClink, OCdatanode grid, size_t index, OCdatanode* mapp);
|
|
|
|
/* Return the data of a dimensioned Structure corresponding
|
|
to the element specified by the indices.
|
|
*/
|
|
extern OCerror oc_data_ithelement(OClink, OCdatanode data, size_t* indices, OCdatanode* elementp);
|
|
|
|
/* Return the i'th record data of a Sequence data. */
|
|
extern OCerror oc_data_ithrecord(OClink, OCdatanode data, size_t index, OCdatanode* recordp);
|
|
|
|
/* Free up an data that is no longer being used */
|
|
extern OCerror oc_data_free(OClink, OCdatanode data);
|
|
|
|
/* Count the records associated with a sequence */
|
|
extern OCerror oc_data_recordcount(OClink, OCdatanode, size_t*);
|
|
|
|
/* Return the actual data values associated with the specified leaf data.
|
|
The OCdatanode is assumed to be referencing a leaf node that is
|
|
either a atomic valued scalar or array.
|
|
If scalar, then index and count are ignored.
|
|
Caller is responsible for allocating memory(of proper size)
|
|
and free'ing it.
|
|
See also oc_dds_read().
|
|
*/
|
|
extern OCerror oc_data_read(OClink, OCdatanode, size_t*, size_t*, size_t, void*);
|
|
|
|
/* Like oc_data_read, but for reading a scalar.
|
|
Caller is responsible for allocating memory(of proper size)
|
|
and free'ing it.
|
|
See also oc_dds_readscalar().
|
|
*/
|
|
extern OCerror oc_data_readscalar(OClink, OCdatanode, size_t, void*);
|
|
|
|
/* Like oc_data_read, but caller provides a starting set of indices
|
|
and count of the number of elements to read.
|
|
Caller is responsible for allocating memory(of proper size)
|
|
and free'ing it.
|
|
See also oc_dds_readn().
|
|
*/
|
|
extern OCerror oc_data_readn(OClink, OCdatanode, size_t*, size_t, size_t, void*);
|
|
|
|
/* Return the indices for this datas; Assumes the data
|
|
was obtained using oc_data_ithelement or oc_data_ithrecord;
|
|
if not, then an error is returned.
|
|
*/
|
|
extern OCerror oc_data_position(OClink, OCdatanode data, size_t* indices);
|
|
|
|
/* Return the pattern dds node for an data */
|
|
extern OCerror oc_data_ddsnode(OClink, OCdatanode data, OCddsnode*);
|
|
|
|
/* Return the octype of the data (convenience) */
|
|
extern OCerror oc_data_octype(OClink, OCdatanode data, OCtype*);
|
|
|
|
/* Return 1 if the specified data has a valid index, 0 otherwise.
|
|
Valid index means it was created using
|
|
oc_data_ithelement or oc_data_ithrecord.
|
|
*/
|
|
extern int oc_data_indexed(OClink link, OCdatanode datanode);
|
|
|
|
/* Return 1 if the specified data has a valid index, 0 otherwise.
|
|
Valid index means it was created using
|
|
oc_data_ithelement or oc_data_ithrecord.
|
|
*/
|
|
extern int oc_data_indexed(OClink, OCdatanode);
|
|
|
|
/* Return 1 if the specified data can be indexed
|
|
Indexable means the data is pointing to
|
|
an indexed structure or to a sequence.
|
|
*/
|
|
extern int oc_data_indexable(OClink, OCdatanode);
|
|
|
|
/**************************************************/
|
|
/*
|
|
For top-level, atomic variables, it is possible to directly
|
|
read the associated data without having to use the oc_data_XXX
|
|
procedures. Provide special procedures to support this.
|
|
*/
|
|
|
|
/* See oc_data_read for semantics */
|
|
extern OCerror oc_dds_read(OClink, OCddsnode, size_t*, size_t*, size_t, void*);
|
|
|
|
/* See oc_data_readscalar for semantics */
|
|
extern OCerror oc_dds_readscalar(OClink, OCddsnode, size_t, void*);
|
|
|
|
/* See oc_data_readn for semantics */
|
|
extern OCerror oc_dds_readn(OClink, OCddsnode, size_t*, size_t, size_t, void*);
|
|
|
|
/**************************************************/
|
|
/* Misc. OCtype-related functions */
|
|
|
|
/* Return size of the given type(Atomic 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 atomic OC type, provide a canonical
|
|
string representing that value; mostly for debugging.
|
|
*/
|
|
extern OCerror oc_typeprint(OCtype, void* value, size_t bufsize, char* buf);
|
|
|
|
/**************************************************/
|
|
/* Logging */
|
|
|
|
extern void oc_loginit(void);
|
|
extern int oc_setlogging(int onoff); /* 1=>start logging 0=>stop */
|
|
extern int oc_logopen(const char* logfilename);
|
|
extern void oc_logclose(void);
|
|
|
|
extern void oc_log(int tag, const char* fmt, ...);
|
|
|
|
extern void oc_logtext(int tag, const char* text);
|
|
|
|
/**************************************************/
|
|
/* Miscellaneous */
|
|
|
|
/* Reclaim the strings within a string vector, but not the vector itself.
|
|
This is useful for reclaiming the result of oc_data_read
|
|
or oc_dds_attr when the type is OC_String or OC_URL.
|
|
Note that only the strings are reclaimed, the string vector
|
|
is not reclaimed because it was presumably allocated by the client.
|
|
*/
|
|
extern void oc_reclaim_strings(size_t n, char** svec);
|
|
|
|
/* Convert an OCerror to a human readable string */
|
|
extern const char* oc_errstring(OCerror err);
|
|
|
|
/* Get client parameters from the URL
|
|
DO NOT free the result
|
|
*/
|
|
extern const char* oc_clientparam_get(OClink, const char* param);
|
|
|
|
/**************************************************/
|
|
/* Merging operations */
|
|
|
|
/* Merge a specified DAS into a specified DDS or DATADDS */
|
|
extern OCerror oc_merge_das(OClink, OCddsnode dasroot, OCddsnode ddsroot);
|
|
|
|
/**************************************************/
|
|
/* Debugging */
|
|
|
|
/* When a server error is detected, then it is possible
|
|
to get DODS supplied server error info using this procedure */
|
|
extern OCerror oc_svcerrordata(OClink link, char** codep,
|
|
char** msgp, long* httpp);
|
|
|
|
/* Get the HTTP return code from the last call;
|
|
note that this may or may not be the same as returned
|
|
by oc_svcerrordata.
|
|
*/
|
|
extern int oc_httpcode(OClink);
|
|
|
|
/*
|
|
(Re-)initialize the oc library as if nothing had been called.
|
|
This is primarily for debugging of rc files.
|
|
*/
|
|
extern OCerror oc_initialize(void);
|
|
|
|
/**************************************************/
|
|
/* Curl options */
|
|
/* This is here because trial and error shows that
|
|
libcurl shows thru too much. So bow to the inevitable.
|
|
*/
|
|
|
|
/*Cause the curl library to be verbose and save error messages*/
|
|
extern OCerror oc_trace_curl(OClink link);
|
|
|
|
/* Allow specification of the rc file */
|
|
extern OCerror oc_set_rcfile(const char* filepath);
|
|
|
|
/* Allow specification of the netrc file */
|
|
extern OCerror oc_set_netrc(OClink*, const char* filepath);
|
|
|
|
/* Set arbitrary curl option */
|
|
extern OCerror oc_set_curlopt(OClink link, const char* option, void* value);
|
|
|
|
/**************************************************/
|
|
/* Experimental/Undocumented */
|
|
|
|
/* Given an arbitrary OCnode, return the connection of which it is a part */
|
|
extern OCerror oc_get_connection(OCobject ocnode, OCobject* linkp);
|
|
|
|
/* 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);
|
|
|
|
/* Test if a given url responds to a DAP protocol request */
|
|
extern OCerror oc_ping(const char* url);
|
|
|
|
/* Return the size of the in-memory or on-disk
|
|
data chunk returned by the server for a given tree.
|
|
Zero implies it is not defined.
|
|
*/
|
|
/* For some reason, the MSVC compiler doesn't like this. */
|
|
#ifndef _WIN32
|
|
extern OCerror oc_raw_xdrsize(OClink,OCddsnode,off_t*);
|
|
#endif
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif /*OC_H*/
|