Create, read and write parameter files. More...

Collaboration diagram for Parameter File Handling API:

Functions
void *	GfParmReadBuf (char *buffer)
	Read parameter set from memory buffer and return handle to parameter set.
void *	GfParmReadFile (const char *file, int mode)
	Read parameter set from file and return handle to parameter set.
int	GfParmWriteBuf (void handle, char buf, int size)
	Write a parameter set into a memory buffer.
void	GfParmSetDTD (void parmHandle, char dtd, char *header)
	Set the dtd path and header.
int	GfParmWriteFile (const char file, void parmHandle, const char *name)
	Write parameter set into file.
int	GfParmCreateDirectory (const char file, void parmHandle)
	Create directory for parameter set handle if it does not yet exist.
void	GfParmClean (void *parmHandle)
	Clean all the parameters of a parameter set.
void	GfParmReleaseHandle (void *parmHandle)
	Release given parameter set handle parmHandle.
char *	GfParmGetFileName (void *handle)
	Get the filename property of the parameter set handle.
int	GfParmCheckHandle (void ref, void tgt)
	Check the values in the parameter set tgt against the min/max/within definitions in the ref parameter set.
void *	GfParmMergeHandles (void ref, void tgt, int mode)
	Merge two parameter sets into a new private set.

Detailed Description

Create, read and write parameter files.

Function Documentation

◆ GfParmCheckHandle()

int GfParmCheckHandle	(	void *	ref,
		void *	tgt )

Check the values in the parameter set tgt against the min/max/within definitions in the ref parameter set.

Parameters

[in]	ref	reference parameter set handle for check (min/max/within)
[in]	tgt	target parameter set handle for check (values)

Returns: -1 for a detected type mismatch; otherwise 0. Numeric bound and string-constraint violations are logged but do not change the return value.

Note: The current implementation visits only attributes directly in top-level reference sections, not nested subsections. Only attributes also present in tgt are checked; missing attributes and tgt's own bounds are ignored. A return value of 0 is therefore not proof that a setup is valid.

See also: GfParmMergeHandles

Definition at line 2885 of file params.cpp.

Here is the call graph for this function:

◆ GfParmClean()

void GfParmClean ( void * parmHandle )

Clean all the parameters of a parameter set.

Removes all contained parameters in the parameter set, the parmHandle remains valid. All handles sharing the set observe the removal.

Parameters

[in,out] parmHandle parameter set handle

Definition at line 1870 of file params.cpp.

Here is the call graph for this function:

◆ GfParmCreateDirectory()

int GfParmCreateDirectory	(	const char *	file,
		void *	parmHandle )

Create directory for parameter set handle if it does not yet exist.

Parameters

[in]	file	Full filename whose parent directories should be created, or NULL to use the stored filename. The filename itself is not created.
[in]	parmHandle	Valid parameter set handle, read but not changed.

Returns: 0 if ok
1 if Error

Definition at line 1793 of file params.cpp.

Here is the call graph for this function:

◆ GfParmGetFileName()

char * GfParmGetFileName ( void * handle )

Get the filename property of the parameter set handle.

Parameters

[in] handle parameter set handle

Returns: Borrowed filename; do not modify or free it despite the char* return type. An unnamed in-memory set has an empty filename.
NULL if failed or not set

Note: The pointer returned is for immediate use, if you plan to keep the value for a long time, it is necessary to copy the string, because manipulating the handle will produce an incoherent pointer.

Definition at line 2218 of file params.cpp.

Here is the call graph for this function:

◆ GfParmMergeHandles()

void * GfParmMergeHandles	(	void *	ref,
		void *	tgt,
		int	mode )

Merge two parameter sets into a new private set.

Used to create a new parameter set from two existing ones, e.g. a car category and car. If GFPARM_MMODE_SRC mode is used, all parameters from ref will exist in the new parameter set. If GFPARM_MMODE_DST mode is used, all parameters from tgt will exist in the new parameter set. You can combine GFPARM_MMODE_SRC and GFPARM_MMODE_DST to get all parameters from both sets into the new set.

Numeric values are taken from tgt when present. If a parameter exists in both sets (ref and tgt) and has different min/max values, then the greater min value and the smaller max value is selected, so with combining parameters it is only possible to shrink the possible range. If the parameter value does not fit the new min/max range it is adjusted. This requires compatible types and overlapping bounds; the merge does not reject type conflicts or disjoint ranges. For common string attributes, tgt's value is kept only if present in ref's within list; otherwise ref's value is used. The resulting within list is the intersection. Attributes present in only one selected set are copied unchanged; empty sections and file metadata are not copied.

Parameters

[in,out]	ref	Reference handle; data is read, but the handle is released on success when RELSRC is set.
[in,out]	tgt	Target handle; data is read, but the handle is released on success when RELDST is set. Use distinct handles when releasing both.
[in]	mode	Merge flags combined with bitwise OR (\|): GFPARM_MMODE_SRC Include all attributes present in ref. GFPARM_MMODE_DST Include all attributes present in tgt. GFPARM_MMODE_RELSRC Release ref handle after the merge GFPARM_MMODE_RELDST Release tgt handle after the merge

