haiku/headers/os/drivers/atomizer.h

98 lines
3.8 KiB
C
Raw Normal View History

/*******************************************************************************
/
/ File: atomizer.h
/
/ Description: Kernel atomizer module API
/
/ Copyright 1999, Be Incorporated, All Rights Reserved.
/
*******************************************************************************/
#ifndef _ATOMIZER_MODULE_H_
#define _ATOMIZER_MODULE_H_
#include <module.h>
#ifdef __cplusplus
extern "C" {
#endif
/*
An atomizer is a software device that returns a unique token for a
null-terminated UTF8 string.
Each atomizer comprises a separate token space. The same string interned
in two different atomizers will generate two distinct tokens.
Atomizers and the tokens they generate are only guaranteed valid between
matched calls to get_module/put_module.
void * find_or_make_atomizer(const char *string)
Returns a token that identifies the named atomizer, creating a new
atomizer if the named atomizer does not exist. Pass null, a zero
length string, or the value B_SYSTEM_ATOMIZER_NAME for string will
return a pointer to the system atomizer. Returns (void *)(0)
if the atomizer could not be created (for whatever reason). A return
value of (void *)(-1) refers to the system atomizer.
status_t delete_atomizer(void *atomizer)
Delete the atomizer specified. Returns B_OK if successfull, B_ERROR
otherwise. An error return usually means that a race condition was
detected while destroying the atomizer.
void * atomize(void *atomizer, const char *string, int create)
Return the unique token for the specified string, creating a new token
if the string was not previously atomized and create is non-zero. If
atomizer is (void *)(-1), use the system atomizer (saving the step of
looking it up with find_or_make_atomizer(). Returns (const char *)(0)
if there were any errors detected: insufficient memory or a race
condition with someone deleting the atomizer.
const char * string_for_token(void *atomizer, void *atom)
Return a pointer to the string described by atom in the provided atomizer.
Returns (const char *)(0) if either the atomizer or the atom were invalid.
status_t get_next_atomizer_info(void **cookie, atomizer_info *info)
Returns info about the next atomizer in the list of atomizers by modifying
the contents of info. The pointer specified by *cookie should be set to
(void *)(0) to retrieve the first atomizer, and should not be modified
thereafter. Returns B_ERROR when there are no more atomizers.
Adding or deleting atomizers between calls to get_next_atomizer() results
in a safe but undefined behavior.
void * get_next_atom(void *atomizer, uint32 *cookie)
Returns the next atom interned in specified atomizer, *cookie
should be set to (uint32)(0) to get the first atom. Returns
(void *)(0) when there are no more atoms. Adding atoms between
calls to get_next_atom() may cause atoms to be skipped.
Atomizers are SMP-safe. Check return codes for errors!
*/
#define B_ATOMIZER_MODULE_NAME "generic/atomizer/v1"
#define B_SYSTEM_ATOMIZER_NAME "BeOS System Atomizer"
typedef struct {
void *atomizer; /* An opaque token representing the atomizer. */
char name[B_OS_NAME_LENGTH]; /* The first B_OS_NAME_LENGTH bytes of the atomizer name, null terminated. */
uint32 atom_count; /* The number of atoms currently interned in this atomizer. */
} atomizer_info;
typedef struct {
module_info minfo;
const void * (*find_or_make_atomizer)(const char *string);
status_t (*delete_atomizer)(const void *atomizer);
const void * (*atomize)(const void *atomizer, const char *string, int create);
const char * (*string_for_token)(const void * atomizer, const void *atom);
status_t (*get_next_atomizer_info)(void **cookie, atomizer_info *info);
const void * (*get_next_atom)(const void *atomizer, uint32 *cookie);
} atomizer_module_info;
#ifdef __cplusplus
}
#endif
#endif