eccodes: The message handle

eccodes

- Main Page
- C Interface
- F90 Interface
- Python Interface

All Data Structures Namespaces Files Functions Groups Pages
Data Structures | Functions
The message handle

## Data Structures
struct | codes_handle
struct | codes_multi_handle

## Functions
int | codes_count_in_file (codes_context *c, FILE *f, int *n)
| Counts the messages contained in a file resource. More...
grib_handle * | codes_handle_new_from_file (grib_context *c, FILE *f, ProductKind product, int *error)
| Create a handle from a file resource. More...
grib_handle * | codes_grib_handle_new_from_file (grib_context *c, FILE *f, int *error)
| Create a GRIB handle from a file resource. More...
grib_handle * | codes_bufr_handle_new_from_file (grib_context *c, FILE *f, int *error)
| Create a BUFR handle from a file resource. More...
int | codes_write_message (codes_handle *h, const char *file, const char *mode)
| Write a coded message to a file. More...
codes_handle * | codes_handle_new_from_message (codes_context *c, const void *data, size_t data_len)
| Create a handle from a user message in memory. More...
codes_handle * | codes_grib_handle_new_from_multi_message (codes_context *c, void **data, size_t *data_len, int *error)
| Create a handle from a user message in memory. More...
codes_handle * | codes_handle_new_from_message_copy (codes_context *c, const void *data, size_t data_len)
| Create a handle from a user message. More...
codes_handle * | codes_grib_handle_new_from_samples (codes_context *c, const char *sample_name)
| Create a handle from a GRIB message contained in a samples directory. More...
codes_handle * | codes_bufr_handle_new_from_samples (codes_context *c, const char *sample_name)
| Create a handle from a BUFR message contained in a samples directory. More...
codes_handle * | codes_handle_clone (codes_handle *h)
| Clone an existing handle using the context of the original handle, The message is copied and reparsed. More...
int | codes_handle_delete (codes_handle *h)
| Frees a handle, also frees the message if it is not a user message. More...
codes_multi_handle * | codes_grib_multi_handle_new (codes_context *c)
| Create an empty multi-field GRIB handle. More...
int | codes_grib_multi_handle_append (codes_handle *h, int start_section, codes_multi_handle *mh)
| Append the sections starting with start_section of the message pointed by h at the end of the multi-field GRIB handle mh. More...
int | codes_grib_multi_handle_delete (codes_multi_handle *mh)
| Delete multi-field GRIB handle. More...
int | codes_grib_multi_handle_write (codes_multi_handle *mh, FILE *f)
| Write a multi-field GRIB handle in a file. More...

## Detailed Description

The codes_handle is the structure giving access to parsed message values by keys.

## Function Documentation

grib_handle* codes_bufr_handle_new_from_file | ( | grib_context * | c,
|  | FILE * | f,
|  | int * | error
| ) |  |

Create a BUFR handle from a file resource.

The file is read until a BUFR message is found. The message is then copied. Remember always to delete the handle when it is not needed anymore to avoid memory leaks.

Parameters

  c | : the context from which the handle will be created (NULL for default context)
  f | : the file resource
  error | : error code set if the returned handle is NULL and the end of file is not reached

Returns
  the new handle, NULL if the resource is invalid or a problem is encountered

codes_handle* codes_bufr_handle_new_from_samples | ( | codes_context * | c,
|  | const char * | sample_name
| ) |  |

Create a handle from a BUFR message contained in a samples directory.

The message is copied at the creation of the handle

Parameters

  c | : the context from which the handle will be created (NULL for default context)
  sample_name | : the name of the sample file (without the .tmpl extension)

Returns
  the new handle, NULL if the resource is invalid or a problem is encountered

int codes_count_in_file | ( | codes_context * | c,
|  | FILE * | f,
|  | int * | n
| ) |  |

Counts the messages contained in a file resource.

Parameters

  c | : the context from which the handle will be created (NULL for default context)
  f | : the file resource
  n | : the number of messages in the file

Returns
  0 if OK, integer value on error

grib_handle* codes_grib_handle_new_from_file | ( | grib_context * | c,
|  | FILE * | f,
|  | int * | error
| ) |  |

Create a GRIB handle from a file resource.

The file is read until a GRIB message is found. The message is then copied. Remember always to delete the handle when it is not needed anymore to avoid memory leaks.

Parameters

  c | : the context from which the handle will be created (NULL for default context)
  f | : the file resource
  error | : error code set if the returned handle is NULL and the end of file is not reached

Returns
  the new handle, NULL if the resource is invalid or a problem is encountered

codes_handle* codes_grib_handle_new_from_multi_message | ( | codes_context * | c,
|  | void ** | data,
|  | size_t * | data_len,
|  | int * | error
| ) |  |

