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
Registry Query Handle. Every registry query uses an own handle to the registry system.
Enumeration Type Documentation
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
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
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 POSCALL 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 POSCALL 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
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
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 VAR_t POSCALL 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
