grib_api: The grib_handle

- Main Page
- Modules
- Files
- Related Pages
- Examples

# The grib_handle

## Typedefs
typedef struct grib_handle | grib_handle
typedef struct grib_multi_handle | grib_multi_handle
## Functions
int | grib_count_in_file (grib_context *c, FILE *f, int *n)
| Counts the messages contained in a file resource.
grib_handle * | grib_handle_new_from_file (grib_context *c, FILE *f, int *error)
| Create a handle from a file resource.
grib_handle * | grib_handle_new_from_message (grib_context *c, void *data, size_t data_len)
| Create a handle from a user message in memory.
grib_handle * | grib_handle_new_from_multi_message (grib_context *c, void **data, size_t *data_len, int *error)
| Create a handle from a user message in memory.
grib_handle * | grib_handle_new_from_message_copy (grib_context *c, const void *data, size_t data_len)
| Create a handle from a user message.
grib_handle * | grib_handle_new_from_template (grib_context *c, const char *res_name)
| Create a handle from a read_only template resource.
grib_handle * | grib_handle_new_from_samples (grib_context *c, const char *res_name)
| Create a handle from a message contained in a samples directory.
grib_handle * | grib_handle_clone (grib_handle *h)
| Clone an existing handle using the context of the original handle, The message is copied and reparsed.
int | grib_handle_delete (grib_handle *h)
| Frees a handle, also frees the message if it is not a user message.
grib_multi_handle * | grib_multi_handle_new (grib_context *c)
| Create an empty multi field handle.
int | grib_multi_handle_append (grib_handle *h, int start_section, grib_multi_handle *mh)
| Append the sections starting with start_section of the message pointed by h at the end of the multi field handle mh.
int | grib_multi_handle_delete (grib_multi_handle *mh)
| Delete multi field handle.
int | grib_multi_handle_write (grib_multi_handle *mh, FILE *f)
| Write a multi field handle in a file.

## Detailed Description

The grib_handle is the structure giving access to parsed grib values by keys.

## Typedef Documentation

typedef struct grib_handle grib_handle

Grib handle, structure giving access to parsed grib values by keys

Examples:
  get.c, iterator.c, keys_iterator.c, multi.c, multi_write.c, nearest.c, precision.c, print_data.c, and set.c.

typedef struct grib_multi_handle grib_multi_handle

Grib multi field handle, structure used to build multi fields messages.

Examples:
  multi_write.c.

## Function Documentation

int grib_count_in_file | ( | grib_context * | c,
|  | FILE * | f,
|  | int * | n |
| ) |  |  |

Counts the messages contained in a file resource.

Parameters:

  | c | : the context from wich 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

Examples:
  count_messages.f90.

grib_handle* grib_handle_clone | ( | grib_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 grib_handle_delete | ( | grib_handle * | h | ) |

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

See also:
  grib_handle_new_from_message

Parameters:

  | h | : The handle to be deleted

Returns:
  0 if OK, integer value on error

Examples:
  get.c, iterator.c, multi.c, multi_write.c, nearest.c, precision.c, print_data.c, and set.c.

grib_handle* grib_handle_new_from_file | ( | grib_context * | c,
|  | FILE * | f,
|  | 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 any more to avoid memory leaks.

Parameters:

  | c | : the context from wich 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

Examples:
  get.c, iterator.c, keys_iterator.c, multi.c, multi_write.c, precision.c, print_data.c, and set.c.

grib_handle* grib_handle_new_from_message | ( | grib_context * | c,
|  | 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

grib_handle* grib_handle_new_from_message_copy | ( | grib_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 wich 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

grib_handle* grib_handle_new_from_multi_message | ( | grib_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

grib_handle* grib_handle_new_from_samples | ( | grib_context * | c,
|  | const char * | res_name |
| ) |  |  |

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

The message is copied at the creation of the handle

Parameters:

  | c | : the context from wich the handle will be created (NULL for default context)
  | res_name | : the resource name

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

grib_handle* grib_handle_new_from_template | ( | grib_context * | c,
|  | const char * | res_name |
| ) |  |  |

Create a handle from a read_only template resource.

The message is copied at the creation of the handle

Parameters:

  | c | : the context from wich the handle will be created (NULL for default context)
  | res_name | : the resource name

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

int grib_multi_handle_append | ( | grib_handle * | h,
|  | int | start_section,
|  | grib_multi_handle * | mh |
| ) |  |  |

Append the sections starting with start_section of the message pointed by h at the end of the multi field 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 then 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

Examples:
  multi_write.c.

int grib_multi_handle_delete | ( | grib_multi_handle * | mh | ) |

Delete multi field handle.

Parameters:

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

Returns:
  0 if OK, integer value on error

Examples:
  multi_write.c.

grib_multi_handle* grib_multi_handle_new | ( | grib_context * | c | ) |

Create an empty multi field handle.

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

Parameters:

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

Examples:
  multi_write.c.

int grib_multi_handle_write | ( | grib_multi_handle * | mh,
|  | FILE * | f |
| ) |  |  |

Write a multi field 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 handle to be written.
  | f | : File on which the file handle is written.

Returns:
  0 if OK, integer value on error

Examples:
  multi_write.c.