OC Updated for version 2.0
|
00001 /* Copyright 2009, UCAR/Unidata and OPeNDAP, Inc. 00002 See the COPYRIGHT dap for more information. */ 00003 00004 /* 00005 OC External Interface 00006 Created: 4/4/2009 00007 Last Revised: 6/7/2012 00008 Version: 2.0 00009 */ 00010 00011 #ifndef OC_H 00012 #define OC_H 00013 00014 #include <stdlib.h> 00015 #include <stdio.h> 00016 00027 #define OC_MAX_DIMENSIONS 1024 00028 00032 typedef enum OCdxd { 00033 OCDDS=1, 00034 OCDAS=2, 00035 OCDATADDS=3 00036 } OCdxd; 00037 00041 #define OCDATA OCDATADDS 00042 00047 typedef int OCflags; 00052 #define OCONDISK 1 00053 /**************************************************/ 00054 /* OCtype */ 00055 00062 typedef enum OCtype { 00063 /* Atomic Types */ 00064 /* OC_Ubyte, OC_Char, OC_Int64 and OC_UInt64 are defined for future extension*/ 00065 OC_NAT=0, 00066 OC_Char=1, 00067 OC_Byte=2, 00068 OC_UByte=3, 00069 OC_Int16=4, 00070 OC_UInt16=5, 00071 OC_Int32=6, 00072 OC_UInt32=7, 00073 OC_Int64=8, 00074 OC_UInt64=9, 00075 OC_Float32=10, 00076 OC_Float64=11, 00077 OC_String=12, 00078 OC_URL=13, 00079 00080 /* Non-Atomic Types */ 00081 OC_Atomic=100, 00082 OC_Dataset=101, 00083 OC_Sequence=102, 00084 OC_Grid=103, 00085 OC_Structure=104, 00086 OC_Dimension=105, 00087 OC_Attribute=106, 00088 OC_Attributeset=107, 00089 } OCtype; 00090 00097 typedef enum OCerror { 00098 OC_NOERR=0, 00099 OC_EBADID=-1, 00100 OC_ECHAR=-2, 00101 OC_EDIMSIZE=-3, 00102 OC_EEDGE=-4, 00103 OC_EINVAL=-5, 00104 OC_EINVALCOORDS=-6, 00105 OC_ENOMEM=-7, 00106 OC_ENOTVAR=-8, 00107 OC_EPERM=-9, 00108 OC_ESTRIDE=-10, 00109 OC_EDAP=-11, 00110 OC_EXDR=-12, 00111 OC_ECURL=-13, 00112 OC_EBADURL=-14, 00113 OC_EBADVAR=-15, 00114 OC_EOPEN=-16, 00115 OC_EIO=-17, 00116 OC_ENODATA=-18, 00117 OC_EDAPSVC=-19, 00118 OC_ENAMEINUSE=-20, 00119 OC_EDAS=-21, 00120 OC_EDDS=-22, 00121 OC_EDATADDS=-23, 00122 OC_ERCFILE=-24, 00123 OC_ENOFILE=-25, 00124 OC_EINDEX=-26, 00125 OC_EBADTYPE=-27, 00126 OC_ESCALAR=-28, 00127 } OCerror; 00128 00132 #define OCLOGNOTE 0 00133 00136 #define OCLOGWARN 1 00137 00140 #define OCLOGERR 2 00141 00144 #define OCLOGDBG 3 00145 00146 /**************************************************/ 00147 /* Define the opaque types */ 00148 00152 typedef void* OCobject; 00153 00164 typedef OCobject OCddsnode; 00165 00166 /* Data data type */ 00172 typedef OCobject OCdatanode; 00173 00181 typedef OCobject OClink; 00182 00185 /**************************************************/ 00186 /* External API */ 00187 00188 #ifdef __cplusplus 00189 extern "C" { 00190 #endif 00191 00192 /**************************************************/ 00193 /* Link management */ 00194 00195 extern OCerror oc_open(const char* url, OClink*); 00196 extern OCerror oc_close(OClink); 00197 00198 /**************************************************/ 00199 /* Tree Management */ 00200 00201 extern OCerror oc_fetch(OClink, 00202 const char* constraints, 00203 OCdxd, 00204 OCflags, 00205 OCddsnode*); 00206 00207 extern OCerror oc_root_free(OClink, OCddsnode root); 00208 extern const char* oc_tree_text(OClink, OCddsnode root); 00209 00210 /**************************************************/ 00211 /* Node Management */ 00212 00213 extern OCerror oc_dds_properties(OClink, OCddsnode, 00214 char** namep, 00215 OCtype* typep, 00216 OCtype* atomictypep, /* if octype == OC_Atomic */ 00217 OCddsnode* containerp, /* NULL if octype == OC_Dataset */ 00218 size_t* rankp, /* 0 if scalar */ 00219 size_t* nsubnodesp, 00220 size_t* nattrp); 00221 00222 /* Define some individual accessors for convenience */ 00223 00224 extern OCerror oc_dds_name(OClink,OCddsnode,char**); 00225 extern OCerror oc_dds_class(OClink,OCddsnode,OCtype*); 00226 extern OCerror oc_dds_atomictype(OClink,OCddsnode,OCtype*); 00227 extern OCerror oc_dds_nsubnodes(OClink,OCddsnode,size_t*); 00228 extern OCerror oc_dds_rank(OClink,OCddsnode,size_t*); 00229 extern OCerror oc_dds_attr_count(OClink,OCddsnode,size_t*); 00230 extern OCerror oc_dds_root(OClink,OCddsnode,OCddsnode*); 00231 extern OCerror oc_dds_container(OClink,OCddsnode,OCddsnode*); 00232 00233 /* Aliases */ 00234 #define oc_dds_octype oc_dds_class 00235 #define oc_dds_type oc_dds_class 00236 00237 /* Get the i'th field of the given (container) node; return OC_EINDEX 00238 if there is no such node; return OC_EBADTYPE if node is not 00239 a container 00240 */ 00241 extern OCerror oc_dds_ithfield(OClink, OCddsnode, size_t index, OCddsnode* dimids); 00242 00243 /* Return the dimension nodes, if any, associated with a given DDS node */ 00244 /* Caller must allocate and free the vector for dimids */ 00245 /* If the node is scalar, then return OC_ESCALAR. */ 00246 extern OCerror oc_dds_dimensions(OClink, OCddsnode, OCddsnode* dimids); 00247 00248 /* Return the i'th dimension node, if any, associated with a given object */ 00249 /* If there is no such dimension, then return OC_EINVAL */ 00250 extern OCerror oc_dds_ithdimension(OClink,OCddsnode, size_t, OCddsnode*); 00251 00252 /* Return the size and name associated with a given dimension object 00253 as defined in the DDS 00254 */ 00255 extern OCerror oc_dimension_properties(OClink,OCddsnode,size_t*,char**); 00256 00257 /* For convenience, return only the dimension sizes */ 00258 extern OCerror oc_dds_dimensionsizes(OClink,OCddsnode,size_t* dimsizes); 00259 00260 /* Attribute Management */ 00261 00262 /* Obtain the attributes associated with a given DDS OCddsnode. 00263 One specifies the DDS root to get the global attributes 00264 The actual attribute strings are returned and the user 00265 must do any required conversion based on the octype. 00266 The strings vector must be allocated and freed by caller, 00267 The contents of the strings vector must also be reclaimed 00268 using oc_attr_reclaim(see below). 00269 Standard practice is to call twice, once with the strings 00270 argument == NULL so we get the number of values, 00271 then the second time with an allocated char** vector. 00272 00273 */ 00274 extern OCerror oc_dds_attr(OClink,OCddsnode, size_t i, 00275 char** name, OCtype* octype, 00276 size_t* nvalues, char** strings); 00277 00278 00279 /* Access ith value string of a DAS OC_Attribute object. 00280 OCddsnode of the object is assumed to be OC_Attribute. 00281 Note that this is different than the above inq_attr that work on DDS 00282 nodes. 00283 Note also that the return value is always a string. 00284 Caller must free returned string. 00285 */ 00286 00287 extern OCerror oc_das_attr_count(OClink, OCddsnode, size_t* countp); 00288 00289 extern OCerror oc_das_attr(OClink,OCddsnode, size_t, OCtype*, char**); 00290 00291 /**************************************************/ 00292 /* Free up a ddsnode that is no longer being used */ 00293 extern OCerror oc_dds_free(OClink, OCddsnode); 00294 00295 /**************************************************/ 00296 /* Data Procedures */ 00297 00298 /* Get the root data of datadds */ 00299 extern OCerror oc_data_getroot(OClink, OCddsnode treeroot, OCdatanode* rootp); 00300 00301 /* Return an data for the i'th field of the specified container data */ 00302 extern OCerror oc_data_ithfield(OClink, OCdatanode container, size_t index, 00303 OCdatanode* fieldp); 00304 00305 /* Return the grid array data for the specified grid data */ 00306 extern OCerror oc_data_gridarray(OClink, OCdatanode grid, OCdatanode* arrayp); 00307 00308 /* Return the i'th grid map data for the specified grid data. 00309 Map indices start at zero. 00310 */ 00311 extern OCerror oc_data_gridmap(OClink, OCdatanode grid, size_t index, OCdatanode* mapp); 00312 00313 /* Return the data of the container for the specified data. 00314 If it does not exist, then return OCNULL. 00315 */ 00316 extern OCerror oc_data_container(OClink, OCdatanode data, OCdatanode* containerp); 00317 00318 /* Return the data of the root for the specified data. */ 00319 extern OCerror oc_data_root(OClink, OCdatanode data, OCdatanode* rootp); 00320 00321 /* Return the data of a dimensioned Structure corresponding 00322 to the element specified by the indices. 00323 */ 00324 extern OCerror oc_data_ithelement(OClink, OCdatanode data, size_t* indices, OCdatanode* elementp); 00325 00326 /* Return the i'th record data of a Sequence data. */ 00327 extern OCerror oc_data_ithrecord(OClink, OCdatanode data, size_t index, OCdatanode* recordp); 00328 00329 /* Free up an data that is no longer being used */ 00330 extern OCerror oc_data_free(OClink, OCdatanode data); 00331 00332 /* Count the records associated with a sequence */ 00333 extern OCerror oc_data_recordcount(OClink, OCdatanode, size_t*); 00334 00335 /* Return the actual data values associated with the specified leaf data. 00336 The OCdatanode is assumed to be referencing a leaf node that is 00337 either a atomic valued scalar or array. 00338 If scalar, then index and count are ignored. 00339 Caller is responsible for allocating memory(of proper size) 00340 and free'ing it. 00341 */ 00342 extern OCerror oc_data_read(OClink, OCdatanode, size_t*, size_t*, size_t, void*); 00343 00344 /* Return the indices for this datas; Assumes the data 00345 was obtained using oc_data_ithelement or oc_data_ithrecord; 00346 if not, then an error is returned. 00347 */ 00348 extern OCerror oc_data_position(OClink, OCdatanode data, size_t* indices); 00349 00350 /* Return the template dds node for an data */ 00351 extern OCerror oc_data_ddsnode(OClink, OCdatanode data, OCddsnode*); 00352 00353 /* Return the octype of the data (convenience) */ 00354 extern OCerror oc_data_octype(OClink, OCdatanode data, OCtype*); 00355 00356 /* Return 1 if the specified data has a valid index, 0 otherwise. 00357 Valid index means it was created using 00358 oc_data_ithelement or oc_data_ithrecord. 00359 */ 00360 extern int oc_data_indexed(OClink link, OCdatanode datanode); 00361 00362 /* Return 1 if the specified data has a valid index, 0 otherwise. 00363 Valid index means it was created using 00364 oc_data_ithelement or oc_data_ithrecord. 00365 */ 00366 extern int oc_data_indexed(OClink, OCdatanode); 00367 00368 /* Return 1 if the specified data can be indexed 00369 Indexable means the data is pointing to 00370 an indexed structure or to a sequence. 00371 */ 00372 extern int oc_data_indexable(OClink, OCdatanode); 00373 00374 /**************************************************/ 00375 /* Misc. OCtype-related functions */ 00376 00377 /* Return size of the given type(Atomic only) */ 00378 extern size_t oc_typesize(OCtype); 00379 00380 /* Return a canonical printable string describing a given type: 00381 e.g. Byte, Int16, etc. 00382 */ 00383 extern const char* oc_typetostring(OCtype); 00384 00385 /* Given a value of a atomic OC type, provide a canonical 00386 string representing that value; mostly for debugging. 00387 */ 00388 extern OCerror oc_typeprint(OCtype, void* value, size_t bufsize, char* buf); 00389 00390 /**************************************************/ 00391 /* Logging */ 00392 00393 extern void oc_loginit(void); 00394 extern int oc_setlogging(int onoff); /* 1=>start logging 0=>stop */ 00395 extern int oc_logopen(const char* logfilename); 00396 extern void oc_logclose(void); 00397 00398 extern void oc_log(int tag, const char* fmt, ...); 00399 00400 extern void oc_logtext(int tag, const char* text); 00401 00402 /**************************************************/ 00403 /* Miscellaneous */ 00404 00405 /* Reclaim the strings within a string vector, but not the vector itself. 00406 This is useful for reclaiming the result of oc_data_read 00407 or oc_dds_attr when the type is OC_String or OC_URL. 00408 Note that only the strings are reclaimed, the string vector 00409 is not reclaimed because it was presumably allocated by the client. 00410 */ 00411 extern void oc_reclaim_strings(size_t n, char** svec); 00412 00413 /* Convert an OCerror to a human readable string */ 00414 extern const char* oc_errstring(OCerror err); 00415 00416 /* Get client parameters from the URL 00417 DO NOT free the result 00418 */ 00419 extern const char* oc_clientparam_get(OClink, const char* param); 00420 00421 /**************************************************/ 00422 /* Merging operations */ 00423 00424 /* Merge a specified DAS into a specified DDS or DATADDS */ 00425 extern OCerror oc_merge_das(OClink, OCddsnode dasroot, OCddsnode ddsroot); 00426 00427 /**************************************************/ 00428 /* Debugging */ 00429 00430 /* When a server error is detected, then it is possible 00431 to get the server error info using this procedure */ 00432 extern OCerror oc_svcerrordata(OClink link, char** codep, 00433 char** msgp, long* httpp); 00434 00435 /**************************************************/ 00436 /* Experimental */ 00437 00438 /* Resend a url as a head request to check the Last-Modified time */ 00439 extern OCerror oc_update_lastmodified_data(OClink); 00440 00441 /* Get last known modification time; -1 => data unknown */ 00442 extern long oc_get_lastmodified_data(OClink); 00443 00444 #ifdef __cplusplus 00445 } 00446 #endif 00447 00448 #endif /*OC_H*/