Introduction, NkComPort_Close, NkComPort_GetConnectionDetails, NkComPort_IsConnected, NkComPort_ListPorts, NkComPort_Open, NkComPort_Read, NkComPort_ReadLine, NkComPort_SelectPortDialog, NkComPort_Write, NkComPort_WriteLine

Introduction

Description 

 Introduction();

Import (“NkComPort.dll”);

The functions in the NkComPort.dll library implement sending and receiving data through a COM port connection. Run the macro ~nis\macros\NkComPort.mac to load the library in NIS. The example macro: ~nis\Examples\NkComPortDemo.mac illustrates the use of the commands. The example macro includes an Arduino sketch that can be used for the proof-of-principle test.

Example:

# fragment from ~nis\Examples\NkComPortDemo.mac:
...
result = NkComPort_Open(&NCPD_port,buf);
if(result < 0)
{
NCPD_Error(result);
return 0;
}
NCPD_Log("port opened.","");
while(NCPD_ReadLine()) {}
...

NkComPort_Open

Description 

 NkComPort_Open(
   int64  port_handle,
   char *port_and_protocol
);

Opens the specified port. The function returns 1 on success, another value on failure. The port_and_protocol string specifies the port name, optionally followed by the communication details. If the communication details are not present, the default values are used as set in the Windows Device Manager Properties Port Settings dialog.

Parameters

int64 port_handle

The address of the handle for the port.

char *port_and_protocol

the port name, optionally followed by a ':' and the command separated communication details (e.g. “COM3:9600,n,8,1,n”).

baudrate	speed of communication in bits-per-second (e.g. 9600 bps)
parity	n,o,e,m,s (none,odd,even,mark,space)
data-bits	7,8
stop-bits	1,2
flow-control	n,x,p,b (none, xonxoff, rtscts, both)
timeout	in ms

NkComPort_IsConnected

Description 

 NkComPort_IsConnected(
   int64  port_handle
);

Returns if the port is successfully opened. The function returns 1 when connected, 0 otherwise.

Parameters

int64 port_handle

The address of the handle for the port.

NkComPort_GetConnectionDetails

Description 

 NkComPort_GetConnectionDetails(
   int64  port_handle,
   char *Buffer,
   long  count
);

Fills the buffer with the name and communication details of the current connection.

Parameters

int64 port_handle

The address of the handle for the port.

char *Buffer

The string buffer.

long count

The size of the string buffer.

NkComPort_Close

Description 

 NkComPort_Close(
   int64  port_handle
);

Closes the port. The port_handle variable is set to 0.

Parameters

int64 port_handle

The address of the handle for the port.

NkComPort_Read

Description 

 NkComPort_Read(
   int64  port_handle,
   char *Buffer,
   long  count
);

Reads the specified number of characters from the port. The function returns as soon as the specified number of characters were received or when the timeout period expires. It returns the number of characters read, -1 in case of an error. The received ASCII characters are converted to the UNICODE characters NIS uses.

Parameters

int64 port_handle

The address of the handle for the port.

char *Buffer

The string buffer.

long count

The size of the string buffer.

NkComPort_ReadLine

Description 

 NkComPort_ReadLine(
   int64  port_handle,
   char *Buffer,
   long  count
);

Reads the specified number of characters from the port up to a carriage-return character \r (13). The function returns as soon as the specified number of characters were received, a newline character was received or when the timeout period expires. It returns the number of characters read, -1 in case of an error. The received ASCII characters are converted to the UNICODE characters NIS uses.

Parameters

int64 port_handle

The address of the handle for the port.

char *Buffer

The string buffer.

long count

The size of the string buffer.

NkComPort_Write

Description 

 NkComPort_Write(
   int64  port_handle,
   char *Buffer,
   long  count_to_write
);

Writes the specified number of characters to the port. If count is 0, the full string is send. The count or string length must be 1024 or lower. It returns the number of characters written, -1 in case of an error. The UNICODE characters NIS uses are converted and send as ASCII characters to the port.

Parameters

int64 port_handle

The address of the handle for the port.

char *Buffer

The string buffer.

long count_to_write

The number of characters to write or 0 to write the full string.

NkComPort_WriteLine

Description 

 NkComPort_WriteLine(
   int64  port_handle,
   char *Buffer
);

Writes the string to the port. If not present, a trailing carriage-return \r (13) is appended. The length must be 1024 or lower. It returns the number of characters written, -1 in case of an error. The UNICODE characters NIS uses are converted and send as ASCII characters to the port.

Parameters

int64 port_handle

The address of the handle for the port.

char *Buffer

The string buffer.

NkComPort_ListPorts

Description 

 NkComPort_ListPorts(
   int64  port_handle,
   char *Buffer,
   long  count
);

Fills the buffer with the information on the available COM ports. The information on each port has three fields separated by a tab character \t (9) and is terminated by a newline \n (10) character: <name>\t<friendly-name>\t<VID, PID>\n.

Parameters

int64 port_handle

The address of the handle for the port.

char *Buffer

The string buffer.

long count

The size of the string buffer.

NkComPort_SelectPortDialog

Description 

 NkComPort_SelectPortDialog(
   int64  parent,
   char *Buffer,
   long  count
);

Shows a dialog to select a COM port and set the communication details. It returns the port and protocol in the buffer for use in a call to NkComPort_Open().

Parameters

int64 parent

The handle of the parent window.

char *Buffer

The string buffer.

long count

The size of the string buffer.