Parser for Doom UMAPINFO data. More...

Typedefs
typedef struct doom_umi1_i_data *	doom_umi1_handle
	Handle type for opaque UMAPINFO object. More...

typedef struct doom_umi1_i_ts_state *	doom_umi1_ts_state
	Handle type for opaque thread-safe state object. More...

Functions
void	doom_umi1_register_mmanager (void (ext_realloc)(void , size_t), void(ext_free)(void *))
	Register optional external memory manager. More...

int	doom_umi1_create (doom_umi1_handle handle, const unsigned char data, size_t length, int verbose)
	Create opaque UMAPINFO object. More...

void	doom_umi1_destroy (doom_umi1_handle *handle)
	Destroy opaque UMAPINFO object. More...

int	doom_umi1_ts_state_create (doom_umi1_ts_state *state, doom_umi1_handle handle)
	Initialize opaque thread-safe state object. More...

void	doom_umi1_ts_state_destroy (doom_umi1_ts_state *state)
	Destroy opaque thread-safe state object. More...

int	doom_umi1_ts_map_count (doom_umi1_ts_state state, size_t *count)
	Get number of maps in UMAPINFO data. More...

int	doom_umi1_ts_map_search (doom_umi1_ts_state state, unsigned int episode, unsigned int map)
	Search for toplevel map block in UMAPINFO data. More...

int	doom_umi1_ts_map_next (doom_umi1_ts_state state)
	Select next toplevel map block in UMAPINFO data. More...

int	doom_umi1_ts_map_read (doom_umi1_ts_state state, unsigned int episode, unsigned int map)
	Read episode and map number of currently selected map. More...

int	doom_umi1_ts_key_count (doom_umi1_ts_state state, size_t *count)
	Get number of keys in map block in UMAPINFO data. More...

int	doom_umi1_ts_key_next (doom_umi1_ts_state state)
	Select next key of selected map block in UMAPINFO data. More...

int	doom_umi1_ts_key_read (doom_umi1_ts_state state, const char *keyword, size_t keyid)
	Read keyword of currently selected key. More...

int	doom_umi1_ts_value_count (doom_umi1_ts_state state, size_t *count)
	Get number of values of selected key from map block in UMAPINFO data. More...

int	doom_umi1_ts_value_next (doom_umi1_ts_state state)
	Select next value of selected key from map block in UMAPINFO data. More...

int	doom_umi1_ts_value_type (doom_umi1_ts_state state, int *type)
	Select next value of selected key from map block in UMAPINFO data. More...

int	doom_umi1_ts_value_read_number (doom_umi1_ts_state state, unsigned int *number)
	Read number from currently selected value. More...

int	doom_umi1_ts_value_read_thing (doom_umi1_ts_state state, const char *thing, size_t thingid)
	Read thing from currently selected value. More...

int	doom_umi1_ts_value_read_qstring (doom_umi1_ts_state state, size_t length, const unsigned char *qstring)
	Read quoted string from currently selected value. More...

Fatal error return values
Fatal error code values are always negative. The meaning of the error code values may differ between major API versions. Always use the symbolic names to checks.
#define	DOOM_UMI1_ERROR_INTERNAL -1
	Internal error (bug)

#define	DOOM_UMI1_ERROR_INVALID -2
	Invalid argument(s)

#define	DOOM_UMI1_ERROR_MEMORY -3
	Memory allocation failed.

#define	DOOM_UMI1_ERROR_NOTFOUND -4
	Selected object not found.

Info (nonfatal error) return values
Info code values are always positive. The meaning of the info code values may differ between major API versions. Always use the symbolic names for checks.
#define	DOOM_UMI1_INFO_SYNTAX 1
	Syntax error(s) detected. The imported data may be incomplete.

Value types
The meaning of the type code values may differ between major API versions. Always use the symbolic names for checks.
#define	DOOM_UMI1_TYPE_INVALID 0
	Reserved for internal use.

#define	DOOM_UMI1_TYPE_CLEAR 1
	Clear flag ('clear')

#define	DOOM_UMI1_TYPE_BOOL 2
	Boolean value ('false'/'true')

#define	DOOM_UMI1_TYPE_NUMBER 3
	Unsigned number.

#define	DOOM_UMI1_TYPE_QSTRING 4
	Quoted string.

#define	DOOM_UMI1_TYPE_THING 5
	Thing type.

Key identifiers
The meaning of the key code values may differ between major API versions. Always use the symbolic names for checks.
#define	DOOM_UMI1_KEY_AUTHOR 0U
	Key "author".

#define	DOOM_UMI1_KEY_LABEL 1U
	Key "label".

#define	DOOM_UMI1_KEY_LEVELNAME 2U
	Key "levelname".

#define	DOOM_UMI1_KEY_LEVELPIC 3U
	Key "levelpic".

