- Main Page
- Modules
- Data Structures
- Files

# 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