• Antelope Release 5.10 Linux CentOS release 7.6.1810 (Core) 3.10.0 2020-05-12

 

NAME

cmdthread_new, cmdthread_destory - ORB packet command processing

SYNOPSIS

#include "brttpkt.h"

CmdThread *
cmdthread_new (int orbcmd, int orbrsp, char *target,
		char *type, int (*callback) (CmdThread *cth, void *user_data, int what, ...), void *user_data)

int cmdthread_destory (CmdThread *cmdthr)

int cmdthread_send_rsp (CmdThread *cmdthr, Pf *pfcmd, char *dlname, char *dlserial, char *dlcom, Pf *pfrsp, char *disposition)

DESCRIPTION

These routines provide a utility for reading and processing ORB datalogger command packets as produced by dlcmd(1).

cmdthread_new creates a new CmdThread object and returns a pointer to the object instance. This pointer is used as a handle for subsequent operations. The input ORB for reading the datalogger command packets is specified by orbcmd. Command response packets are sent to the ORB specified by orbrsp. This particular application instance is specified by target. The application instance target name is compared against the command targets regular expression to see if this particular target should respond to the command. The datalogger type is specified by type. The datalogger type name is compared against the command types regular expression to see if this particular target should respond to the command. callback specifies a user callback function that is called whenever a new ORB command packet is received. The callback function is called with the following syntax:


int callback (CmdThread *cth, void *user_data, int what, ...)

The object pointer returned from cmdthread_new is passed back with cth. The private pointer passed to cmdthread_new, user_data, is passed back to callback. what will be one of COMTHREAD_COMPLAIN, CMDTHREAD_POSTING or CMDTHREAD_EXEC. If what is set to CMDTHREAD_COMPLAIN, then there was a problem reading and processing the command packet from orbcmd and the variable arguments are set to int flag, char *format, ..., which can be used in subsequent elog(3) calls. Problems include orbreap(3) error returns, problems unstuffing the raw orb packet, problems parsing the unstuffed parameter file, missing command parameter, missing username parameter, missing hostname parameter, or missing ip parameter. Verbose error reporting is done through the variable argument list with no hardwired complains or program exits. All of these problems are deemed to make the command packet unusable. If what is set to CMDTHREAD_POSTING, then this is either an informational call indicating that the command was properly read and parsed, or an informational call indicating that the embedded packet digital signature did not check. In both cases a simple message is put into the callback variable argument list as a single char * argument. Note that when the digital signature does not check, then the command packet is automatically discarded with no further processing. When a packet has been properly read, parsed and digital signature checked, then the callback is called with what set to CMDTHREAD_EXEC, indicating that the command should be executed. In this case the callback variable arguments are set to char *cmd, Pf *pfcmd, where cmd is the value of the parameter file command parameter and pfcmd is the full command parameter file object. The callback function should execute the command and return its results through a call to cmdthread_send_rsp defined below.

cmdthead_destory will destroy all resources associated with the command processing thread.

cmdthread_send_rsp will send a response packet to the orbserver specified by orbrsp in the original cmdthread_new call. The response packet will have srcnames set to dlcmd/pf/dlcmr. These response packets are automatically read by dlcmd(1) and displayed. The response packets are meant to give the user some feedback on the efficacy of a command, or to return detailed information resulting from commands to, for instance, get configuration information. The response packets can obviously be read and used by processes other than dlcmd(1). Response packets are automatically assimilated by this function and sent to the output orbserver. pfcmd should be the unmodified parameter file command object passed to the callback routine. dlname, dlserial and dlcom are optional datalogger name, datalogger serial number and datalogger communication strings that will cause the setting of these parameters in the output response packet. If any of these are set to NULL, then that parameter will not be set. pfrsp is an optional parameter file object that will be appended into the output response packet. This provides a means to specify detailed output results. disposition is meant to indicate a result from the command processing. If it is set to done, then the command was successfully executed and any results from the command may appear as other parameters in the output packet through the pfrsp argument. If it is set to pending, then the command is in the process of being executed, but has not completed. Any partial results from the command may appear as other parameters in the output packet through the pfrsp argument. If it is set to error, then the command was not successfully executed and any error messages may appear as other parameters in the output packet through the pfrsp argument.

RETURN VALUES

cmdthdread_new returns a CmdThread process handle (pointer to a CmdThread structure) or NULL if there is an error.

Everything else returns 0 if OK or -1 if there is an error. If there is an error, then messages are left on the error register.

LIBRARY

-lbrttpkt $(ORBLIBS)

AUTHOR

Danny Harvey
Printer icon