Feature dcAPI - Gadreel/divconq GitHub Wiki

The dcAPI feature is when you use DivConq as a client to a DivConq server. The dcAPI provides a selection of operations to connect to and interoperate with a DivConq server. One interesting aspect of dcAPI is that you may test it right in the server process if you like by connecting to "localhost" (or any domain supported by the server). So to start development with [dcScript] (Feature dcScript) use localhost first for easy debugging.

Sessions to a DivConq server use CTP (Common Transfer Protocol) to pass messages and files to the server.

Connect to the current DivConq process as root user.

<CtpSession Name="MySession" Host="localhost" />

Connect to the current DivConq process as root user.

<CtpSession Name="MySession" Host="localhost" User="mike" Password="temp123" />

Connect to a remote server at somehost.com as a user.

<CtpSession Name="MySession" Host="somehost.com" User="mike" Password="temp123" />

• Name
• Host domain name to connect to
• Port defaults to 443
• Secure defaults to true, you can connect to an unsecured remote port but only if you force DivConq to
• User who to sign in as
• Password password for the user

• HubId id of hub connected to
• SessionId id of session connected to
• SessionKey key of session connected to
• Host domain name to connect to
• Port defaults to 443
• Secure defaults to true, you can connect to an unsecured remote port but only if you force DivConq to
• User who to sign in as
• Password password for the user

TODO how to use Cert as creds instead of User and Password.

To send a message to the server:

<CtpCall Name="TheResponse" Session="$MySession" Service="[service name]" Feature="[feature name]" Op="[op name]" Data="$RequestData" />

$TheResponse now holds the result of the request. This is just a typical RecordStruct or ListStruct or some ScalarStruct which can then be accessed in the typical way.

Errors from the response will be copied into the script's own log, including errors. To respond to errors either use advanced features further below (TODO add description of how to get access to the message object and how to manage errors - copy or not) or use the typical approach like this:

<CtpCall Name="TheResponse" Session="$MySession" Service="Status" Feature="Echo" Op="Test" Data="Hello Buddy!" />

<ExitIfErrored Code="1" Result="Cannot continue, there was an error calling the Status service" />

<Info>Here is the response we got: {$TheResponse}</Info>

If the message is already a fully formed record:

<CtpCall Name="TheResponse" Session="$MySession" Message="$RequestMessage" />

If there is no data for the request:

<CtpCall Name="TheResponse" Session="$MySession" Service="[service name]" Feature="[feature name]" Op="[op name]" />

To send a message to the server without looking for a response:

<CtpCallForget Session="$MySession" Service="[service name]" Feature="[feature name]" Op="[op name]" />

Example:

<CtpCallForget Session="$MySession" Service="Status" Feature="Tickle" Op="Test" Data="Hello Buddy!" />

File to File transfer local to Ctp Server

<CtpUpload Session="$MySession" Service="dcFileServer" 
	Source="[local path]" Dest="[path on server]" />

<CtpDownload Session="$MySession" Service="dcFileServer" 
	Dest="[local path]" Source="[path on server]" />

Remote DivConq File System (via API)

<CtpFileStore Name="MyDeposits" Session="$MySession" Service="dcFileServer" />

Subsequent operations are the same as for any file store.

• Name
• RootPath optional, when present chains the file operations to a given path
• Session CtpSession to connect through
• Service to use to find the FileStore, defaults to dcFileServer