Returns: Owned private handle, or NULL if result allocation fails. Release the result with GfParmReleaseHandle. Its filename is empty: pass an explicit filename and name to GfParmWriteFile. Inputs are not released on the early failure paths. Without SRC or DST the result is empty.

See also: GfParmCheckHandle

Definition at line 3129 of file params.cpp.

Here is the call graph for this function:

◆ GfParmReadBuf()

void * GfParmReadBuf ( char * buffer )

Read parameter set from memory buffer and return handle to parameter set.

Parameters

[in] buffer NUL-terminated XML text, parsed synchronously and not retained.

Returns: handle to the parameter set
0 if Error

Note: The result is private and has an empty filename. Release it with GfParmReleaseHandle; supply an explicit filename when writing it. This legacy function is not declared in the public tgf.h API.

See also: GfParmWriteBuf

Definition at line 1099 of file params.cpp.

Here is the call graph for this function:

◆ GfParmReadFile()

void * GfParmReadFile	(	const char *	file,
		int	mode )

Read parameter set from file and return handle to parameter set.

Parameters

[in]	file	name of the file to read
[in]	mode	opening mode is a mask of: GFPARM_RMODE_STD if the parameter set is already loaded and not private return a handle pointing to the existing parameter set (default) GFPARM_RMODE_REREAD re-read the parameters file GFPARM_RMODE_CREAT if the parameters file does not exist return a handle pointing to an empty parameter set (does not create a file on disk, this is done using GfParmWriteFile). GFPARM_RMODE_PRIVATE mark handle as private

Note: Each successful call returns a new handle to release with GfParmReleaseHandle. Non-private handles for the exact same filename share data and list cursors. REREAD clears that shared data before reading; other handles see the replacement, even if the read subsequently fails. CREAT permits an empty set on any file-open failure, not just a missing file.

Returns: handle to parameter set
0 if error

See also: GfParmWriteFile

Definition at line 1173 of file params.cpp.

Here is the call graph for this function:

◆ GfParmReleaseHandle()

void GfParmReleaseHandle ( void * parmHandle )

Release given parameter set handle parmHandle.

Releases the parameter set handle and eventally the parameter set which it refers to.

The parameter sets are internally reused and reference counted, so if the parameter set has still a reference counter greater than 0, just the reference counter is decremented, if it reaches 0, the whole parameter set is deleted from memory.

The parameter file is not written on release, write operations are done explicitely with GfParmWriteFile.

Parameters

[in,out] parmHandle Non-NULL owned handle, invalid after this call.

See also: GfParmWriteFile; GfParmReadFile

Definition at line 1963 of file params.cpp.

Here is the call graph for this function:

◆ GfParmSetDTD()

void GfParmSetDTD	(	void *	parmHandle,
		char *	dtd,
		char *	header )

Set the dtd path and header.

Parameters

[in,out]	parmHandle	Parameter set whose output metadata is changed.
[in]	dtd	DTD path to copy, or NULL to preserve the current value.
[in]	header	Header text to copy, or NULL to preserve the current value.

Definition at line 1704 of file params.cpp.

◆ GfParmWriteBuf()

int GfParmWriteBuf	(	void *	handle,
		char *	buf,
		int	size )

Write a parameter set into a memory buffer.

Parameters

[in,out]	handle	Parameter set handle; serialization state is changed.
[out]	buf	Destination buffer with at least size bytes.
[in]	size	buffer size

Returns: 0 on completion, including truncation; 1 for nonpositive size or a reported serialization error.

Note: This function does not report insufficient capacity. It writes a NUL only at buf[size-1], not necessarily immediately after the XML text. Zero-initialize a sufficiently large buffer before calling. This legacy function is not declared in the public tgf.h API.

Definition at line 1656 of file params.cpp.

Here is the call graph for this function:

◆ GfParmWriteFile()

int GfParmWriteFile	(	const char *	file,
		void *	parmHandle,
		const char *	name )

Write parameter set into file.

Parameters

[in]	file	if NULL the internally stored filename is used, if not NULL the given filename is used (it is not stored in the handle)
[in,out]	parmHandle	parameter set handle
[in]	name	if NULL the internally stored name is used, if not NULL the given name is used and stored in the handle

Returns: 0 after serialization; 1 for a missing filename, open failure or reported serialization error. Individual write/close errors are not checked.

Note: Opens the file for replacement. Parent directories must already exist; use GfParmCreateDirectory if needed.

Definition at line 1732 of file params.cpp.

Here is the call graph for this function:

Functions

Detailed Description

Function Documentation

◆ GfParmCheckHandle()

◆ GfParmClean()

◆ GfParmCreateDirectory()

◆ GfParmGetFileName()

◆ GfParmMergeHandles()

◆ GfParmReadBuf()

◆ GfParmReadFile()

◆ GfParmReleaseHandle()

◆ GfParmSetDTD()

◆ GfParmWriteBuf()

◆ GfParmWriteFile()