Defines methods that can be called remotely (via RPC). More...

Public Member Functions
int	StartJob (string programName, string args=null)
	Start a job on the remote machine. More...

int	StartJobWithNotification (string callbackAddress, long callbackPort, string programName, string args=null)
	Start a job on a remote machine, and receive a TCP msg on completion. More...

int	StartJobWithProgress (string callbackAddress, long callbackPort, long progressPort, string programName, string args=null)
	Start a job on a remote machine, sends progress messages, and a completion message. More...

bool	IsJobComplete (long jobId)
	Poll to see if a job has finished. More...

bool	StopJob (long jobId)
	Halts a running job. More...

string	GetJobResult (long jobId)
	Returns the output of a completed job. More...

string	GetJobResultEx (long jobId)
	Return job output, exit code, and other info as a json object. More...

Dictionary< long, bool >	GetAllJobs ()
	Returns all active and completed jobs. More...

bool	PluginLoad (string identifier, string dllClass, string dllPath)
	Load an arbitrary class from a DLL. More...

object	PluginCallMethod (string identifier, string methodName, params object[] args)
	Call a function in a DLL. More...

bool	PluginUnload (string identifier)
	Remove an reference to a plugin. More...

Static Public Member Functions
static bool	Run (string programName, string args=null)
	Run an exe/bat/ps1, and immediately return. More...

static string	RunWithResult (string programName, string args=null)
	Start an exe, bat, or ps1 file on the remote machine; block and return result when complete. More...

static string[]	RunWithResultAndExitCode (string programName, string args=null)
	Start an exe, bat, or ps1 file on the remote machine; block and return exit code and result when complete. More...

static bool	KillProcess (string processName)
	Kill a process by name. More...

static int	UploadFile (string filename, string data, bool overwrite)
	Uploads a file to the server. More...

static string	DownloadFile (string filename)
	Downloads a file from the server. More...

static int	Upload (string path, bool overwrite, long port=0)
	Upload a file or folder to the server. More...

static long[]	Download (string path, long port=0)
	Download a file or folder from the server. More...

static string	GetVersion ()

static bool	GetHeartbeat ()
	Simple function to confirm the server is up. Returns true in all cases. More...

static string	GetClientIP ()
	Return the IP address the of the client, as seen by the server. More...

static bool	GetIsRunningAsAdmin ()
	Return if the current process is running as an Administrator. More...

static string	GetServerLocation ()
	Return the path to this SimpleRemote assembly (SimpleDUTRemote.DLL). More...

Detailed Description

Defines methods that can be called remotely (via RPC).

The Functions class defines the methods that can be called from a remote machine. When an RPC request comes in, the RpcServer parses the request, and hands it to the Dispatcher object. The Dispatcher determines which method to call in this class (by checking the method names), and calls it with the parameters provided in the request.

Member Function Documentation

◆ Download()

static long [] SimpleDUTRemote.Functions.Download	(	string	path,
		long	port = `0`
	)

inlinestatic

Download a file or folder from the server.

This method openes a port on the server, and allows the client to directly read data from the port. All data is wrapped in a tarfile. The client can either write the received bytes directly to a tarfile, or extract the contents.
This method supports supports glob expressions, as long as they are at the end of the path (C:\foo* and C:\foo*.etl are valid, C:*\bar\baz is not).
The port will timeout if a connection is not established promptly, so clients should connect to the port immediately after calling this method.

Parameters

path	Path to download on the remote machine.
port	Optional port number to use for the transfer. If not specified, the server will let the OS choose the port number.

Returns: Array of two 64-bit integers, the port number, and the uncompressed size of the files/directories to transfer in bytes.

◆ DownloadFile()

static string SimpleDUTRemote.Functions.DownloadFile ( string filename )

inlinestatic

Downloads a file from the server.

Retrieves a file, as a base64 encoded string. The client is responsible for performing base64 decoding on the data.
This operation stores the entire file in memory while it is being received and encoded. If you are moving large files (over 1GB), you should use DownloadLargeFile() instead.

Parameters

filename Location on DUT to fetch.

Returns: Base64 encoded string, containing the contents of the file.

◆ GetAllJobs()

