>
> |
-- JohnChamberlain - 11 Aug 2004
CAPI_Header_Comments <-- post comments here
/** OPeNDAP C API
John Chamberlain
13 September 2004
*/
/** OPeNDAP C API - USAGE
* The API implementation comes in two forms:
- standalone executable (ocapi or ocapi.exe)
- library (ocapi.o or ocapi.dll)
* The source code is available
* It can be operated interactively or by programmatic function call
* When executed standalone interactive_open( stdin, stdout ) is called at the outset
*************** General Methodologies ********************
* After any function call ALWAYS check the return code for an error
* In the case of an error the message will be in sError
* If SUCCESS is returned but sError is non-NULL, then it is a warning
* Return value(s) are always accessed via a handle (a pointer to a pointer)
* All non-data arrays are 1-based (indicated by "1" at end of identifier)
*************** HTTP Functionality ***********************
* To operate the library form programmatically to get data or other large binary:
- create an URL structure and populate it (or use the createURL convenience method)
- create a ConnectionParameters structure and populate it (optional)
- call connection_Open
- monitor connection.eState and do the next step in a loop
- yield to other threads
- check for a timeout (you must define your own timeout periods)
- when connection.eState == CS_Full read the buffer and set iContentPosition to 0
- when connection.eState == CS_Complete read the buffer and close the connection
* To operate the library form programmatically to get a small amount of data (ddx, dds etc):
- create an URL structure and populate it (or use the createURL convenience method)
- create a ConnectionParameters structure and populate it (optional)
- call getContent (timeouts etc handled automatically)
* If a call returns FAILURE the accumulated error will be in sError
* Connection can be closed prematurely at any time to cancel an operation
* Up to (sizeof)int connections can be maintained simultaneously (subject to OS limitations)
* File descriptor (or stdout etc) can be supplied as a logging handle to get detailed logs
* Client header can be manually specified by the user; can be viewed after open
*************** OPeNDAP Functionality ********************
* All the functions are memory protected -- if you lack the memory you will get a returned error
* To create a structure from scratch generate it yourself and call structure_Verify on it to validate
* To load a structure use one of the load methods
* All the structures are trees of nodes
* Deep copy a structure or node using the clone functions
*/
typedef enum eRESULT { FAILURE, SUCCESS };
typedef enum eCONNECTION_STATE { CS_Unitialized, CS_Initial, CS_Opening, CS_Reading, CS_Full, CS_Complete };
typedef enum eREQUEST_CLASS { RC_Raw, RC_Catalog, RC_Directory, RC_Data, RC_DDX, RC_DDS, RC_DAS, RC_Info };
typedef enum eLOG_LEVEL { LL_NoChange, LL_Brief, LL_Normal, LL_All };
typedef struct Proxy {
*char sHost;
int iPort;
};
typedef struct URL {
*char sRawURL; /** for reference only */
*char sHost;
int iPort; /** defaults to 80 */
*char sPath;
*char sQuery;
eREQUEST_CLASS eRequestClass; /** defaults to RC_Info */
*char sCanonicalURL;
};
typedef struct Buffer {
*char sContentBuffer;
long int iBufferSize;
long int iContentLength;
long int iContentPosition;
}
typedef struct ConnectionParameters { /** see configure below for defaults */
Proxy *structProxy;
URL *structURL;
int iConnectTimeout_seconds;
int iReadTimeout_seconds;
*char sProtocol;
*char sClientHeader;
long int nLoggingHandle;
}
typedef struct ConversionFormat { /** see configure below for defaults */
unsigned int ordinal;
*char sTitle;
}
typedef struct OPeNDAPConnection {
int iChannelDescriptor;
eCONNECTION_STATE eState;
*char sError;
*char sServerHeader;
*char sServerVersion;
Buffer *structContent;
};
/** Node Content Summary
* If the node content is a primitive numeric type then the node content
* pointer can be cast to that type (defined below). Otherwise, the pointer
* should be cast to the proper NodeContent type.
*/
#define DBOOLEAN int
#define FALSE 0
#define TRUE 1
#define DBYTE unsigned char
#define DINT16 short
#define DUINT16 unsigned short
#define DINT32 long
#define DUINT32 unsigned long
#define DFLOAT32 float
#define DFLOAT64 double
typedef enum eFORMATS { FORMAT_OPeNDAPBinary, FORMAT_HDF, FORMAT_NetCDF };
typedef enum eSTRUCTURE_TYPE { STRUCTURE_DataDDS, STRUCTURE_DDX, STRUCTURE_DDS, STRUCTURE_DAS };
typedef enum eNODE_TYPE {
NODE_Boolean,
NODE_Byte,
NODE_Int16,
NODE_UInt16,
NODE_Int32,
NODE_UInt32,
NODE_Float32,
NODE_Float64,
NODE_String,
NODE_Array,
NODE_Grid
};
typedef enum eATTRIBUTE_TYPE {
ATTRIBUTE_unknown,
ATTRIBUTE_alias,
ATTRIBUTE_container,
ATTRIBUTE_Boolean,
ATTRIBUTE_Byte,
ATTRIBUTE_Int16,
ATTRIBUTE_UInt16,
ATTRIBUTE_Int32,
ATTRIBUTE_UInt32,
ATTRIBUTE_Float32,
ATTRIBUTE_Float64,
ATTRIBUTE_String,
ATTRIBUTE_URL
};
typedef struct NodeContent_String {
unsigned int iLength;
*char sContent;
}
typedef struct NodeContent_Array {
unsigned int iDimensionCount1[];
unsigned int iDimensionLength1[];
unsigned int iWordSize;
*char sDimensionName1[];
*void array;
}
typedef struct NodeContent_Grid {
*void maps1[];
*NodeContent_Array values;
}
typedef struct Attribute {
eATTRIBUTE_TYPE eType;
*AttributeTable reference; /** valid if type is ATTRIBUTE_container or ATTRIBUTE_alias */
*void value; /** valid for other types, must cast to value */
}
typedef struct AttributeTable {
*char attribute_name1[];
Attribute attribute_value1[];
}
typedef struct OPeNDAPStructure {
eSTRUCTURE_TYPE eStructureType;
long int nEstimatedSize;
OPeNDAPNode *nodeRoot;
}
typedef struct OPeNDAPNode {
eNODE_TYPE eNodeType;
OPeNDAPNode *nodeSuper;
OPeNDAPNode *nodeSub;
int iSubNodeCount;
*void *nodeContent; /** see summary below */
*char sName;
*char sLongName;
long int nContentSize;
*AttributeTable attributes;
}
/*************/
/** Utility **/
/*************/
*char getVersion();
*char getConfiguration();
*char getDocumentation();
* getConversionFormats();
OPeNDAPConnection[] getConnections();
eRESULT configure(
int iConnectTimeout_seconds, /** defaults to 30, -1 = no change, 0 = infinite */
int iReadTimeout_seconds, /** defaults to 60, -1 = no change, 0 = infinite */
*char sProtocol, /** defaults to "HTTP/1.0", NULL or "" = no change */
long int iLoggingHandle, /** defaults to 0 = none, -1 = no change */
LOG_LEVEL eLogLevel /** defaults to LL_Normal */
);
void interactive_open( long int handle_in, long int handle_out );
void interactive_close( long int handle_in );
/*************************/
/** Generic HTTP Access **/
/*************************/
eRESULT createURL( *char url_string, **URL created_url, **char sError );
eRESULT connection_Open( *ConnectionParameters parameters, **OPeNDAPConnection connection, **char sError );
eRESULT connection_Open( *URL url, **OPeNDAPConnection connection, **char sError );
eRESULT connection_Read( *OPeNDAPConnection connection, **char sError );
eRESULT connection_Close( *OPeNDAPConnection connection, **char sError );
eRESULT getContent( *url, **char content, **char sError );
eRESULT getContent( *ConnectionParameters parameters, **char content, **char sError );
/************************/
/** Structure Handling **/
/************************/
eRESULT structure_Load( *URL url, OPeNDAPNode **nodeRoot, **char sError );
eRESULT structure_Load( *OPeNDAPConnection connection, OPeNDAPStructure **structure, **char sError );
eRESULT structure_Load( long int handle, OPeNDAPStructure **structure, **char sError );
eRESULT structure_Load( *Buffer structContent, OPeNDAPStructure **structure, **char sError );
eRESULT structure_Free( OPeNDAPStructure *structure, **char sError );
eRESULT structure_Clone( OPeNDAPStructure *structure, OPeNDAPStructure *new_structure, **char sError );
eRESULT structure_Verify( OPeNDAPStructure *structure, **char sError );
eRESULT node_getSize( OPeNDAPNode *node, *(long int) size, **char sError );
eRESULT node_Clone( OPeNDAPNode *node, OPeNDAPNode **new_node, **char sError );
eRESULT node_Print_ASCII( OPeNDAPNode *node, **char output, **char sError );
eRESULT node_Print_ASCII( OPeNDAPNode *node, long int handle_output, **char sError );
eRESULT node_Print_XML( OPeNDAPNode *node, **char output, **char sError );
eRESULT node_Print_XML( OPeNDAPNode *node, long int handle_output, **char sError );
eRESULT node_Convert( OPeNDAPNode *node, unsigned int eFORMAT, **void output, **char sError );
eRESULT node_Convert( OPeNDAPNode *node, unsigned int eFORMAT, long int handle_output, **char sError );
|