Create a handle from a user message in memory.

The message will not be freed at the end. The message will be copied as soon as a modification is needed. This function works also with multi field messages.

Parameters

  c | : the context from which the handle will be created (NULL for default context)
  data | : the actual message
  data_len | : the length of the message in number of bytes
  error | : error code

Returns
  the new handle, NULL if the message is invalid or a problem is encountered

codes_handle* codes_grib_handle_new_from_samples | ( | codes_context * | c,
|  | const char * | sample_name
| ) |  |

Create a handle from a GRIB message contained in a samples directory.

The message is copied at the creation of the handle

Parameters

  c | : the context from which the handle will be created (NULL for default context)
  sample_name | : the name of the sample file (without the .tmpl extension)

Returns
  the new handle, NULL if the resource is invalid or a problem is encountered

int codes_grib_multi_handle_append | ( | codes_handle * | h,
|  | int | start_section,
|  | codes_multi_handle * | mh
| ) |  |

Append the sections starting with start_section of the message pointed by h at the end of the multi-field GRIB handle mh.

Remember always to delete the multi-handle when it is not needed any more to avoid memory leaks.

Parameters

  h | : The handle from which the sections are copied.
  start_section | : section number. Starting from this section all the sections to the end of the message will be copied.
  mh | : The multi-field handle on which the sections are appended.

Returns
  0 if OK, integer value on error

int codes_grib_multi_handle_delete | ( | codes_multi_handle * | mh | ) |

Delete multi-field GRIB handle.

Parameters

  mh | : The multi-field handle to be deleted.

Returns
  0 if OK, integer value on error

codes_multi_handle* codes_grib_multi_handle_new | ( | codes_context * | c | ) |

Create an empty multi-field GRIB handle.

Remember always to delete the multi-handle when it is not needed any more to avoid memory leaks.

Parameters

  c | : the context from which the handle will be created (NULL for default context)

int codes_grib_multi_handle_write | ( | codes_multi_handle * | mh,
|  | FILE * | f
| ) |  |

Write a multi-field GRIB handle in a file.

Remember always to delete the multi-handle when it is not needed any more to avoid memory leaks.

Parameters

  mh | : The multi-field GRIB handle to be written.
  f | : File on which the file handle is written.

Returns
  0 if OK, integer value on error

codes_handle* codes_handle_clone | ( | codes_handle * | h | ) |

Clone an existing handle using the context of the original handle, The message is copied and reparsed.

Parameters

  h | : The handle to be cloned

Returns
  the new handle, NULL if the message is invalid or a problem is encountered

int codes_handle_delete | ( | codes_handle * | h | ) |

Frees a handle, also frees the message if it is not a user message.

See Also
  codes_handle_new_from_message

Parameters

  h | : The handle to be deleted

Returns
  0 if OK, integer value on error

grib_handle* codes_handle_new_from_file | ( | grib_context * | c,
|  | FILE * | f,
|  | ProductKind | product,
|  | int * | error
| ) |  |

Create a handle from a file resource.

The file is read until a message is found. The message is then copied. Remember always to delete the handle when it is not needed anymore to avoid memory leaks.

Parameters

  c | : the context from which the handle will be created (NULL for default context)
  f | : the file resource
  product | : the kind of product e.g. PRODUCT_GRIB, PRODUCT_BUFR
  error | : error code set if the returned handle is NULL and the end of file is not reached

Returns
  the new handle, NULL if the resource is invalid or a problem is encountered

codes_handle* codes_handle_new_from_message | ( | codes_context * | c,
|  | const void * | data,
|  | size_t | data_len
| ) |  |

Create a handle from a user message in memory.

The message will not be freed at the end. The message will be copied as soon as a modification is needed.

Parameters

  c | : the context from which the handle will be created (NULL for default context)
  data | : the actual message
  data_len | : the length of the message in number of bytes

Returns
  the new handle, NULL if the message is invalid or a problem is encountered

codes_handle* codes_handle_new_from_message_copy | ( | codes_context * | c,
|  | const void * | data,
|  | size_t | data_len
| ) |  |

Create a handle from a user message.

The message is copied and will be freed with the handle

Parameters

  c | : the context from which the handle will be created (NULL for default context)
  data | : the actual message
  data_len | : the length of the message in number of bytes

Returns
  the new handle, NULL if the message is invalid or a problem is encountered

int codes_write_message | ( | codes_handle * | h,
|  | const char * | file,
|  | const char * | mode
| ) |  |

Write a coded message to a file.

Parameters

  h | : codes_handle to be written
  file | : name of the output file
  mode | : mode

Returns
  0 if OK, integer value on error