Dictionary<long, bool> SimpleDUTRemote.Functions.GetAllJobs ( )

inline

Returns all active and completed jobs.

Returns all the active jobs on the system (ones which are running) and jobs that have completed, but the result has not been read.

Returns: Dictionary of job numbers, and bools indicating if the jobs are complete.

◆ GetClientIP()

static string SimpleDUTRemote.Functions.GetClientIP ( )

inlinestatic

Return the IP address the of the client, as seen by the server.

This may be useful for some systems where the test machine has mutliple active interfaces, and a user would like to determine which is being used by this connection.

Returns: IP Address of the client, as a string

◆ GetHeartbeat()

static bool SimpleDUTRemote.Functions.GetHeartbeat ( )

inlinestatic

Simple function to confirm the server is up. Returns true in all cases.

Returns: True.

◆ GetIsRunningAsAdmin()

static bool SimpleDUTRemote.Functions.GetIsRunningAsAdmin ( )

inlinestatic

Return if the current process is running as an Administrator.

This function only works on Windows. It will throw PlatformNotSupportedException on MacOS and Linux.

Returns: True if this process is running as an administrator. False otherwise.

◆ GetJobResult()

string SimpleDUTRemote.Functions.GetJobResult ( long jobId )

inline

Returns the output of a completed job.

Retrieves the output from a completed job (stdout and stderr). Once this function is completed, all resources assocated with the job will be freed, and the job id will become invalid.

Parameters

jobId Job id returned by CreateJob()

Returns: String of stdout and stderr from completed job.

◆ GetJobResultEx()

string SimpleDUTRemote.Functions.GetJobResultEx ( long jobId )

inline

Return job output, exit code, and other info as a json object.

Retrieves the output from a completed job as a json string. This output includes:

output: stdout and stderr as a string
exitCode: the exit code of the completed process.

In future versions, this function may return additional information.
Like GetJobResult(), once this function is completed, all resources assocated with the job will be freed, and the job id will become invalid.

Parameters

jobId Job id returned by CreateJob()

Returns: String of stdout and stderr from completed job.

◆ GetServerLocation()

static string SimpleDUTRemote.Functions.GetServerLocation ( )

inlinestatic

Return the path to this SimpleRemote assembly (SimpleDUTRemote.DLL).

Returns: Path to SimpleRemote server DLL.

◆ IsJobComplete()

bool SimpleDUTRemote.Functions.IsJobComplete ( long jobId )

inline

Poll to see if a job has finished.

Parameters

jobId Job id returned by CreateJob()

Returns: True if done, false otherwise.

◆ KillProcess()

static bool SimpleDUTRemote.Functions.KillProcess ( string processName )

inlinestatic

Kill a process by name.

Kill a task using the image name (the name in process manager). If you are trying to start a process that was created with StartJob(), use StopJob() instead.

Parameters

processName Name of the process to stop.

Returns: String "OK"

◆ PluginCallMethod()

object SimpleDUTRemote.Functions.PluginCallMethod	(	string	identifier,
		string	methodName,
		params object[]	args
	)

inline

Call a function in a DLL.

Call a function in a class, loaded from a custom DLL. The class must have been loaded with PluginLoad() before calling this function.

Parameters

identifier	A string identifier passed to PluginLoad() to locate the class.
methodName	Method to call on the loaded DLL.
args	Optional arguments to be passed to the called function.

Returns: The result from the call, or null if the function called was type void.

◆ PluginLoad()

bool SimpleDUTRemote.Functions.PluginLoad	(	string	identifier,
		string	dllClass,
		string	dllPath
	)

inline

Load an arbitrary class from a DLL.

In cases where calling an executable or script is undesirable, users can use this function to access an arbitrary .NET DLL, provided that it is compatible with the running architecture and framework (use .NET DLLs for .NET Framework, .NET Core DLLs for netcore).

Be advised that, when copying your DLL, you must copy any dependent DLLs as well.

The class must also have a constructor that doesn't take arguments. If you need more complex object creation, create a basic instance of the class, and call a function to perform any required initialization.

Parameters

identifier	A string identifier to reference the loaded class in future calls.
dllClass	The fully qualified name of the class (Namespace.Classname)
dllPath	The path to the DLL. Dependent libraries must be in the same directory.