#define	DOOM_UMI1_KEY_NEXT 4U
	Key "next".

#define	DOOM_UMI1_KEY_NEXTSECRET 5U
	Key "nextsecret".

#define	DOOM_UMI1_KEY_SKYTEXTURE 6U
	Key "skytexture".

#define	DOOM_UMI1_KEY_MUSIC 7U
	Key "music".

#define	DOOM_UMI1_KEY_EXITPIC 8U
	Key "exitpic".

#define	DOOM_UMI1_KEY_ENTERPIC 9U
	Key "enterpic".

#define	DOOM_UMI1_KEY_PARTIME 10U
	Key "partime".

#define	DOOM_UMI1_KEY_ENDGAME 11U
	Key "endgame".

#define	DOOM_UMI1_KEY_ENDPIC 12U
	Key "endpic".

#define	DOOM_UMI1_KEY_ENDBUNNY 13U
	Key "endbunny".

#define	DOOM_UMI1_KEY_ENDCAST 14U
	Key "endcast".

#define	DOOM_UMI1_KEY_NOINTERMISSION 15U
	Key "nointermission".

#define	DOOM_UMI1_KEY_INTERTEXT 16U
	Key "intertext".

#define	DOOM_UMI1_KEY_INTERTEXTSECRET 17U
	Key "intertextsecret".

#define	DOOM_UMI1_KEY_INTERBACKDROP 18U
	Key "interbackdrop".

#define	DOOM_UMI1_KEY_INTERMUSIC 19U
	Key "intermusic".

#define	DOOM_UMI1_KEY_EPISODE 20U
	Key "episode".

#define	DOOM_UMI1_KEY_BOSSACTION 21U
	Key "bossaction".

Detailed Description

Parser for Doom UMAPINFO data.

This library occupies the namespaces with "doom_umi1_" and "DOOM_UMI1_" prefix.
The namespaces with "doom_umi1_i_" and "DOOM_UMI1_I_" prefix is reserved for internal, use never use it outside of the library (the shared library may not even export such symbols).

Typedef Documentation

◆ doom_umi1_handle

typedef struct doom_umi1_i_data* doom_umi1_handle

Handle type for opaque UMAPINFO object.

Handle for dynamically allocated UMAPINFO object.
Assign NULL to initialize the handle before an object exists.

Use doom_umi1_create() to create and initialize an object.

◆ doom_umi1_ts_state

typedef struct doom_umi1_i_ts_state* doom_umi1_ts_state

Handle type for opaque thread-safe state object.

Handle for dynamically allocated state object.
Assign NULL to initialize the handle before an object exists.

Use doom_umi1_ts_state_create() to create and initialize an object.

Function Documentation

◆ doom_umi1_create()

int doom_umi1_create	(	doom_umi1_handle *	handle,
		const unsigned char *	data,
		size_t	length,
		int	verbose
	)

Create opaque UMAPINFO object.

Parameters

[out]	handle	Pointer to UMAPINFO handle
[in]	data	Pointer to data from UMAPINFO lump
[in]	length	Size of UMAPINFO data
[in]	verbose	Print verbose processing information to stderr

This function executes the parser and copies required information into the object.
The data pointed to by data is allowed to become invalid after return.
Zero length UMAPINFO data is accepted.

Attention: On success the caller is responsible to destroy the opaque UMAPINFO object with doom_umi1_destroy() .

Note: Verbose mode can be enabled with value 1 for verbose .
Verbose mode prints debug information to stderr.

Returns

0 on success
Positive value on success with non-fatal error (check with DOOM_UMI1_INFO )
Negative value on error (check with DOOM_UMI1_ERROR )

◆ doom_umi1_destroy()

void doom_umi1_destroy ( doom_umi1_handle * handle )

Destroy opaque UMAPINFO object.

Parameters

[in,out] handle Pointer to UMAPINFO handle

Note: If handle is NULL , or points to NULL , this function executes as NOP.

◆ doom_umi1_register_mmanager()

void doom_umi1_register_mmanager	(	void ()(void *, size_t)	ext_realloc,
		void()(void )	ext_free
	)

Register optional external memory manager.

Parameters

[in]	ext_realloc	Pointer to memory reallocation function
[in]	ext_free	Pointer to memory free function

Replacement functions for ext_realloc and ext_free must work as defined by C90.
If this function is not executed, the default memory management with realloc() and free() is used.

Attention: All objects must be used with the same memory manager setup for their whole lifetime.

Note: The semantics for the case that realloc() is called with a new size of zero differ between the C and POSIX standards and are ambiguous.
This library will never call realloc() or ext_realloc with a new size of zero.

◆ doom_umi1_ts_key_count()

int doom_umi1_ts_key_count	(	doom_umi1_ts_state	state,
		size_t *	count
	)

