grib_api: The context object

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

# The context object

## Typedefs
typedef void(* | grib_free_proc )(const grib_context *c, void *data)
| Grib free procedure, format of a procedure referenced in the context that is used to free memory.
typedef void *(* | grib_malloc_proc )(const grib_context *c, size_t length)
| Grib malloc procedure, format of a procedure referenced in the context that is used to allocate memory.
typedef void *(* | grib_realloc_proc )(const grib_context *c, void *data, size_t length)
| Grib realloc procedure, format of a procedure referenced in the context that is used to reallocate memory.
typedef void(* | grib_log_proc )(const grib_context *c, int level, const char *mesg)
| Grib loc proc, format of a procedure referenced in the context that is used to log internal messages.
typedef void(* | grib_print_proc )(const grib_context *c, void *descriptor, const char *mesg)
| Grib print proc, format of a procedure referenced in the context that is used to print external messages.
typedef size_t(* | grib_data_read_proc )(const grib_context *c, void *ptr, size_t size, void *stream)
| Grib data read proc, format of a procedure referenced in the context that is used to read from a stream in a resource.
typedef size_t(* | grib_data_write_proc )(const grib_context *c, const void *ptr, size_t size, void *stream)
| Grib data read write, format of a procedure referenced in the context that is used to write to a stream from a resource.
typedef off_t(* | grib_data_tell_proc )(const grib_context *c, void *stream)
| Grib data tell, format of a procedure referenced in the context that is used to tell the current position in a stream.
typedef off_t(* | grib_data_seek_proc )(const grib_context *c, off_t offset, int whence, void *stream)
| Grib data seek, format of a procedure referenced in the context that is used to seek the current position in a stream.
typedef int(* | grib_data_eof_proc )(const grib_context *c, void *stream)
| Grib data eof, format of a procedure referenced in the context that is used to test end of file.
## Functions
grib_context * | grib_get_context (grib_handle *h)
| Retreive the context from a handle.
grib_context * | grib_context_get_default (void)
| Get the static default context.
grib_context * | grib_context_new (grib_context *c)
| Create and allocate a new context from a parent context.
void | grib_context_delete (grib_context *c)
| Frees the cached definition files of the context.
void | grib_gts_header_on (grib_context *c)
| Set the gts header mode on.
void | grib_gts_header_off (grib_context *c)
| Set the gts header mode off.
void | grib_gribex_mode_on (grib_context *c)
| Set the gribex mode on.
void | grib_gribex_mode_off (grib_context *c)
| Set the gribex mode off.
void | grib_context_set_user_data (grib_context *c, void *udata)
| Sets user data in a context.
void * | grib_context_get_user_data (grib_context *c)
| get userData from a context
void | grib_context_set_memory_proc (grib_context *c, grib_malloc_proc griballoc, grib_free_proc gribfree, grib_realloc_proc gribrealloc)
| Sets memory procedures of the context.
void | grib_context_set_persistent_memory_proc (grib_context *c, grib_malloc_proc griballoc, grib_free_proc gribfree)
| Sets memory procedures of the context for persistent data.
void | grib_context_set_buffer_memory_proc (grib_context *c, grib_malloc_proc griballoc, grib_free_proc gribfree, grib_realloc_proc gribrealloc)
| Sets memory procedures of the context for large buffers.
void | grib_context_set_path (grib_context *c, const char *path)
| Sets the context search path for definition files.
void | grib_context_set_dump_mode (grib_context *c, int mode)
| Sets context dump mode.
void | grib_context_set_print_proc (grib_context *c, grib_print_proc printp)
| Sets the context printing procedure used for user interaction.
void | grib_context_set_logging_proc (grib_context *c, grib_log_proc logp)
| Sets the context logging procedure used for system (warning, errors, infos .
void | grib_multi_support_on (grib_context *c)
| Turn on support for multiple fields in single grib messages.
void | grib_multi_support_off (grib_context *c)
| Turn off support for multiple fields in single grib messages.

## Detailed Description

The context is a long life configuration object of the grib_api. It is used to define special allocation and free routines or to set special grib_api behaviours and variables.

## Typedef Documentation

typedef int(* grib_data_eof_proc)(const grib_context *c, void *stream)

Grib data eof, format of a procedure referenced in the context that is used to test end of file.

Parameters:

  | c | : the context where the tell will apply
  | *stream | : the stream

Returns:
  the position in the stream

typedef size_t(* grib_data_read_proc)(const grib_context *c, void *ptr, size_t size, void *stream)

Grib data read proc, format of a procedure referenced in the context that is used to read from a stream in a resource.

Parameters:

  | c | : the context where the read will apply
  | *ptr | : the resource
  | size | : size to read
  | *stream | : the stream

Returns:
  size read

typedef off_t(* grib_data_seek_proc)(const grib_context *c, off_t offset, int whence, void *stream)

Grib data seek, format of a procedure referenced in the context that is used to seek the current position in a stream.

Parameters:

  | c | : the context where the tell will apply
  | offset | : the offset to seek to
  | whence | : If whence is set to SEEK_SET, SEEK_CUR, or SEEK_END, the offset is relative to the start of the file, the current position indicator, or end-of-file, respectively.
  | *stream | : the stream

Returns:
  0 if OK, integer value on error

typedef off_t(* grib_data_tell_proc)(const grib_context *c, void *stream)

Grib data tell, format of a procedure referenced in the context that is used to tell the current position in a stream.

Parameters:

  | c | : the context where the tell will apply
  | *stream | : the stream

Returns:
  the position in the stream

typedef size_t(* grib_data_write_proc)(const grib_context *c, const void *ptr, size_t size, void *stream)

Grib data read write, format of a procedure referenced in the context that is used to write to a stream from a resource.

Parameters:

  | c | : the context where the write will apply
  | *ptr | : the resource
  | size | : size to read
  | *stream | : the stream

Returns:
  size written

typedef void(* grib_free_proc)(const grib_context *c, void *data)

Grib free procedure, format of a procedure referenced in the context that is used to free memory.

Parameters:

  | c | : the context where the memory freeing will apply
  | data | : pointer to the data to be freed must match

See also:
  grib_malloc_proc

typedef void(* grib_log_proc)(const grib_context *c, int level, const char *mesg)

Grib loc proc, format of a procedure referenced in the context that is used to log internal messages.

Parameters:

  | c | : the context where the logging will apply
  | level | : the log level, as defined in log modes
  | mesg | : the message to be logged

typedef void*(* grib_malloc_proc)(const grib_context *c, size_t length)

Grib malloc procedure, format of a procedure referenced in the context that is used to allocate memory.

Parameters:

  | c | : the context where the memory allocation will apply
  | length | : length to be allocated in number of bytes

Returns:
  a pointer to the alocated memory, NULL if no memory can be allocated must match

See also:
  grib_free_proc

typedef void(* grib_print_proc)(const grib_context *c, void *descriptor, const char *mesg)

Grib print proc, format of a procedure referenced in the context that is used to print external messages.

Parameters:

  | c | : the context where the logging will apply
  | descriptor | : the structure to be printed on, must match the implementation
  | mesg | : the message to be printed

typedef void*(* grib_realloc_proc)(const grib_context *c, void *data, size_t length)

Grib realloc procedure, format of a procedure referenced in the context that is used to reallocate memory.

Parameters:

  | c | : the context where the memory allocation will apply
  | data | : pointer to the data to be reallocated
  | length | : length to be allocated in number of bytes

Returns:
  a pointer to the alocated memory

## Function Documentation

void grib_context_delete | ( | grib_context * | c | ) |

Frees the cached definition files of the context.

Parameters:

  | c | : the context to be deleted

grib_context* grib_context_get_default | ( | void |  | ) |

Get the static default context.

Returns:
  the default context, NULL it the context is not available

void* grib_context_get_user_data | ( | grib_context * | c | ) |

get userData from a context

Parameters:

  | c | : the context from which the user data will be retreived

Returns:
  the user data referenced in the context

grib_context* grib_context_new | ( | grib_context * | c | ) |

Create and allocate a new context from a parent context.

Parameters:

  | c | : the context to be cloned, NULL for default context

Returns:
  the new and empty context, NULL if error

void grib_context_set_buffer_memory_proc | ( | grib_context * | c,
|  | grib_malloc_proc | griballoc,
|  | grib_free_proc | gribfree,
|  | grib_realloc_proc | gribrealloc |
| ) |  |  |

Sets memory procedures of the context for large buffers.

Parameters:

  | c | : the context to be modified
  | griballoc | : the memory allocation procedure to be set

See also:
  grib_malloc_proc

Parameters:

  | gribfree | : the memory freeing procedure to be set

See also:
  grib_free_proc

void grib_context_set_dump_mode | ( | grib_context * | c,
|  | int | mode |
| ) |  |  |

Sets context dump mode.

Parameters:

  | c | : the context to be modified
  | mode | : the log mode to be set

void grib_context_set_logging_proc | ( | grib_context * | c,
|  | grib_log_proc | logp |
| ) |  |  |

Sets the context logging procedure used for system (warning, errors, infos .

..) messages

Parameters:

  | c | : the context to be modified
  | logp | : the logging procedure to be set

See also:
  grib_log_proc

void grib_context_set_memory_proc | ( | grib_context * | c,
|  | grib_malloc_proc | griballoc,
|  | grib_free_proc | gribfree,
|  | grib_realloc_proc | gribrealloc |
| ) |  |  |

Sets memory procedures of the context.

Parameters:

  | c | : the context to be modified
  | griballoc | : the memory allocation procedure to be set

See also:
  grib_malloc_proc

Parameters:

  | gribfree | : the memory freeing procedure to be set

See also:
  grib_free_proc

void grib_context_set_path | ( | grib_context * | c,
|  | const char * | path |
| ) |  |  |

Sets the context search path for definition files.

Parameters:

  | c | : the context to be modified
  | path | : the search path to be set

void grib_context_set_persistent_memory_proc | ( | grib_context * | c,
|  | grib_malloc_proc | griballoc,
|  | grib_free_proc | gribfree |
| ) |  |  |

Sets memory procedures of the context for persistent data.

Parameters:

  | c | : the context to be modified
  | griballoc | : the memory allocation procedure to be set

See also:
  grib_malloc_proc

Parameters:

  | gribfree | : the memory freeing procedure to be set

See also:
  grib_free_proc

void grib_context_set_print_proc | ( | grib_context * | c,
|  | grib_print_proc | printp |
| ) |  |  |

Sets the context printing procedure used for user interaction.

Parameters:

  | c | : the context to be modified
  | printp | : the printing procedure to be set

See also:
  grib_print_proc

void grib_context_set_user_data | ( | grib_context * | c,
|  | void * | udata |
| ) |  |  |

Sets user data in a context.

Parameters:

  | c | : the context to be modified
  | udata | : the user data to set

grib_context* grib_get_context | ( | grib_handle * | h | ) |

Retreive the context from a handle.

Parameters:

  | h | : the handle used to retreive the context from

Returns:
  The handle's context, NULL it the handle is invalid

void grib_gribex_mode_off | ( | grib_context * | c | ) |

Set the gribex mode off.

Grib files won't be always compatible with gribex.

Parameters:

  | c | : the context to be deleted

void grib_gribex_mode_on | ( | grib_context * | c | ) |

Set the gribex mode on.

Grib files will be compatible with gribex.

Parameters:

  | c | : the context to be deleted

void grib_gts_header_off | ( | grib_context * | c | ) |

Set the gts header mode off.

The GTS headers will be deleted.

Parameters:

  | c | : the context to be deleted

void grib_gts_header_on | ( | grib_context * | c | ) |

Set the gts header mode on.

The GTS headers will be preserved.

Parameters:

  | c | : the context to be deleted

void grib_multi_support_off | ( | grib_context * | c | ) |

Turn off support for multiple fields in single grib messages.

Parameters:

  | c | : the context to be modified

Examples:
  multi.f90, and multi_fortran.F.

void grib_multi_support_on | ( | grib_context * | c | ) |

Turn on support for multiple fields in single grib messages.

Parameters:

  | c | : the context to be modified

Examples:
  multi.c, multi.f90, and multi_fortran.F.