Introduction, NkSocket_Close, NkSocket_Connect, NkSocket_GetErrorDescription, NkSocket_IsConnected, NkSocket_IsListening, NkSocket_IsValid, NkSocket_Listen, NkSocket_Read, NkSocket_ReadLine, NkSocket_ReadLineA, NkSocket_Write, NkSocket_WriteLine, NkSocket_WriteLineA

Introduction

Description 

 Introduction();

Import ("NkSocket.dll");

The functions in the NkSocket.dll library implement sending and receiving data through a TCP/IP connection. Run the macro ~nis\macros\NkSocket.mac to load the library in NIS. The example macros ~nis\Examples\NkSocketServerDemo.mac and ~\nis\Examples\NkSocketClientDemo.mac illustrate the use of the commands. The Server demo starts listening on a socket. The Client demo connects to the server socket. Start both demo macros, press the 'Listen' button on the server dialog and press the 'Connect' button on the client dialog.

Example:

# fragment from ~nis\Examples\NkSocketServerDemo.mac:
...
result = NkSocket_Listen(&NSSD_socket,buf);
if(result < 0)
{
NSSD_Error(result);
NkDialog_SendMessage(NSSD_dlg,"btnListen",BM_SETCHECK,0,0);
return 0;
}
NkSocket_IsListening(NSSD_socket,buf,128);
NSSD_SetStatus("listening on: ",buf);
...
# fragment from ~nis\Examples\NkSocketClientDemo.mac:
...
result = NkSocket_Connect(&NSCD_socket,buf);
if(result < 0)
{
NSCD_Error(result);
NkDialog_SendMessage(NSCD_dlg,"btnConnect",BM_SETCHECK,0,0);
return 0;
}
NkSocket_IsConnected(NSCD_socket,buf,128);
NSCD_SetStatus("connected to: ",buf);
...

NkSocket_Listen

Description 

 NkSocket_Listen(
   int64 *phSocket,
   char *port_or_service
);

Starts listening on the specified port (e.g. “12345”) or UDP service name (e.g. “NIS_SERVER”). Client programs can connect to this socket. When listing on a port, the client must specify the same port number. When the client is running on a different PC, the IP-address of this server must be specified (e.g. “10.12.64.4:12345”). When listing on an UDP service, the client will broadcast an UDP message on the local network to located the ip-address and port to connect to. A negative return value indicates that an error occurred. Use the NkSocket_GetErrorDescription function to get a description of the error.

Parameters

int64 *phSocket

The address of the variable for the handle of the socket.

char *port_or_service

The port (e.g. “12345”), ip-address:port (e.g. “127.0.0.1:12345”) or UDP service name (e.g. “NIS_SERVER”).

NkSocket_IsListening

Description 

 NkSocket_IsListening(
   char *port_or_service,
   long  count
);

Returns 1 if the service is listening and fills the port_or_service buffer with the details of the server and port.

Parameters

char *port_or_service

The port (e.g. “12345”), ip-address:port (e.g. “127.0.0.1:12345”) or UDP service name (e.g. “NIS_SERVER”).

long count

The size of the string buffer.

NkSocket_Connect

Description 

 NkSocket_Connect(
   int64 *phSocket,
   char *port_or_service
);

Connects this client to a service running on a server. Specify the service name or port number that the server listens to. For remote servers the port must be preceded by the server ip-address (e.g. “10.12.64.4:12345”). A negative return value indicates that an error occurred. Use the NkSocket_GetErrorDescription function to get a description of the error.

Parameters

int64 *phSocket

The address of the variable for the handle of the socket.

char *port_or_service

The port (e.g. “12345”), ip-address:port (e.g. “127.0.0.1:12345”) or UDP service name (e.g. “NIS_SERVER”).

NkSocket_IsConnected

Description 

 NkSocket_IsConnected(
   int64  hsocket,
   char *port_or_service,
   long  count
);

Returns 1 if the connection with the remote partner is established. It fills the 'port_or_service' buffer with the address of the remote partner.

Parameters

int64 hsocket

The socket handle.

char *port_or_service

The port (e.g. “12345”), ip-address:port (e.g. “127.0.0.1:12345”) or UDP service name (e.g. “NIS_SERVER”).

long count

The size of the string buffer.

NkSocket_Close

Description 

 NkSocket_Close(
   int64 *phSocket
);

Terminates the connection with the remote partner.

Parameters

int64 *phSocket

The address of the variable for the handle of the socket.

NkSocket_Write

Description 

 NkSocket_Write(
   int64  hsocket,
   byte *data,
   long  count
);

Writes data to the remote partner. A negative return value indicates that an error occurred. Use the NkSocket_GetErrorDescription function to get a description of the error.

Parameters

int64 hsocket

The socket handle.

byte *data

The buffer.

long count

The size of the string buffer.

NkSocket_Read

Description 

 NkSocket_Read(
   int64  hsocket,
   byte *data,
   long  count,
   long  timeout
);

Reads data from the remote partner. It returns the number of bytes read. A negative return value indicates that an error occurred. Use the NkSocket_GetErrorDescription function to get a description of the error.

Parameters

int64 hsocket

The socket handle.

byte *data

The buffer.

long count

The size of the string buffer.

long timeout

The timeout period in milliseconds.

NkSocket_WriteLine

Description 

 NkSocket_WriteLine(
   int64  hsocket,
   char *line
);

Writes the line to the remote server. If not present, a terminating cariage-return character is appended. A negative return value indicates that an error occurred. Use the NkSocket_GetErrorDescription function to get a description of the error.

Parameters

int64 hsocket

The socket handle.

char *line

The line.

NkSocket_ReadLine

Description 

 NkSocket_ReadLine(
   int64  hsocket,
   char *line,
   long  timeout
);

Reads a line to the remote server. The function returns when a cariage-return character is read, a A negative return value indicates that an error occurred. Use the NkSocket_GetErrorDescription function to get a description of the error.

Parameters

int64 hsocket

The socket handle.

char *line

The line.

long timeout

The timeout period in milliseconds.

NkSocket_WriteLineA

Description 

 NkSocket_WriteLineA(
   int64  hsocket,
   char *line
);

Writes the multi-byte line to a remote server that communicates in 8-bit character strings (ASCII, multi-byte). NIS strings must be converted to char8 using the function WideCharToMultiByte(). If not present, a terminating cariage-return character is appended. A negative return value indicates that an error occurred. Use the NkSocket_GetErrorDescription function to get a description of the error.

Parameters

int64 hsocket

The socket handle.

char *line

The line.

NkSocket_ReadLineA

Description 

 NkSocket_ReadLineA(
   int64  hsocket,
   char *line,
   long  timeout
);

Reads a line to a remote server that communicates in 8-bit character strings (ASCII, multi-byte). For NIS the string must be converted to 16-bit character strings (UNICODE, wide-char) using the function MultiByteToWideChar(). The function returns when a cariage-return character is read, a A negative return value indicates that an error occurred. Use the NkSocket_GetErrorDescription function to get a description of the error.

Parameters

int64 hsocket

The socket handle.

char *line

The line.

long timeout

The timeout period in milliseconds.

NkSocket_IsValid

Description 

 NkSocket_IsValid(
   int64  hsocket
);

Returns if the socket handle is valid.

Parameters

int64 hsocket

The socket handle.

NkSocket_GetErrorDescription

Description 

 NkSocket_GetErrorDescription(
   int  iSocketError,
   char *Buffer,
   long  count
);

Fills the buffer with a description of the error.

Parameters

int iSocketError

A negative error code returned by any NkSocket_ function.

char *Buffer

The string buffer.

long count

The size of the string buffer.