Get number of keys in map block in UMAPINFO data.

Parameters

[in]	state	State handle
[out]	count	Pointer to number of keys

Note: On success, if number of keys is nonzero, the first key is selected.
On error, the current key selection is not changed.

Use doom_umi1_ts_key_next() to select the next key.

Returns

0 on success (location pointed to by count was updated)
Negative value on error (check with DOOM_UMI1_ERROR )

◆ doom_umi1_ts_key_next()

int doom_umi1_ts_key_next ( doom_umi1_ts_state state )

Select next key of selected map block in UMAPINFO data.

Parameters

[in] state State handle

Note: On error, the current key selection is not changed.

Returns

0 on success (key was found and selected)
Negative value on error (check with DOOM_UMI1_ERROR )

◆ doom_umi1_ts_key_read()

int doom_umi1_ts_key_read	(	doom_umi1_ts_state	state,
		const char **	keyword,
		size_t *	keyid
	)

Read keyword of currently selected key.

Parameters

[in]	state	State handle
[out]	keyword	Pointer to keyword string (`NUL` terminated)
[out]	keyid	Pointer to keyword ID

The value stored at the location pointed to by keyword points to static memory of the library.
It stays valid even after the state and data objects are destroyed.

The value stored at the location pointed to by keyid is intended to be resolved with DOOM_UMI1_KEY .

Note: It is allowed to pass NULL for keyword and/or keyid , if the caller has no need for the corresponding information.

Returns

0 on success (locations pointed to by keyword and keyid were updated)
Negative value on error (check with DOOM_UMI1_ERROR )

◆ doom_umi1_ts_map_count()

int doom_umi1_ts_map_count	(	doom_umi1_ts_state	state,
		size_t *	count
	)

Get number of maps in UMAPINFO data.

Parameters

[in]	state	State handle
[out]	count	Pointer to number of maps

Note: On success, if number of maps is nonzero, the first map is selected.
On error, the current map selection is not changed.

Use doom_umi1_ts_map_next() to select the next map.

Returns

0 on success (location pointed to by count was updated)
Negative value on error (check with DOOM_UMI1_ERROR )

◆ doom_umi1_ts_map_next()

int doom_umi1_ts_map_next ( doom_umi1_ts_state state )

Select next toplevel map block in UMAPINFO data.

Parameters

[in] state State handle

If no map is currently selected, this function returns error.

Note: On error, the current map selection is not changed.

Returns

0 on success (map was found and selected)
Negative value on error (check with DOOM_UMI1_ERROR )

◆ doom_umi1_ts_map_read()

int doom_umi1_ts_map_read	(	doom_umi1_ts_state	state,
		unsigned int *	episode,
		unsigned int *	map
	)

Read episode and map number of currently selected map.

Parameters

[in]	state	State handle
[out]	episode	Pointer to episode number
[out]	map	Pointer to map number

Returns

0 on success (locations pointed to by episode and map were updated)
Negative value on error (check with DOOM_UMI1_ERROR )

◆ doom_umi1_ts_map_search()

int doom_umi1_ts_map_search	(	doom_umi1_ts_state	state,
		unsigned int	episode,
		unsigned int	map
	)

Search for toplevel map block in UMAPINFO data.

Parameters

[in]	state	State handle
[in]	episode	Episode number
[in]	map	Map number

To search for a Doom 2 map, set episode to zero.

If multiple toplevel blocks are present for the same map, the last one is selected.

Note: On error, the current map selection is not changed.

Returns

0 on success (location pointed to by map was updated)
Negative value on error (check with DOOM_UMI1_ERROR )

◆ doom_umi1_ts_state_create()

int doom_umi1_ts_state_create	(	doom_umi1_ts_state *	state,
		doom_umi1_handle	handle
	)

Initialize opaque thread-safe state object.

Parameters

[out]	state	Pointer to state handle
[in]	handle	UMAPINFO handle

Attention: On success the caller is responsible to destroy the opaque thread-safe state object with doom_umi1_ts_state_destroy() .

Returns

0 on success
Negative value on error (check with DOOM_UMI1_ERROR )

◆ doom_umi1_ts_state_destroy()

void doom_umi1_ts_state_destroy ( doom_umi1_ts_state * state )

Destroy opaque thread-safe state object.

Parameters

[in,out] state Pointer to state handle

Note: If state is NULL , or points to NULL , this function executes as NOP.

◆ doom_umi1_ts_value_count()

int doom_umi1_ts_value_count	(	doom_umi1_ts_state	state,
		size_t *	count
	)

Get number of values of selected key from map block in UMAPINFO data.

Parameters

[in]	state	State handle
[out]	count	Pointer to number of values

Note: On success the first value is selected.
On error, the current value selection is not changed.

Use doom_umi1_ts_value_next() to select the next value.

