#include "generalDefines.h"

Classes
struct	MCDevice
	MC device details This is a struct returned from GetDeviceList where each struct contains Soft MC details, such as name, ip, serialNumber. More...

class	KMApi
	The KMApi class for connecting and communicating with MC. Use the KMApi class inside any other program. KMApi supports a direct access via the KMAPI class. KMApi Dll, also, contains a set of wrapper functions. More...

Macros
#define	KMAPI_EXPORT __declspec(dllimport)

Functions
typedef	void (__stdcall MCCallback)(int

KMAPI_EXPORT KMApi *	KMNewKMAPI ()
	Creates and returns a new KMApi object. Use this method to create a new KMApi object (do not create it directly) you may use the class directly: More...

KMAPI_EXPORT void	MCFreeKMApi (KMApi *pKmapi)
	Releases KMApi object. Use this method to release KMApi object and free memory. Here is an example of creating, using and freeing kmapi object: More...

KMAPI_EXPORT void	SetCallback (KMApi pKmapi, MCCallback pCallback)
	Sets a pointer to a callback function. Assign the callback function to receive async messages and other error status notifications. . More...

KMAPI_EXPORT KMResponse	Connect (KMApi *pKmapi, LPCSTR ip, int port)
	Connect to a specific IP and port. the connect function tries to connect a specific IP:port. If it succeeds, return value is KMRet_OK. It may return Timeout or connection refused. On error, you should always call GetMCLastError and get detailed description from the socket. . More...

KMAPI_EXPORT KMResponse	ExecCommand (KMApi *pKmapi, LPCSTR command, LPSTR response, int rspLength)
	Executes command and waits for response This method will execute a command and will return a string with the response from MC or an error code. the function will return a timeout error if no response was receive before defined timeout see `SetTimeout` for details. Calling this function will force KMApi to wait for acknowledge and prompt frames before it returns . More...

KMAPI_EXPORT KMResponse	SendCommand (KMApi *pKmapi, LPCSTR command)
	Sends a command but doesn't to wait for response. The function send a command on Soft MC and returns. . More...

KMAPI_EXPORT KMResponse	DownloadFile (KMApi *pKmapi, LPCSTR sFilePath, LPCSTR sFileName)
	Downloads a file from Soft MC to a specific folder on the PC. . More...

KMAPI_EXPORT KMResponse	UploadFile (KMApi *pKmapi, LPCSTR Filename)
	Uploads a file to Soft MC . More...

KMAPI_EXPORT KMResponse	GetMCLastError (KMApi *pKmapi, int &errorCode, LPSTR sErrorMessage, int msgLength)
	Gets last error from socket or from soft MC Gets the last error id and text. Call this method after you receive an error code from any kmapai function The method may return error text from soft MC or an error description from socket (last socket error) . More...

KMAPI_EXPORT void	SetTimeout (KMApi *pKmapi, KMTimeout type, DWORD timeout)

KMAPI_EXPORT KMResponse	DetectDevices (KMApi *pKmapi, DWORD Timout)
	Detect device and wait for all to responses a specific timeout This function will send a UDP message to all local networks . More...

KMAPI_EXPORT MCDevice *	GetDeviceList (KMApi *pKmapi)
	Get a list of last detected devices Call this method after calling DetectDevices to get a list of detected device. You may treat return value as an array of structs, or just move a pointer over the return buffer. . More...

KMAPI_EXPORT KMResponse	Authenticate (KMApi pKmapi, const char password)
	Performs an authentication process. If Soft MC requires authentication, you may do it using this function. In order to authenticate call this method with the right Password as string. . More...

Variables
typedef	LPCSTR

Macro Definition Documentation

◆ KMAPI_EXPORT

#define KMAPI_EXPORT __declspec(dllimport)

Definition at line 13 of file KMApi.h.

Function Documentation

◆ Authenticate()

KMResponse Authenticate	(	KMApi *	pKmapi,
		const char *	password
	)

Performs an authentication process.
If Soft MC requires authentication, you may do it using this function.
In order to authenticate call this method with the right Password as string.
.

Parameters

pKmapi	A pointer to KMApi object created by KMNewKMAPI()
password	The password (utf8 string) to authenticate with MC

Returns: KMResponse: Return code.
: MC does not return error in case of a wrong password

◆ Connect()

KMResponse Connect	(	KMApi *	pKmapi,
		LPCSTR	ip,
		int	port
	)

Connect to a specific IP and port.
the connect function tries to connect a specific IP:port. If it succeeds, return value is KMRet_OK.
It may return Timeout or connection refused.
On error, you should always call GetMCLastError and get detailed description from the socket.
.

Parameters

pKmapi	A pointer to KMApi object created by KMNewKMAPI()
ip	The IP string to connect to.
port	A port number.

Returns: KMResponse Return code.

◆ DetectDevices()

KMResponse DetectDevices	(	KMApi *	pKmapi,
		DWORD	Timout
	)

Detect device and wait for all to responses a specific timeout
This function will send a UDP message to all local networks
.

Parameters

pKmapi	A pointer to KMApi object created by KMNewKMAPI()
timeout	How long to wait for MC's responses

Returns: KMResponse Return code.

◆ DownloadFile()

KMResponse KMResponse DownloadFile	(	KMApi *	pKmapi,
		LPCSTR	sFilePath,
		LPCSTR	sFileName
	)

Downloads a file from Soft MC to a specific folder on the PC.
.

Parameters

pKmapi	A pointer to KMApi object created by KMNewKMAPI()
sFilePath	An existing folder name to download to
sFileName	A string with an existing filename to download from Soft MC

Returns: KMResponse Return code.

◆ ExecCommand()

KMResponse ExecCommand	(	KMApi *	pKmapi,
		LPCSTR	command,
		LPSTR	response,
		int	rspLength
	)

Executes command and waits for response
This method will execute a command and will return a string with the response from MC or an error code.
the function will return a timeout error if no response was receive before defined timeout
see SetTimeout for details.
Calling this function will force KMApi to wait for acknowledge and prompt frames before it returns
.

Parameters

pKmapi	A pointer to KMApi object created by KMNewKMAPI()
command	a utf8 string with command to run on Soft MC.
response	a buffer to copy response to.
rspLength	The length of the response buffer.

Returns: KMResponse Return code.
May be an error from MC or any other error such a timeout, buffer too small
In all cases you want to call GetLastError to understand what went wrong

◆ GetDeviceList()

MCDevice * GetDeviceList ( KMApi * pKmapi )

Get a list of last detected devices
Call this method after calling DetectDevices to get a list of detected device.
You may treat return value as an array of structs, or just move a pointer over the return buffer.
.

Parameters

pKmapi A pointer to KMApi object created by KMNewKMAPI()

Returns: returns a list of MCDevice struct. list ends with a MCDevice object where ip == ""

◆ GetMCLastError()

KMResponse GetMCLastError	(	KMApi *	pKmapi,
		int &	errorCode,
		LPSTR	sErrorMessage,
		int	msgLength
	)

Gets last error from socket or from soft MC
Gets the last error id and text.
Call this method after you receive an error code from any kmapai function
The method may return error text from soft MC or an error description from socket (last socket error)
.

Parameters

pKmapi	A pointer to KMApi object created by KMNewKMAPI()
errorCode	(Out value) The error code it may be KMRetCode or socket error type. (according to the error type)
sErrorMessage	a buffer to fill error text from socket or from soft MC
msgLength	buffer size

Returns: KMResponse: Return code. Buffer Too Small or OK

◆ KMNewKMAPI()

KMApi * KMNewKMAPI ( )

Creates and returns a new KMApi object. Use this method to create a new KMApi object (do not create it directly) you may use the class directly:

KMApi* kmapiObj = KMNewKMAPI();
if ( kmapiObj != NULL)
{
    connectRet = kmapiObj->Connect( ip, port );
    ...
    MCFreeKMApi(kmapiObj);
 }

or Like this (indirect)

KMApi* kmapiObj = KMNewKMAPI();
if ( kmapiObj != NULL)
{
    connectRet = Connect(kmapiObj, ip, port );
    ...
    MCFreeKMApi(kmapiObj);
}

Note: see MCFreeKMApi.

Returns: KMApi new Object.

◆ MCFreeKMApi()

MCFreeKMApi ( KMApi * pKmapi )

Releases KMApi object. Use this method to release KMApi object and free memory. Here is an example of creating, using and freeing kmapi object:

KMApi* kmapiObj = KMNewKMAPI();
if ( kmapiObj != NULL)
{
  //use kmapiObj...
  ...
  // release memory
  MCFreeKMApi(kmapiObj);
  // now kmapiObj is invalid.
}

Note: see KMNewKMApi.

Parameters

pKmapi A pointer to KMApi object created by KMNewKMAPI()

Returns: void

◆ SendCommand()

SendCommand	(	KMApi *	pKmapi,
		LPCSTR	command
	)

Sends a command but doesn't to wait for response.
The function send a command on Soft MC and returns.
.

Parameters

pKmapi	A pointer to KMApi object created by KMNewKMAPI()
command	a utf8 string with command to run on Soft MC.

Returns: KMResponse Return code.

◆ SetCallback()

void SetCallback	(	KMApi *	pKmapi,
		MCCallback *	pCallback
	)

Sets a pointer to a callback function.
Assign the callback function to receive async messages and other error status notifications.
.

Parameters

pKmapi	A pointer to KMApi object created by KMNewKMAPI()
pCallback	a pointer to a callback function: callback function should be in the form of `void` callback(int, LPCSTR)

◆ SetTimeout()

KMAPI_EXPORT void SetTimeout	(	KMApi *	pKmapi,
		KMTimeout	type,
		DWORD	timeout
	)

◆ UploadFile()

KMResponse UploadFile	(	KMApi *	pKmapi,
		LPCSTR	Filename
	)

Uploads a file to Soft MC
.

Parameters

pKmapi	A pointer to KMApi object created by KMNewKMAPI()
Filename	a full path (a utf8 string) of the file to upload to Soft MC

Returns: KMResponse Return code.

◆ void()

typedef void ( __stdcall MCCallback )

Variable Documentation

◆ LPCSTR

typedef LPCSTR

Definition at line 16 of file KMApi.h.

Classes

Macros

Functions

Variables

Macro Definition Documentation

◆ KMAPI_EXPORT

Function Documentation

◆ Authenticate()

◆ Connect()

◆ DetectDevices()

◆ DownloadFile()

◆ ExecCommand()

◆ GetDeviceList()

◆ GetMCLastError()

◆ KMNewKMAPI()

◆ MCFreeKMApi()

◆ SendCommand()

◆ SetCallback()

◆ SetTimeout()

◆ UploadFile()

◆ void()

Variable Documentation

◆ LPCSTR