H5_file_attribs.h 11.2 KB
Newer Older
1
/*
gsell's avatar
gsell committed
2
  Copyright (c) 2006-2016, The Regents of the University of California,
3 4 5 6 7 8 9
  through Lawrence Berkeley National Laboratory (subject to receipt of any
  required approvals from the U.S. Dept. of Energy) and the Paul Scherrer
  Institut (Switzerland).  All rights reserved.

  License: see file COPYING in top level of source distribution.
*/

10 11
#ifndef __H5_FILE_ATTRIBS_H
#define __H5_FILE_ATTRIBS_H
12 13 14

#include <string.h>

15
#include "h5core/h5_log.h"
gsell's avatar
gsell committed
16
#include "h5core/h5_file_attribs.h"
17

gsell's avatar
gsell committed
18 19 20 21
#ifdef __cplusplus
extern "C" {
#endif

22
/*
gsell's avatar
gsell committed
23 24 25 26 27 28 29
   !   _                   _          
   !  (_)_ __   __ _ _   _(_)_ __ ___ 
   !  | | '_ \ / _` | | | | | '__/ _ \
   !  | | | | | (_| | |_| | | | |  __/
   !  |_|_| |_|\__, |\__,_|_|_|  \___|
   !              |_|
   !
30
*/
31

32
/**
gsell's avatar
gsell committed
33 34
   \addtogroup h5_file_attribs
   @{
35 36
*/

gsell's avatar
gsell committed
37
/**
gsell's avatar
gsell committed
38
  Query the number of attributes attached to the file's root ("/").
39

gsell's avatar
gsell committed
40 41
  \return   Number of attributes
  \return   \c H5_FAILURE on error
42 43

  \see H5GetFileAttribInfo()
44 45 46
*/
static inline h5_int64_t
H5GetNumFileAttribs (
gsell's avatar
gsell committed
47
	const h5_file_t f              ///< [in]  file handle
48 49 50 51 52 53 54
	) {
	H5_API_ENTER (h5_int64_t,
                      "f=%p",
                      (h5_file_p)f);
	H5_API_RETURN (h5_get_num_file_attribs (f));
}

gsell's avatar
gsell committed
55
/**
56
  Gets the name, type and number of elements of the file attribute
57
  given by its index.
58 59

  This function can be used to retrieve all attributes bound to the
gsell's avatar
gsell committed
60 61 62
  file \c f by looping from \c 0 to the number of attribute minus one.
  The number of attributes attached to the file \c f can be queried by
  calling \ref H5GetNumFileAttribs().
63

gsell's avatar
gsell committed
64 65
  \return   \c H5_SUCCESS on success
  \return   \c H5_FAILURE on error
66 67
*/
static inline h5_err_t
68
H5GetFileAttribInfo (
gsell's avatar
gsell committed
69
	const h5_file_t f,		///< [in]  file handle
70
	const h5_size_t idx,    	///< [in]  index of attribute to query
gsell's avatar
C-API:  
gsell committed
71
	char* const attrib_name,	///< [out] name of attribute
gsell's avatar
gsell committed
72
	const h5_size_t len_attrib_name,///< [in]  size of buffer \c attrib_name
gsell's avatar
C-API:  
gsell committed
73 74
	h5_int64_t* const attrib_type,  ///< [out] type of value
	h5_size_t* const nelems         ///< [out] number of elements
75 76
	) {
	H5_API_ENTER (h5_err_t,
77
		      "f=%p, "
gsell's avatar
gsell committed
78 79
		      "idx=%llu, attrib_name=%p, len_attrib_name=%llu, "
		      "attrib_type=%p, nelems=%p",
80 81
                      (h5_file_p)f,
                      (long long unsigned)idx,
gsell's avatar
gsell committed
82 83 84
                      attrib_name,
                      (long long unsigned)len_attrib_name,
                      attrib_type,
85
                      nelems);
gsell's avatar
C-API:  
gsell committed
86 87 88 89 90 91 92
	H5_API_RETURN (
		h5_get_file_attrib_info_by_idx (
			f,
			idx,
			attrib_name, len_attrib_name,
			attrib_type,
			nelems));
93 94
}

gsell's avatar
C-API:  
gsell committed
95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117
static inline h5_err_t
H5GetFileAttribName (
	const h5_file_t f,		///< [in]  file handle
	const h5_size_t idx,    	///< [in]  index of attribute to query
	char* const attrib_name,	///< [out] name of attribute
	const h5_size_t len_attrib_name ///< [in]  size of buffer \c attrib_name
	) {
	H5_API_ENTER (h5_err_t,
		      "f=%p, "
		      "idx=%llu, attrib_name=%p, len_attrib_name=%llu, ",
                      (h5_file_p)f,
                      (long long unsigned)idx,
                      attrib_name,
                      (long long unsigned)len_attrib_name);
	H5_API_RETURN (
		h5_get_file_attrib_info_by_idx (
			f,
			idx,
			attrib_name, len_attrib_name,
			NULL,
			NULL));
}

gsell's avatar
gsell committed
118
/**
gsell's avatar
gsell committed
119
   Determines whether a file attribute with a given name exists.
120

gsell's avatar
gsell committed
121 122 123 124
   \return      true (value \c >0) if atrribute exists
   \return      false (\c 0) if attribute does not exist
   \return      \c H5_FAILURE on error
 */
125
static inline h5_err_t
gsell's avatar
gsell committed
126 127 128
H5HasFileAttrib (
	const h5_file_t f,		///< [in]  file handle
	const char* const attrib_name	///< [in]  name of attribute to query
129 130
	) {
	H5_API_ENTER (h5_err_t,
gsell's avatar
gsell committed
131 132 133 134 135 136 137 138
		      "f=%p, "
		      "attrib_name=%p",
		      (h5_file_p)f,
		      attrib_name);
	H5_API_RETURN (
		h5_has_file_attrib (
			f,
			attrib_name));
139 140
}

gsell's avatar
gsell committed
141
/**
gsell's avatar
gsell committed
142 143
  Get the type and number of elements of the file attribute
  given by its name.
144

gsell's avatar
gsell committed
145 146
  \return   \c H5_SUCCESS on success
  \return   \c H5_FAILURE on error
147 148
*/
static inline h5_err_t
gsell's avatar
gsell committed
149 150 151
H5GetFileAttribInfoByName (
	const h5_file_t f,		///< [in]  file handle.
	const char* const attrib_name,  ///< [in]  name of attribute.
gsell's avatar
C-API:  
gsell committed
152 153
	h5_int64_t* const attrib_type,  ///< [out] type of value..
	h5_size_t* const nelems         ///< [out] number of elements.
154 155
	) {
	H5_API_ENTER (h5_err_t,
gsell's avatar
gsell committed
156 157 158 159 160 161
		      "f=%p, "
		      "attrib_name=%s, "
		      "attrib_type=%p, nelems=%p",
                      (h5_file_p)f,
                      attrib_name,
                      attrib_type, nelems);
gsell's avatar
C-API:  
gsell committed
162 163 164 165 166
	H5_API_RETURN (
		h5_get_file_attrib_info_by_name (
			f,
			attrib_name,
			attrib_type, nelems));
167 168
}

gsell's avatar
gsell committed
169 170 171 172 173 174 175
/*
  !                 _ _       
  !  __      ___ __(_) |_ ___ 
  !  \ \ /\ / / '__| | __/ _ \
  !   \ V  V /| |  | | ||  __/
  !    \_/\_/ |_|  |_|\__\___|
*/
176

gsell's avatar
gsell committed
177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234
/**
   \fn h5_err_t H5WriteFileAttribString (
	const h5_file_t f,
	const char* attrib_name,
	const char* buffer
	)

   \fn  h5_err_t H5WriteFileAttribFloat64 (
	const h5_file_t f,
	const char* attrib_name,
	const h5_float64_t* buffer,
	const h5_size_t nelems
	)

   \fn h5_err_t H5WriteFileAttribFloat32 (
	const h5_file_t f,
	const char* attrib_name,
	const h5_float32_t* buffer,
	const h5_size_t nelems
	)

   \fn h5_err_t H5WriteFileAttribInt64 (
	const h5_file_t f,
	const char* attrib_name,
	const h5_int64_t* buffer,
	const h5_size_t nelems
	)

   \fn h5_err_t H5WriteFileAttribInt32 (
	const h5_file_t f,
	const char* attrib_name,
	const h5_int32_t* buffer,
	const h5_size_t nelems
	)

  Attach an attribute to a file given by a handle.

  The type of the attribute can be

  - a C string (\c char*)
  - an array of 64bit floating point numbers (\c h5_float64_t)
  - an array of 32bit floating point numbers (\c h5_float32_t)
  - an array of 64bit integers (\c h5_int64_t)
  - an array of 32bit integers (\c h5_int32_t)

  \param f		[in]  file handle
  \param attrib_name	[in]  the attribute name
  \param buffer		[in]  data to be written
  \param nelems		[in]  number of elements to be written

  \return \c H5_SUCCESS on success
  \return \c H5_FAILURE on error

  \see H5ReadFileAttribString()
  \see H5ReadFileAttribFloat64()
  \see H5ReadFileAttribFloat32()
  \see H5ReadFileAttribInt64()
  \see H5ReadFileAttribInt32()
235 236
*/
static inline h5_err_t
gsell's avatar
gsell committed
237 238
H5WriteFileAttribString (
	const h5_file_t f,
gsell's avatar
C-API:  
gsell committed
239 240
	const char* const attrib_name,
	const char* const buffer
241 242
	) {
	H5_API_ENTER (h5_err_t,
gsell's avatar
gsell committed
243 244
                      "f=%p, attrib_name='%s', buffer='%s'",
                      (h5_file_p)f, attrib_name, buffer);
gsell's avatar
C-API:  
gsell committed
245 246 247 248 249 250 251
	H5_API_RETURN (
		h5_write_file_attrib (
			f,
			attrib_name,
			H5_STRING_T,
			buffer,
			strlen(buffer) + 1 ));
252 253 254
}

static inline h5_err_t
gsell's avatar
gsell committed
255
H5WriteFileAttribFloat64 (
gsell's avatar
C-API:  
gsell committed
256 257 258 259
	const h5_file_t f,
	const char* const attrib_name,
	const h5_float64_t* const buffers,
	const h5_size_t nelems
260 261
	) {
	H5_API_ENTER (h5_err_t,
gsell's avatar
gsell committed
262 263
                      "f=%p, attrib_name='%s', buffers=%p, nelems=%llu",
		      (h5_file_p)f, attrib_name, buffers, (long long unsigned)nelems);
gsell's avatar
C-API:  
gsell committed
264 265 266 267 268 269 270
	H5_API_RETURN (
		h5_write_file_attrib (
			f,
			attrib_name,
			H5_FLOAT64_T,
			buffers,
			nelems));
271 272 273
}

static inline h5_err_t
274
H5WriteFileAttribFloat32 (
gsell's avatar
gsell committed
275
	const h5_file_t f,
gsell's avatar
C-API:  
gsell committed
276 277
	const char* const attrib_name,
	const h5_float32_t* const buffers,
gsell's avatar
gsell committed
278
	const h5_size_t nelems
279 280
	) {
	H5_API_ENTER (h5_err_t,
gsell's avatar
gsell committed
281 282
                      "f=%p, attrib_name='%s', buffers=%p, nelems=%llu",
		      (h5_file_p)f, attrib_name, buffers, (long long unsigned)nelems);
gsell's avatar
C-API:  
gsell committed
283 284 285 286 287 288 289
	H5_API_RETURN (
		h5_write_file_attrib (
			f,
			attrib_name,
			H5_FLOAT32_T,
			buffers,
			nelems ));
290 291 292
}

static inline h5_err_t
gsell's avatar
gsell committed
293 294
H5WriteFileAttribInt64 (
	const h5_file_t f,
gsell's avatar
C-API:  
gsell committed
295 296
	const char* const attrib_name,
	const h5_int64_t* const buffers,
gsell's avatar
gsell committed
297
	const h5_size_t nelems	
298 299
	) {
	H5_API_ENTER (h5_err_t,
gsell's avatar
gsell committed
300 301
                      "f=%p, attrib_name='%s', buffers=%p, nelems=%llu",
		      (h5_file_p)f, attrib_name, buffers, (long long unsigned)nelems);
gsell's avatar
C-API:  
gsell committed
302 303 304 305 306 307 308
	H5_API_RETURN (
		h5_write_file_attrib (
			f,
			attrib_name,
			H5_INT64_T,
			buffers,
			nelems));
309 310 311
}

static inline h5_err_t
gsell's avatar
gsell committed
312 313
H5WriteFileAttribInt32 (
	const h5_file_t f,
gsell's avatar
C-API:  
gsell committed
314 315
	const char* const attrib_name,
	const h5_int32_t* const buffers,
gsell's avatar
gsell committed
316
	const h5_size_t nelems
317 318
	) {
	H5_API_ENTER (h5_err_t,
gsell's avatar
gsell committed
319 320
                      "f=%p, attrib_name='%s', buffers=%p, nelems=%llu",
		      (h5_file_p)f, attrib_name, buffers, (long long unsigned)nelems);
gsell's avatar
C-API:  
gsell committed
321 322 323 324 325 326 327
	H5_API_RETURN (
		h5_write_file_attrib (
			f,
			attrib_name,
			H5_INT32_T,
			buffers,
			nelems));
328 329
}

gsell's avatar
gsell committed
330 331 332 333 334 335 336 337
/*
  !                      _ 
  !   _ __ ___  __ _  __| |
  !  | '__/ _ \/ _` |/ _` |
  !  | | |  __/ (_| | (_| |
  !  |_|  \___|\__,_|\__,_|
 */

gsell's avatar
gsell committed
338
/**
gsell's avatar
gsell committed
339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378
   \fn h5_err_t H5ReadFileAttribString (
	const h5_file_t f,
	const char* attrib_name,
	char* buffer
	)

   \fn h5_err_t H5ReadFileAttribFloat64 (
	const h5_file_t f,
	const char* attrib_name,
	h5_float64_t* buffer
	)

   \fn h5_err_t H5ReadFileAttribFloat32 (
	const h5_file_t f,
	const char* attrib_name,
	h5_float32_t* buffer
	)

   \fn h5_err_t H5ReadFileAttribInt64 (
	const h5_file_t f,
	const char* attrib_name,
	h5_int64_t* buffer
	)

   \fn h5_err_t H5ReadFileAttribInt32 (
	const h5_file_t f,
	const char* attrib_name,
	h5_int32_t* buffer
	)

  Read attribute attached to a file given by a handle.

  \note Make sure that the size of the buffer is large enough!

  \param f		[in]  file handle
  \param attrib_name	[in]  attribute name
  \param buffer		[out] buffer for data to be read

  \return \c H5_SUCCESS on success
  \return \c H5_FAILURE on error
379

gsell's avatar
gsell committed
380 381 382 383 384 385 386 387 388
  \see H5GetFileAttribInfo()
  \see H5GetFileAttribInfoByName()
  \see H5WriteFileAttribString()
  \see H5WriteFileAttribFloat64()
  \see H5WriteFileAttribFloat32()
  \see H5WriteFileAttribInt64()
  \see H5WriteFileAttribInt32()

 */
389
static inline h5_err_t
gsell's avatar
gsell committed
390 391
H5ReadFileAttribString (
	const h5_file_t f,
gsell's avatar
C-API:  
gsell committed
392 393
	const char* const attrib_name,
	char* const buffer
394 395
	) {
	H5_API_ENTER (h5_err_t,
gsell's avatar
gsell committed
396
                      "f=%p, attrib_name='%s', buffer='%p'",
gsell's avatar
gsell committed
397
                      (h5_file_p)f, attrib_name, buffer);
gsell's avatar
C-API:  
gsell committed
398 399 400 401 402 403
	H5_API_RETURN (
		h5_read_file_attrib (
			f,
			attrib_name,
			H5_STRING_T,
			(void*)buffer));
404 405
}

gsell's avatar
gsell committed
406 407 408
static inline h5_err_t
H5ReadFileAttribFloat64 (
	const h5_file_t f,
gsell's avatar
C-API:  
gsell committed
409 410
	const char* const attrib_name,
	h5_float64_t* const buffer
gsell's avatar
gsell committed
411 412 413 414
	) {
	H5_API_ENTER (h5_err_t,
		      "f=%p, attrib_name='%s', buffer=%p",
		      (h5_file_p)f, attrib_name, buffer);
gsell's avatar
C-API:  
gsell committed
415 416 417 418 419 420
	H5_API_RETURN (
		h5_read_file_attrib (
			f,
			attrib_name,
			H5_FLOAT64_T,
			(void*)buffer));
gsell's avatar
gsell committed
421
}
422 423

static inline h5_err_t
gsell's avatar
gsell committed
424 425
H5ReadFileAttribFloat32 (
	const h5_file_t f,
gsell's avatar
C-API:  
gsell committed
426 427
	const char* const attrib_name,
	h5_float32_t* const buffer
428 429
	) {
	H5_API_ENTER (h5_err_t,
gsell's avatar
gsell committed
430 431
                      "f=%p, attrib_name='%s', buffer=%p",
		      (h5_file_p)f, attrib_name, buffer);
gsell's avatar
C-API:  
gsell committed
432 433 434 435 436 437
	H5_API_RETURN (
		h5_read_file_attrib (
			f,
			attrib_name,
			H5_FLOAT32_T,
			(void*)buffer));
438 439
}

gsell's avatar
gsell committed
440 441 442
static inline h5_err_t
H5ReadFileAttribInt64 (
	const h5_file_t f,
gsell's avatar
C-API:  
gsell committed
443 444
	const char* const attrib_name,
	h5_int64_t* const buffer
gsell's avatar
gsell committed
445 446 447 448
	) {
	H5_API_ENTER (h5_err_t,
                      "f=%p, attrib_name='%s', buffer=%p",
		      (h5_file_p)f, attrib_name, buffer);
gsell's avatar
C-API:  
gsell committed
449 450 451 452 453 454
	H5_API_RETURN (
		h5_read_file_attrib (
			f,
			attrib_name,
			H5_INT64_T,
			(void*)buffer));
gsell's avatar
gsell committed
455
}
456 457

static inline h5_err_t
458
H5ReadFileAttribInt32 (
gsell's avatar
gsell committed
459
	const h5_file_t f,
gsell's avatar
C-API:  
gsell committed
460 461
	const char* const attrib_name,
	h5_int32_t* const buffer
462 463
	) {
	H5_API_ENTER (h5_err_t,
gsell's avatar
gsell committed
464 465
                      "f=%p, attrib_name='%s', buffer=%p",
                      (h5_file_p)f, attrib_name, buffer);
gsell's avatar
C-API:  
gsell committed
466 467 468 469 470 471
	H5_API_RETURN (
		h5_read_file_attrib (
			f,
			attrib_name,
			H5_INT32_T,
			(void*)buffer));
472
}
gsell's avatar
gsell committed
473
///< @}
gsell's avatar
gsell committed
474

gsell's avatar
gsell committed
475 476 477 478
#ifdef __cplusplus
}
#endif

479
#endif