Returns

0 on success (location pointed to by count was updated)
Negative value on error (check with DOOM_UMI1_ERROR )

◆ doom_umi1_ts_value_next()

int doom_umi1_ts_value_next ( doom_umi1_ts_state state )

Select next value of selected key from map block in UMAPINFO data.

Parameters

[in] state State handle

Note: On error, the current value selection is not changed.

Returns

0 on success (value was found and selected)
Negative value on error (check with DOOM_UMI1_ERROR )

◆ doom_umi1_ts_value_read_number()

int doom_umi1_ts_value_read_number	(	doom_umi1_ts_state	state,
		unsigned int *	number
	)

Read number from currently selected value.

Parameters

[in]	state	State handle
[out]	number	Pointer to numeric value

Attention: Usable for value types DOOM_UMI1_TYPE_BOOL and DOOM_UMI1_TYPE_NUMBER .

For type DOOM_UMI1_TYPE_BOOL the numbers 0 for false and 1 for true are returned.

Returns

0 on success (location pointed to by number was updated)
Negative value on error (check with DOOM_UMI1_ERROR )

◆ doom_umi1_ts_value_read_qstring()

int doom_umi1_ts_value_read_qstring	(	doom_umi1_ts_state	state,
		size_t *	length,
		const unsigned char **	qstring
	)

Read quoted string from currently selected value.

Parameters

[in]	state	State handle
[out]	length	Length without delimiting double quotes
[out]	qstring	Pointer to first octet inside of quoted string

Attention: Usable only for value type DOOM_UMI1_TYPE_QSTRING.; This library supports arbitrary octets in quoted strings (except double quotes, because they are used as delimiters).
The caller is responsible to postprocess the result for a specific encoding and/or NUL-termination.

The value returned in qstring points to memory of the data object.
The data stays valid after the state object is destroyed.
The caller must create a copy before the data object is destroyed.

Returns

0 on success (locations pointed to by length and qstring were updated)
Negative value on error (check with DOOM_UMI1_ERROR )

◆ doom_umi1_ts_value_read_thing()

int doom_umi1_ts_value_read_thing	(	doom_umi1_ts_state	state,
		const char **	thing,
		size_t *	thingid
	)

Read thing from currently selected value.

Parameters

[in]	state	State handle
[out]	thing	Pointer to thing string (`NUL` terminated)
[out]	thingid	Pointer to thing ID

Attention: Usable only for value type DOOM_UMI1_TYPE_THING.

The value returned in thing points to static memory of the library.
It stays valid even after the state and data objects are destroyed.

The value stored at the location pointed to by thingid is the index for the thing table in the UMNAPINFO specification.

Note: It is allowed to pass NULL for thing and/or thingid , if the caller has no need for the corresponding information.

Returns

0 on success (locations pointed to by thing and thingid were updated)
Negative value on error (check with DOOM_UMI1_ERROR )

◆ doom_umi1_ts_value_type()

int doom_umi1_ts_value_type	(	doom_umi1_ts_state	state,
		int *	type
	)

Select next value of selected key from map block in UMAPINFO data.

Parameters

[in]	state	State handle
[out]	type	Pointer to value type code (DOOM_UMI1_TYPE )

Use doom_umi1_ts_value_read_number() function to get a numerical value for types DOOM_UMI1_TYPE_BOOL and DOOM_UMI1_TYPE_NUMBER .

Use doom_umi1_ts_value_read_thing() function to get a name string for type DOOM_UMI1_TYPE_THING .

Use doom_umi1_ts_value_read_qstring() function to get the content for type DOOM_UMI1_TYPE_QSTRING .

Returns

0 on success (location pointed to by type was updated)
Negative value on error (check with DOOM_UMI1_ERROR )

Typedefs

Functions

Fatal error return values

Info (nonfatal error) return values

Value types

Key identifiers

Detailed Description

Typedef Documentation

◆ doom_umi1_handle

◆ doom_umi1_ts_state

Function Documentation

◆ doom_umi1_create()

◆ doom_umi1_destroy()

◆ doom_umi1_register_mmanager()

◆ doom_umi1_ts_key_count()

◆ doom_umi1_ts_key_next()

◆ doom_umi1_ts_key_read()

◆ doom_umi1_ts_map_count()

◆ doom_umi1_ts_map_next()

◆ doom_umi1_ts_map_read()

◆ doom_umi1_ts_map_search()

◆ doom_umi1_ts_state_create()

◆ doom_umi1_ts_state_destroy()

◆ doom_umi1_ts_value_count()

◆ doom_umi1_ts_value_next()

◆ doom_umi1_ts_value_read_number()

◆ doom_umi1_ts_value_read_qstring()

◆ doom_umi1_ts_value_read_thing()

◆ doom_umi1_ts_value_type()