Novell Doc: NDK: Libraries for C (LibC), Volume 2

Syntax

  #include <netware.h> 
   
  int RegisterCommand (
     void              *NLMHandle,
     rtag_t             rTag,
     uint32_t           keywordFlags,
     const char        *keyword,
     uint32_t           handlerFlags,
     uint32_t           insertionFlags,
     CommandHandler_t   handler,
     void              *callerReference);

Parameters

NLMHandle

(IN) Points to the handle for the NML that consumes the command.

rTag

Specifies a resource tag created by calling AllocateResourceTag with the signature parameter set to CommandLineServicesSignature.

keywordFlags

(IN) Specifies the data type of keyword with one of the following flags:

Flag	Value	Description
CMD_MSG_NUMBER	0x80000000	The keyword is a message number.
CMD_LENGTH_PREC	0x40000000	The keyword is length-preceded string.

keyword

Points to a developer-defined keyword, which is used to identify the command.

If the keywordFlags parameter is set to a string, the keyword is a length-preceded string. The maximum length of a command is 48 bytes. Spaces are not allowed in a keyword. For example, use the following string to register a mycommand keyword:

  "\x09""mycommand"

handlerFlags

(IN) Specifies how to handle the command, using a bit mask of the following flags:

Flag	Value	Description
CMD_CONFIG_INFO	0x00000001	Requires configuration information.
CMD_CONVERT_UPPER	0x00000002	Must be converted to upper case.
CMD_SERVER_RUNNING	0x00000004	Requires the server to be running
CMD_LEGAL_SERVER	0x00000008	Allows this command on a regular server.
CMD_HIDDEN_CMD	0x00200000	Do not display this command.
CMD_SUB_CMDS_AVAIL	0x00100000	Allows the command to have sub commands.
CMD_NO_CMD_CHAIN	0x00010000	Do not allow any chaining of command keywords.
CMD_PASS_ON_ERROR	0x00020000	Ignores any errors
CMD_ANY_PROCESS	0x80000000	Must run on a process with a keyboard.

insertionFlags

Specifies where the command should be inserted if the command allows chaining. Use one of the following flags:

Flag	Value	Description
CMD_INSERT_AT_HEAD	0x00000001	Insert at the beginning.
CMD_INSERT_AT_TAIL	0x00000002	Insert at the end.
CMD_PERM_POSITION	0x80000000	Make this command the permanent beginning or end when ORed to the head or tail flag.

handler

(IN/OUT) Specifies the handler for the command. For a description of the prototype, see CommandHandler_t.

callerReference

Points to a developer-defined value that is passed to the handler.

Return Values

If successful, returns 0. Otherwise, returns one of the following error codes:

Decimal	Constant	Description
0x00000001	ERR_INVALID_MODULE	The NLM handle is invalid.
0x00000002	ERR_INVALID_RTAG	The resource tag is invalid.
0x00000003	ERR_INVALID_KEYWORD	The keyword is invalid because it is NULL.
0x00000004	ERR_MODULE_RTAG_MIX	The resource tag doesn't belong to the NLM.
0x00000005	ERR_MISSING_HANDLER	The handler is missing because the handler parameter is NULL.
0x00000006	ERR_KEYWORD_TOO_LONG	The keyword is longer than 48 bytes.
0x00000007	ERR_INVALID_REQUEST	The syntax indicates that this command is a permanent command but the syntax doesn't include a flag to indicate whether to set the command at the top or the bottom.
0x00000008	ERR_OUT_OF_MEMORY	Unable to allocate memory for the command.
0x00000009	ERR_FAILED_TOO_REGISTER	The command cannot be registered.
0x0000000A	ERR_ALREADY_REGISTERED	The command is trying to register as a no chaining command, but the command has already been registered to allow chaining.
0x0000000B	ERR_CANT_GRANT_TOP	The command cannot be the permanent head because another handler has registered a permanent top command.
0x0000000C	ERR_CANT_GRANT_END	The command cannot be permanent tail because another handler has registered a permanent tail command.

Remarks

The function pointer to the handler must be wrappered with the NX_WRAP_INTERFACE macro to ensure accurate library context is established if that context is needed.

This function can only be used by an application that runs in the kernel (ring 0); it cannot be used by an application that runs in protected address space (ring 3). If your application needs to run in ring 3, you need to split it into multiple NLM applications and run the NLM responsible for registering the command in ring 0.

RegisterCommand

Syntax

Parameters

Return Values

Remarks

See Also