Returns: Bool if successful, throws otherwise.

◆ PluginUnload()

bool SimpleDUTRemote.Functions.PluginUnload ( string identifier )

inline

Remove an reference to a plugin.

This removes the referenced class from the internal class store, allowing it to be garbage collected. This function does not unload the assembly - there is no mechanism in .NET to unload a manually loaded assembly.

Parameters

identifier A string identifier passed to PluginLoad() to locate the class.

Returns: True if successful, throws otherwise.

◆ Run()

static bool SimpleDUTRemote.Functions.Run	(	string	programName,
		string	args = `null`
	)

inlinestatic

Run an exe/bat/ps1, and immediately return.

Runs an exe, bat, or powershell script on the remote machine, ignoring any output from the process.
This function will block until the item finishes, and should not be used for items that will take an extended amount of time to run, as waiting on a long-running process may trigger a timeout exception (depending your client's timeout settings). If you need to start a long-running task, consider using StartJob() instead.

Parameters

programName	Name of called program (exe/bat/ps1).
args	Arguments for the called program.

Returns: True on success. Throws exception otherwise.

◆ RunWithResult()

static string SimpleDUTRemote.Functions.RunWithResult	(	string	programName,
		string	args = `null`
	)

inlinestatic

Start an exe, bat, or ps1 file on the remote machine; block and return result when complete.

Runs an exe, bat, or powershell script on the remote machine, capturing output from the process. This function will block until the item finishes, and should be used with caution for items that will take an extended amount of time to run, as waiting on a long-running process may trigger a timeout exception on your client (depending on your client's socket settings). If you need to start a long-running task, consider using StartJob() instead.

Some networking devices may automatically disconnect TCP connections that are idle for extended periods. Enabling TCP keep alive packets on your client may help, at the expense of additional power consumption on the server.

Parameters

programName	Name of called program (exe/bat/ps1).
args	Arguments for the called program.

Returns: Standard output and error from called process.

◆ RunWithResultAndExitCode()

static string [] SimpleDUTRemote.Functions.RunWithResultAndExitCode	(	string	programName,
		string	args = `null`
	)

inlinestatic

Start an exe, bat, or ps1 file on the remote machine; block and return exit code and result when complete.

Runs an exe, bat, or powershell script on the remote machine, capturing output from the process. This function will block until the item finishes, and should be used with caution for items that will take an extended amount of time to run, as waiting on a long-running process may trigger a timeout exception on your client (depending on your client's socket settings). If you need to start a long-running task, consider using StartJob() instead.

Some networking devices may automatically disconnect TCP connections that are idle for extended periods. Enabling TCP keep alive packets on your client may help, at the expense of additional power consumption on the server.

Parameters

programName	Name of called program (exe/bat/ps1).
args	Arguments for the called program.

Returns: Array of strings containing the exit code, and merged standard output and error from called process.

◆ StartJob()

int SimpleDUTRemote.Functions.StartJob	(	string	programName,
		string	args = `null`
	)

inline

Start a job on the remote machine.

The job system allows callers to start long-running jobs on the remote machine without blocking. When a job is started (using this function), the function returns a job id which can be used to query the status of the job, or to retrieve it's result. A given job id is valid until a call to GetJobResult(), which returns the output from the job and releases any associated resources, or a call to StopJob() which terminates a job and releases any resources.

Note that any output to stdout or stderr from the job will be stored in memory until GetJobResult() is called. If your job will generate a large amount of output, you may want to pipe the output to a file instead.

Parameters

programName	Name of called program (exe/bat/ps1).
args	Arguments for the called program.

Returns: Job id of newly generated job.

◆ StartJobWithNotification()

int SimpleDUTRemote.Functions.StartJobWithNotification	(	string	callbackAddress,
		long	callbackPort,
		string	programName,
		string	args = `null`
	)

inline

Start a job on a remote machine, and receive a TCP msg on completion.

Operates identically to StartJob(), but sends a simple text message back to the client once the job is done via TCP. The message is always JOB X COMPLETED where X is the job number. This requires that the client have a TCP listener active on the specified port before the job finishes to receive the callback. If the job finishes and the service cannot contact open a connection to the client, it will simply log the failure, and continue to operate normally, as though the standard StartJob() function was used.

Parameters

callbackAddress	IP address of the client machine, if not specified will use data from this connection.
callbackPort	TCP port number on the client machine to connect to for the callback
programName	Name of called program (exe/bat/ps1).
args	Arguments for the called program.

Returns: Job id of the newly generated job.

◆ StartJobWithProgress()

int SimpleDUTRemote.Functions.StartJobWithProgress	(	string	callbackAddress,
		long	callbackPort,
		long	progressPort,
		string	programName,
		string	args = `null`
	)

inline

Start a job on a remote machine, sends progress messages, and a completion message.

Operates identically to StartJobWithNotification(), but every time the called process emits a line of output, the server will send the line of output via TCP to the port specified by progressPort. As with StartJobWithNotification(), a completion message will be sent to the callbackPort once the job finishes. The process will also log all output to a file named SimpleRemote-JobOutput-[TIMESTAMP] in the TEMP directory. This is to ensure that, even if the network fails, output will not be lost.

Because this function creates network and disk activity, it should not be used in power testing.

Note: When this function is used, the server will no longer store process output in memory. Calling GetJobResult() will result in an empty string. It is recommended you still call GetJobResult() to acknowledge to the server that you're done with the job, and ensure any resources associated with the job are properly cleaned.

Parameters

callbackAddress	IP address of the client machine, if not specified will use data from this connection.
callbackPort	TCP port number on the client machine to connect to for the callback
progressPort	TCP port number on the client machine to send progress.
programName	Name of called program (exe/bat/ps1).
args	Arguments for the called program.

Returns: Job id of the newly generated job.

◆ StopJob()

bool SimpleDUTRemote.Functions.StopJob ( long jobId )

inline

Halts a running job.

Terminates a job and the underlying called process. Note that if this function is successful, the job id will become invalid, and any captured output from the job will be lost.

Parameters

jobId Job id returned by CreateJob()

Returns: True on success, throws exception otherwise.

◆ Upload()

static int SimpleDUTRemote.Functions.Upload	(	string	path,
		bool	overwrite,
		long	port = `0`
	)

inlinestatic

Upload a file or folder to the server.

This method openes a port on the server, and allows the client to directly write data to the port. It treats all data written as part of a tarfile. As data is received from the socket, it is extracted to the target path. Once the server receives the last block of the tarfile, it will send back the number of bytes written to disk.
The port will timeout if a connection is not established promptly, so clients should connect to the port immediately after calling this method.

Parameters

path	Path of directory to save extracted data on the remote machine.
overwrite	Bool indicating if existing files should be overwritten.
port	Optional port number to use for the transfer. If not specified, the server will let the OS choose the port number.

Returns: Port on remote machine

◆ UploadFile()

static int SimpleDUTRemote.Functions.UploadFile	(	string	filename,
		string	data,
		bool	overwrite
	)

inlinestatic

Uploads a file to the server.

Writes the provided base64 encoded data to a file. The client is responsible for performing base64 encoding on the data. You must specify if files should be overwritten.
This operation stores the entire file in memory while it is being received and decoded. If you are moving large files (over 1GB), you should use UploadLargeFile() instead.

Parameters

filename	Location on DUT to store data.
data	Base64 encoded contents of the file to save.
overwrite	Flag to indicate if existing files should be overwritten.

Returns: Number of bytes written.

The documentation for this class was generated from the following file:

SimpleDUTRemote/Functions.cs

Public Member Functions

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ Download()

◆ DownloadFile()

◆ GetAllJobs()

◆ GetClientIP()

◆ GetHeartbeat()

◆ GetIsRunningAsAdmin()

◆ GetJobResult()

◆ GetJobResultEx()

◆ GetServerLocation()

◆ IsJobComplete()

◆ KillProcess()

◆ PluginCallMethod()

◆ PluginLoad()

◆ PluginUnload()

◆ Run()

◆ RunWithResult()

◆ RunWithResultAndExitCode()

◆ StartJob()

◆ StartJobWithNotification()

◆ StartJobWithProgress()

◆ StopJob()

◆ Upload()

◆ UploadFile()