COID remote console

coidc [-all] [host:port]

Connects to localhost:55099 or to the specified host:port. It requests the console service from the COID server, that enables it to browse through the system log, filter system log messages and to send commands to the COID server and objects located therein.

The remote console allows to create instances of served classes or to bind to existing instances, and to invoke methods on these objects too. So for example you can connect to an instance of your C++ class, call a method, passing in the in- and inout- type arguments and receiving the out- type arguments back, all text formatted. The remote object doesn't even know the difference between normal call or a method call from remote console, even though in the first case the communication goes through a binary stream, while console communicates through a text-formatting stream. The abstraction is possible thanks to binstream class.

There are two types of commands:
- console commands, used to modify console behaviour
- object specific commands, applicable on selected server objects

Console commands are:

quit q	quit console
ls [n]	list child nodes of selected node (or list childs of node n)
cd cd [n]	change selected node to ConnectionCoid node of this console connection or change selected node to n
ping [size]	measure ping time to server, optionally transfering to and from the specified amount of bytes

Any object command may be aimed at multiple objects by preceding command with path specifier. The path can begin with characters: . / * or a number (id of object). The path and command are separated by space or colon characters.

path

selection

. .. / /@server /xyz /xyz@server /@server/ *unknown *unknown/

currently selected device (default root) parent device anything immediatelly below root anything immediatelly below root of class server anything immediatelly below root that has name xyz anything immediatelly below root of class serverthat has name xyz   anything immediatelly below all objects of classs server living below the root all objects in any level below currently selected one, that have name 'unknown' anything immediatelly below all objects in any level under currently selected one that have name 'unknown'

Object commands are specific to the class of the object, but some are common in all classes:

class	command	description
*	help [cmd]	print list of commands or methods or print help for command cmd
	cid	print id of connection owner node this is the node that console command cd without argument changes to
	id	print selected object/node id
	info	print info about the selected object
	lodl	list object detach list, identifiers of objects that would be destroyed if this object is dropped the objects are listed in the order in which they would be destroyed
	lot	list object threads
	parid	print parent node id
root	acceptor restart	restart coid acceptor
	drop ID	drop object with id ID
	find CLASS [NAME]	find  objects  of  class  CLASS, optionally named NAME
	findi CLASS	find autorun instance of class
	finds CLASS	find service object of class
	server (restart|shutdown)	restart or shutdown server
	version	display server version
connection	connect SERVICENAME connect (-s | --shared) ID[:NAME] connect (-s | --shared) SERVICENAME	Create instance of specified service SERVICENAME and connect it under the connection object. Optional arguments to the connect method of the specified service can be passed after required arguments. With the -s or --shared option, the connect command tries to estabilish a shared connection to an existing object with id ID or to an autospawned object of service SERVICENAME.
	lsl	list slots (bound services) of this connection
instance	log	enable or disable method logging
	.method	calling a method of service; use help command on the object to get list of methods with parameter description

As an example we can use one of built-in services in the COID server, for example AccountMgr. AccountMgr is an ordinary C++ class that was appropriately decorated in order to be servable by the COID server. It's started automatically by the COID server and handles user accounts.

Normally you would need corresponding client to communicate with the service. But since the communication is done using abstract stream class binstream, it's possible to bind a text-formatting stream to any object on the server. The object doesn't know the difference, but we can call its methods passing textual arguments and getting formatted response.

First we need to find the AccountMgr service instance:

findi AccountMgr
6

Now we change the working device to it:

cd 6
selected device: AccountMgr  (auto)@AccountMgr (6)

Now we are working with the instance of AccountMgr service. We can list methods of the service:

help
.add_account
.del_account
.find_account
.list_accounts
log
help
cid
id
info
lodl
lot
parid

Entries starting with '.' are methods of the class, the other are commands inherited from ServiceInstanceCoid class and CoidNode class. We can get more specific help for particular method or command, for example:

help .list_accounts
.list_accounts [const] OUT:( dynarray<account> & data )

- prints method name, qualifiers [const] and IN, INOUT and OUT arguments. In this case, the method has only OUT type arguments, namely an array of account structures.
Calling .list_accounts would yield something like this:

.list_accounts
OK
[
        {
                "root"
                "*"
                [70 6D 54 CA 7D 58 BE A1 BA 86 CE 44 7C AF 50 9F B9 07 F6 39]
                1
        }
]

16:21:38 ....   6 Account  m (3) list_accounts ( ? )  -->  (root*70 6D 54 CA 7D 58 BE A1 BA 86 CE 44 7C AF 50 9F B9 07 F6 393435973836) .. ok

First is return value, in this case opcd 0 (no error). Following is list of output values, in this case array (enclosed in square braces) of account structures, each consisting of name, group, password and flags. After the output appears a line from the COID server log subsystem, logging the call that has been made to AccountMgr service. We can turn off the log for this object calling the log command, that is recognized by any ServiceInstanceCoid object, i.e. an instance of any served class.

log
method log disabled

When we called the list_accounts method, there was only one entry, that for implicit "root" account of the server. We can create more accounts by calling add_account method. First we look at the arguments:

help .add_account
.add_account IN:( const account & acid, bool modify )

This method has only input arguments, account structure and flag saying if we are modifying the account (true) or adding new one (false). Let's add a new account.

.add_account { "joe" "*" $PWD$ 0 } false
password:
**
OK

The $PWD$ construct is catched by the console before the data are sent to the console service, it allows to ask for passwords without echoing the characters on the console. Equivalently you could type the hashed password as an array of 20 numbers straight away :)
Now we call list_accounts again:

.list_accounts
OK
[
        {
                "joe"
                "*"
                [70 6D 54 CA 7D 58 BE A1 BA 86 CE 44 7C AF 50 9F B9 07 F6 39]
                0
        }

        {
                "root"
                "*"
                [70 6D 54 CA 7D 58 BE A1 BA 86 CE 44 7C AF 50 9F B9 07 F6 39]
                1
        }
]

Note that list_accounts method doesn't return valid passwords, only name, group and flags.