Region Storage

Classes
struct	clod_region_opts

Enumerations
enum	clod_region_result { CLOD_REGION_OK = 0 , CLOD_REGION_INVALID_USAGE = 1 , CLOD_REGION_MALFORMED = 2 , CLOD_REGION_NOT_FOUND = 3 }

Functions
struct clod_region *	clod_region_open (const char *path, const struct clod_region_opts *opts)
enum clod_region_result	clod_region_read (struct clod_region *region, const int64_t *pos, uint8_t *buff, size_t buff_size, size_t *size)
enum clod_region_result	clod_region_write (struct clod_region *region, const int64_t *pos, const uint8_t *buff, size_t buff_size)
enum clod_region_result	clod_region_mtime (struct clod_region *region, const int64_t *pos, time_t *mtime)
struct clod_region_iter *	clod_region_iter_start (struct clod_region *region)
bool	clod_region_iter_next (struct clod_region_iter *iter, int64_t *pos)
void	clod_region_iter_end (struct clod_region_iter *iter)
enum clod_region_result	clod_region_close (struct clod_region *region)

Open modes
#define	CLOD_REGION_MODE_RDONLY   1
#define	CLOD_REGION_MODE_RDWR   2

Limits
#define	CLOD_REGION_PREFIX_MAX   30
#define	CLOD_REGION_EXTENSION_MAX   10
#define	CLOD_REGION_DIMENSIONS_MAX   10

Detailed Description

region.h defines the public interface libclod exposes for interacting with a gentrified and extended version of the minecraft region file format that retains compatibility with minecraft.

https://minecraft.wiki/w/Region_file_format

Thanks to ishland for his insights while brainstorming approaches to this.

Macro Definition Documentation

CLOD_REGION_MODE_RDONLY

#define CLOD_REGION_MODE_RDONLY   1

Definition at line 143 of file region.h.

CLOD_REGION_MODE_RDWR

#define CLOD_REGION_MODE_RDWR   2

Definition at line 144 of file region.h.

CLOD_REGION_PREFIX_MAX

#define CLOD_REGION_PREFIX_MAX   30

Definition at line 149 of file region.h.

CLOD_REGION_EXTENSION_MAX

#define CLOD_REGION_EXTENSION_MAX   10

Definition at line 150 of file region.h.

CLOD_REGION_DIMENSIONS_MAX

#define CLOD_REGION_DIMENSIONS_MAX   10

Definition at line 151 of file region.h.

Enumeration Type Documentation

clod_region_result

enum clod_region_result

Result of a call to a libregion library method. It's designed to allow programs to respond to error states and does not intend to represent debug information. The library currently uses stderr for debug information and user-relevant messages (i.e. permission denied). I do realise that might not be ideal for some cases, so I've tried to leave space to add support for a custom logger if such a thing becomes wanted.

Enumerator
CLOD_REGION_OK	No worries mate.
CLOD_REGION_INVALID_USAGE	Library used incorrectly - either directly or indirectly. File permissions errors, IO errors, system clock errors, virtual memory errors, memory allocation failures, invalid options, and many others all fall under this value.
CLOD_REGION_MALFORMED	Data is corrupted. Manual intervention is required. The program can delete the chunk to continue operation. Note Deleting a corrupted chunk can cause the deletion of other corrupted chunks.
CLOD_REGION_NOT_FOUND	The chunk does not exist. The program can write to the chunk to make it exist.

Definition at line 33 of file region.h.

Function Documentation

clod_region_open()

struct clod_region * clod_region_open	(	const char *	path,
		const struct clod_region_opts *	opts )

Open a directory for region storage.

Parameters

path	Path to the directory.
opts	Configuration options.

Returns

Handle to the directory and configuration, or nullptr on error.

Definition at line 8 of file region_open.c.

clod_region_read()

enum clod_region_result clod_region_read	(	struct clod_region *	region,
		const int64_t *	pos,
		uint8_t *	buff,
		size_t	buff_size,
		size_t *	size )

Read chunk data.

Parameters

[in]	Region Storage	Region handle.
[in]	pos	Chunk position.
[in]	buff	The buffer where data is written to.
[in]	buff_size	Size of dst.
[out]	size	Actual size of the chunk data.

Exceptions

CLOD_REGION_OK	On success.
CLOD_REGION_INVALID_USAGE	On invalid usage.
CLOD_REGION_MALFORMED	Chunk data is corrupted.
CLOD_REGION_NOT_FOUND	Chunk does not exist.

Definition at line 6 of file region_read.c.

clod_region_write()

enum clod_region_result clod_region_write	(	struct clod_region *	region,
		const int64_t *	pos,
		const uint8_t *	buff,
		size_t	buff_size )

Write chunk data or delete a chunk. Delete a chunk by passing a null buffer.

Parameters

[in]	Region Storage	Region handle.
[in]	pos	Chunk position.
[in]	buff	Buffer containing chunk data to write.
[in]	buff_size	Size of the chunk data to write.

Exceptions

CLOD_REGION_OK	On success.
CLOD_REGION_INVALID_USAGE	On invalid usage.
CLOD_REGION_MALFORMED	Chunk data is corrupted.

clod_region_mtime()

enum clod_region_result clod_region_mtime	(	struct clod_region *	region,
		const int64_t *	pos,
		time_t *	mtime )

Get the last modification time of the chunk.

Parameters

[in]	Region Storage	Region handle.
[in]	pos	Chunk position.
[out]	mtime	Last modification time.

Exceptions

CLOD_REGION_OK	On success.
CLOD_REGION_INVALID_USAGE	On invalid usage.
CLOD_REGION_MALFORMED	Chunk data is corrupted.
CLOD_REGION_NOT_FOUND	Chunk does not exist.

clod_region_iter_start()

struct clod_region_iter * clod_region_iter_start

(

struct clod_region *

region

)

Start iterating over chunks.

Parameters

[in]

Region Storage

Region handle.

Returns

New iterator, or nullptr on allocation failure.

clod_region_iter_next()

bool clod_region_iter_next	(	struct clod_region_iter *	iter,
		int64_t *	pos )

Get the next position when iterating over chunks. This method is thread-safe and always returns a unique position.

Parameters

[in]	iter	Iterator.
[out]	pos	Next chunk position.

Returns

True if the next position existed and was returned in pos.

clod_region_iter_end()

void clod_region_iter_end

(

struct clod_region_iter *

iter

)

Release resources associated with an iterator. This method is not thread safe.

Parameters

[in]

iter

The iterator to free.

clod_region_close()

enum clod_region_result clod_region_close

(

struct clod_region *

region

)

Release resources associated with the region handle.

Parameters

[in]

Region Storage

The handle to free.

Definition at line 31 of file region_open.c.