Loader

TODO. More...

Typedefs
typedef struct DmLoader	DmLoader
	Represents a DirectMusic Loader.
typedef enum DmLoaderOptions	DmLoaderOptions
	Configuration flags for DirectMusic Loaders.
typedef void *	DmLoaderResolverCallback(void *ctx, char const *file, size_t *len)
	A function used to look up and read in DirectMusic objects by file name.

Enumerations
enum	DmLoaderOptions { DmLoader_DOWNLOAD = 1U << 0U , DmLoader_DEFAULT = 0U }
	Configuration flags for DirectMusic Loaders. More...

Functions
DmResult	DmLoader_create (DmLoader **slf, DmLoaderOptions opt)
	Create a new DirectMusic Loader object.
DmLoader *	DmLoader_retain (DmLoader *slf)
	Add one to the reference count of a loader.
void	DmLoader_release (DmLoader *slf)
	Subtract one from the reference count of a loader.
DmResult	DmLoader_addResolver (DmLoader *slf, DmLoaderResolverCallback *resolve, void *ctx)
	Add a resolver to the loader.
DmResult	DmLoader_getSegment (DmLoader *slf, char const *name, DmSegment **segment)
	Get a segment from the loader's cache or load it by file name.

Detailed Description

TODO.

Typedef Documentation

DmLoader

typedef struct DmLoader DmLoader

Represents a DirectMusic Loader.

Definition at line 293 of file dmusic.h.

DmLoaderOptions

typedef enum DmLoaderOptions DmLoaderOptions

Configuration flags for DirectMusic Loaders.

See also

DmLoader_create

DmLoaderResolverCallback

typedef void * DmLoaderResolverCallback(void *ctx, char const *file, size_t *len)

A function used to look up and read in DirectMusic objects by file name.

When called, a function implementing this interface should look up a DirectMusic data file corresponding to the given file name and return the data contained within as a memory buffer. When the function fails to find an appropriate file, it should return NULL.

The returned memory buffer's ownership will be transferred to the loader, so it must be able to be de-allocated using free or (if set) the custom de-allocation function passed to Dm_setHeapAllocator.

Parameters

ctx[in]	An arbitrary pointer provided when calling DmLoader_addResolver.
file[in]	The name of the file to look up.
len[out]	The length of the returned memory buffer in bytes.

Returns

A memory buffer containing the file data or NULL if the lookup failed. Ownership of this buffer is transferred to the loader.

Definition at line 392 of file dmusic.h.

Enumeration Type Documentation

DmLoaderOptions

enum DmLoaderOptions

Configuration flags for DirectMusic Loaders.

See also

DmLoader_create

Enumerator
DmLoader_DOWNLOAD	Automatically download references.
DmLoader_DEFAULT	Default options for loader objects.

Definition at line 369 of file dmusic.h.

Function Documentation

DmLoader_addResolver()

DmResult DmLoader_addResolver	(	DmLoader *	slf,
		DmLoaderResolverCallback *	resolve,
		void *	ctx
	)

Add a resolver to the loader.

Resolvers are used to locate stored DirectMusic object by file name. Whenever the loader needs to look up an object, it calls all resolvers in sequential order until one returns a match. If no match is found, an error is issued and the object is not loaded.

Parameters

slf[in]	The loader to add a resolver to.
resolve[in]	The callback function used to resolve a file using the new resolver.
ctx[in]	An arbitrary pointer passed to resolve on every invocation.

Returns

DmResult_SUCCESS if the operation completed and an error code if it did not.

Return values

DmResult_INVALID_ARGUMENT	slf or resolve was NULL.
DmResult_MEMORY_EXHAUSTED	A dynamic memory allocation failed.
DmResult_MUTEX_ERROR	An error occurred while trying to lock an internal mutex.

DmLoader_create()

DmResult DmLoader_create	(	DmLoader **	slf,
		DmLoaderOptions	opt
	)

Create a new DirectMusic Loader object.

If the DmLoader_DOWNLOAD option is defined, all references for objects retrieved for the loader are automatically resolved and downloaded.

Parameters

slf[out]	A pointer to a variable in which to store the newly created loader.
opt	A bitfield containing loader configuration flags.

Returns

DmResult_SUCCESS if the operation completed and an error code if it did not.

Return values

DmResult_INVALID_ARGUMENT	slf was NULL.
DmResult_MEMORY_EXHAUSTED	A dynamic memory allocation failed.

DmLoader_getSegment()

DmResult DmLoader_getSegment	(	DmLoader *	slf,
		char const *	name,
		DmSegment **	segment
	)

Get a segment from the loader's cache or load it by file name.

Gets a segment from the loader's cache or loads the segment using the resolvers added to the loader. If the requested segment is found in neither the loader, nor by any resolver, an error is issued.

If the loader was created using the DmLoader_DOWNLOAD option, this function automatically downloads the segment by calling DmSegment_download.

Parameters

slf[in]	The loader to load a segment from.
name[in]	The file name of the segment to load.
segment[out]	A pointer to a variable in which to store the segment.

Returns

DmResult_SUCCESS if the operation completed and an error code if it did not.

Return values

DmResult_INVALID_ARGUMENT	slf, name or segment was NULL.
DmResult_MEMORY_EXHAUSTED	A dynamic memory allocation failed.
DmResult_NOT_FOUND	No segment with the given name could be found.
DmResult_MUTEX_ERROR	An error occurred while trying to lock an internal mutex.

See also

DmLoader_addResolver

DmLoader_release()

void DmLoader_release

(

DmLoader *

slf

)

Subtract one from the reference count of a loader.

If a call to this function reduces the reference count to zero, it also de-allocates the loader and releases any resources referenced by it.

Parameters

slf[in]

The loader to release.

DmLoader_retain()

DmLoader * DmLoader_retain

(

DmLoader *

slf

)

Add one to the reference count of a loader.

Parameters

slf[in]

The loader to retain.

Returns

The same loader as was given in slf or NULL if slf was NULL.