Registry
[User API: Nano Layer]


Typedefs

typedef void * NOSGENERICHANDLE_t
typedef void * NOSREGQHANDLE_t

Enumerations

enum  NOSREGTYPE_t {
  REGTYPE_TASK = 0, REGTYPE_SEMAPHORE, REGTYPE_MUTEX, REGTYPE_FLAG,
  REGTYPE_TIMER, REGTYPE_USER, REGTYPE_SEARCHALL
}

Functions

NANOEXT NOSGENERICHANDLE_t nosGetHandleByName (NOSREGTYPE_t objtype, const char *objname)
NANOEXT VAR_t nosGetNameByHandle (NOSGENERICHANDLE_t handle, char *buffer, VAR_t bufsize, NOSREGTYPE_t what)
NANOEXT VAR_t nosRegSet (const char *keyname, KEYVALUE_t keyvalue)
NANOEXT VAR_t nosRegGet (const char *keyname, KEYVALUE_t *keyvalue)
NANOEXT VAR_t nosRegDel (const char *keyname)
NANOEXT NOSREGQHANDLE_t nosRegQueryBegin (NOSREGTYPE_t type)
NANOEXT VAR_t nosRegQueryElem (NOSREGQHANDLE_t qh, NOSGENERICHANDLE_t *genh, char *namebuf, VAR_t bufsize)
NANOEXT void nosRegQueryEnd (NOSREGQHANDLE_t qh)

Detailed Description

Note: This API is part of the nano layer

Registry keys are short ASCII texts that are assigned to binary numbers like integers or pointers. pico]OS uses registry keys in two ways:

First, this keys are used to identify resources, such as tasks, semaphores and timers. So it is possible to create named semaphores, that are accessible by every program module that knows the name of the semaphore (the program module does not need to know the exact semaphore handle, the ASCII name is sufficiennt). Also with named resources it is possible to maintain a list of allocated resources, e.g. this resource list can be printed out to a shell window.

Second, registry keys can be used by an application to maintain a central storage with setup and configuration data. This is known as "the registry" in MS Windows operating systems.

Typedef Documentation

typedef void* NOSGENERICHANDLE_t
 

Generic Handle

typedef void* NOSREGQHANDLE_t
 

Registry Query Handle. Every registry query uses an own handle to the registry system.

Enumeration Type Documentation

enum NOSREGTYPE_t
 

Registry type

Enumerator:
REGTYPE_TASK  task registry
REGTYPE_SEMAPHORE  semaphore registry
REGTYPE_MUTEX  mutex registry
REGTYPE_FLAG  flag event registry
REGTYPE_TIMER  timer registry
REGTYPE_USER  user defined registry
REGTYPE_SEARCHALL  this is a special flag for the function nosGetNameByHandle

Function Documentation

NANOEXT NOSGENERICHANDLE_t nosGetHandleByName (  NOSREGTYPE_t  objtype,
const char *  objname
) 
 

Registry function. Searches the registry for an object name and returns the handle that is assigned to the object. For example, somebody can get a semaphore handle by just knowing the semaphores name.

Parameters:
objtype Type of the object that is searched for. Valid types are: REGTYPE_TASK, REGTYPE_SEMAPHORE, REGTYPE_MUTEX, REGTYPE_FLAG, REGTYPE_TIMER, REGTYPE_USER
objname Name of the object to search for.
Returns:
The handle to the object on success, NULL if the object was not found.
Note:
NOSCFG_FEATURE_REGISTRY must be defined to 1 to enable the registry and this function.
See also:
nosGetNameByHandle

NANOEXT VAR_t nosGetNameByHandle (  NOSGENERICHANDLE_t  handle,
char *  buffer,
VAR_t  bufsize,
NOSREGTYPE_t  what
) 
 

Registry function. Searches the registry for a handle and returns the name of the objetct.

Parameters:
handle Object-handle to search the registry for.
buffer If the object could be found in the registry, the name of the object will be stored in this buffer.
bufsize Size of the buffer in bytes. The size should be at least NOS_MAX_REGKEYLEN + 1.
what What to search for. If the type of the handle is known, this parameter should be set to REGTYPE_TASK, REGTYPE_SEMAPHORE, REGTYPE_MUTEX, REGTYPE_FLAG, REGTYPE_TIMER or REGTYPE_USER. If the object type is unknown, you may specify REGTYPE_SEARCHALL. But note that the user branch of the registry will not be included into the search.
Note:
NOSCFG_FEATURE_REGISTRY must be defined to 1 to enable the registry and this function.
See also:
nosGetHandleByName

NANOEXT VAR_t nosRegDel (  const char *  keyname  ) 
 

Registry function. Deletes a registry key string.

