Commands
neuray Services commands are the core of the services system.
Command Naming
Commands are identified by a name and optional namespace. Namespaces are hierarchical and must be specified in full by the command as a '::' separated sequence of strings. Command names must be unique within their namespace, if more than one command is installed within a namespace then the last command installed overwrites the earlier ones. Note that neuray Services has no concept of a 'current' namespace so when calling commands the fully qualified command name must be given, IE: "namespace::command_name". If a command does not specify a namespace then the namespace may be omitted and the command simple called as "command_name".
Command Documentation
neuray Services commands are self documenting and the command interface provides various methods which can be implemented to provide information on the commands functionality, the arguments it accepts and the value that it returns.
Command Arguments
Arguments to commands are accessed by name through the command context. The types supported by arguments include most of the Neuray Library types in addition to a number of neuray Services defined types. You may also extend the supported types with user defined structures.
If a particular arguments self documentation includes a type name then neuray Services will automatically attempt to convert any supplied argument of that name to the specified type. This frees you from having to do this conversion yourself. If type conversion fails then the command will not be executed and an error is returned. Additionally, if a default value is specified, and that argument is not given by the user, then this default is supplied instead.
Command Results
On completion a command can return either the result of the command or an error to the user. The result may be any type supported as an argument. An error response consists of an error code, an error message plus optional, additional information pertaining to the error.
Note that unlike arguments the type of a result is not restricted to the type specified in the self documentation. neuray Services will not perform any automatic conversion.
Attachments
Commands may have additional, more general, data attached to them. This comes in two forms, command attachments which are accessible only to the current command, and global attachments which are accessible to all commands. If a command modifies a global attachment then any commands it executes, or commands executed as part of the same request will see the modified attachments. Attachments are used to provide more general information to commands that would not be considered arguments and may be provided by neuray Services itself or by the parent application.