Interface: CommandUse

Interface for using Commands. Commands provide a generic mechanism for registering and executing named commands via AM messages or a local interface.

See lib/Commands/... for examples of components that register commands.

See interfaces/Command.h for the data structures used in this interface

Implemented by lib/Command.td

Author: Wei Hong (wei.hong@intel-research.net)

Components providing this interface:: tos.lib.Command
tos.lib.TinyDB.TinyDBCommand

Components requiring this interface:: tos.lib.TinyDB.DBBufferC
tos.lib.TinyDB.NetworkC
tos.lib.TinyDB.TupleRouterM

Commands

CommandDescPtr getCommand (char *name) Get a descriptor for the specified command
CommandDescPtr getCommandById (uint8_t idx) Get a descriptor for a specified command id
uint8_t numCommands(void)

Returns: The number of commands currently registered with the system
CommandDescsPtr getCommands(void)

Returns: A list of all the commands in the system
result_t invoke (char *commandName, char *resultBuf, SchemaErrorNo *errorNo, ParamVals *params) Invoke the specified command by name, with the specified parameters.
result_t invokeById(uint8_t commandId, char *resultBuf, SchemaErrorNo *errorNo, ParamVals *params)
result_t invokeMsg (TOS_MsgPtr msg, char *resultBuf, SchemaErrorNo *errorNo) Given a msg represent a command invocation, invoke the appropriate command, writing results to resultBuf.

Events

result_t commandDone (char *commandName, char *resultBuf, SchemaErrorNo errorNo) Signalled when a command invocation is complete

Commands - Details

getCommand

CommandDescPtr getCommand(char *name)

Get a descriptor for the specified command

Parameters:	name - The (8 byte or shorted, null-terminated) name for the command of interest.
Returns:	A pointer to the command descriptior, or NULL if no such command exists.

getCommandById

CommandDescPtr getCommandById(uint8_t idx)

Get a descriptor for a specified command id

Parameters:	idx - The (0-based) index of the command of interest
Returns:	A pointer to the command descriptor, or NULL if no such command exists.

invoke

result_t invoke(char *commandName, char *resultBuf, SchemaErrorNo *errorNo, ParamVals *params)

Invoke the specified command by name, with the specified parameters. Write the results into the specified buffer.

Parameters:

commandName - The command to invoke.

resultBuf - The buffer to write results into (must be at least sizeOf(CommandDesc.retType) bytes long)

errorNo - (on return) The result code (may signal a split-phase invocation, for which a commandDone event will be fired later) See SchemaType.h for a list of possible result codes

params - The parameters to this funtion.

invokeMsg

result_t invokeMsg(TOS_MsgPtr msg, char *resultBuf, SchemaErrorNo *errorNo)

Given a msg represent a command invocation, invoke the appropriate command, writing results to resultBuf. See invoke(...) above

Parameters:

msg - The command message. The format of this message is a packed array representing the name of the command, followed by a packed list of parameters. See java/net/tinyos/tinydb/CommandMsgs.java for an example of a Java program that invokes a command.

resultBuf - The result buffer to write results into

errorNo - (on return)The result code

Events - Details

commandDone

result_t commandDone(char *commandName, char *resultBuf, SchemaErrorNo errorNo)

Signalled when a command invocation is complete

Parameters:

commandName - The command that was completed

resultBuf - The buffer where the results were written

errorNo - The return code from the invocation.