Parameters:
keyname Name of the registry key string to delete.
Returns:
Zero on success. Nonzero values denote an error.
Note:
NOSCFG_FEATURE_REGISTRY and NOSCFG_FEATURE_USERREG must be defined to 1 to enable the registry and this function.
See also:
nosRegSet, nosRegGet

NANOEXT VAR_t nosRegGet (  const char *  keyname,
KEYVALUE_t *  keyvalue
) 
 

Registry function. Returns the binary value that is assigned to a registry key. This function is the counterpart to function nosRegSet.

Parameters:
keyname text string that binary value shall be returned
keyvalue Pointer to a variable of type KEYVALUE_t. When the function succeeds (the text string could be found), the value that is associated with the registry key is stored in this variable.
Returns:
Zero on success. Nonzero values denote an error.
Note:
NOSCFG_FEATURE_REGISTRY and NOSCFG_FEATURE_USERREG must be defined to 1 to enable the registry and this function.
See also:
nosRegSet, nosRegDel

NANOEXT NOSREGQHANDLE_t nosRegQueryBegin (  NOSREGTYPE_t  type  ) 
 

Registry function. Queries a list of registry keys. This function starts a new registry query.

Parameters:
type Type of the registry to query:
  • REGTYPE_TASK: query list of task handles
  • REGTYPE_SEMAPHORE: query list of semaphore handles
  • REGTYPE_MUTEX: query list of mutex handles
  • REGTYPE_FLAG: query list of flag event handles
  • REGTYPE_TIMER: query list of timer handles
  • REGTYPE_USER: query list of user values (registry)
Returns:
Handle to the new query. NULL is returned on error.
Note:
In the current implementation, only one registry query can run at a time. The next query can start when the first query is finnished (function nosRegQueryEnd called).
As long as the user queries the registry, all other operating system functions that try to access the registry will be blocked.
NOSCFG_FEATURE_REGISTRY and NOSCFG_FEATURE_REGQUERY must be defined to 1 to enable the registry and this function.
See also:
nosRegQueryElem, nosRegQueryEnd

NANOEXT VAR_t nosRegQueryElem (  NOSREGQHANDLE_t  qh,
NOSGENERICHANDLE_t *  genh,
char *  namebuf,
VAR_t  bufsize
) 
 

Registry function. Returns the next found element in a query.

Parameters:
qh Handle to the current query (returnvalue of nosRegQueryBegin).
genh Pointer to a (user provided) generic handle variable. In this variable the handle of the next found registry key will be stored. For user registry keys (REGTYPE_USER), this is the KEYVALUE_t.voidptr
namebuf Pointer to a (user provided) character buffer. The buffer is filled with the name of the next registry key that is found. The buffer must have at least a size of NOS_MAX_REGKEYLEN+1 characters.
bufsize Size of namebuf in bytes.
Returns:
Zero on success (E_OK). A negative value denotes an error. -E_NOMORE is returned when the end of the query is reached.
Note:
NOSCFG_FEATURE_REGISTRY and NOSCFG_FEATURE_REGQUERY must be defined to 1 to enable the registry and this function.
See also:
nosRegQueryBegin, nosRegQueryEnd

NANOEXT void nosRegQueryEnd (  NOSREGQHANDLE_t  qh  ) 
 

Registry function. Finnishes a query. This function is the counterpart to nosRegQueryBegin.

Parameters:
qh Handle to the current query (returnvalue of nosRegQueryBegin).
Returns:
Zero on success. A negative value denotes an error.
Note:
NOSCFG_FEATURE_REGISTRY and NOSCFG_FEATURE_REGQUERY must be defined to 1 to enable the registry and this function.
See also:
nosRegQueryBegin, nosRegQueryElem

NANOEXT VAR_t nosRegSet (  const char *  keyname,
KEYVALUE_t  keyvalue
) 
 

Registry function. Sets a key value or creates a new registry key string. This function is used to assign a binary value to a text string. If the user knows the text string, he can call nosRegGet to get the binary value that is associated with the text string.

Parameters:
keyname text string, name of the registry key to create or set
keyvalue binary value that shall be assigned to the registry key
Returns:
Zero on success. Nonzero values denote an error.
Note:
When creating a new registry key string, you can use the asteriks joker sign as last character in the registry key string. This function will replace the asteriks character by a decimal number, so that the generated registry key will be unique.
NOSCFG_FEATURE_REGISTRY and NOSCFG_FEATURE_USERREG must be defined to 1 to enable the registry and this function.
The maximum length of a registry key string is NOS_MAX_REGKEYLEN.
See also:
nosRegGet, nosRegDel

Generated on Mon May 1 11:07:42 2006 for pico]OS by  doxygen 1.4.6-NO