Application Programming Interface

Application Programming Interface - Eric's TelNet98

The Eric's TelNet98 Application Programming Interface ETNAPI.DLL provides the following functions to exchange data between TelNet98 sessions and your Windows applications. To use the functions of the ETNAPI.DLL you need to import them into your programming language environment. Please refer to the documentation of your Software Development Kit (SDK) on how to import a DLL.

etnEnableInput

The etnEnableInput function enables or disables mouse and keyboard input to the specified session window. When input is disabled, the window does not receive input such as mouse clicks and key presses. When input is enabled, the window receives all input.

BOOL WINAPI etnEnableInput(
HWND hSession,
BOOL bEnable
);

Parameters

hSession: Identifies the session to be enabled or disabled. The etnObtainHandle function returns this handle.

bEnable: Specifies whether to enable or disable the session. If this parameter is TRUE, the window is enabled. If the parameter is FALSE, the window is disabled.

etnIsSession

The etnIsSession function determines whether the specified window handle identifies an existing session window.

BOOL WINAPI etnIsSession(
HWND hSession
);

Return Values

If the handle identifies an existing session window, the return value is nonzero. If the handle does not identify an existing session window, the return value is zero.

etnObtainHandle

The etnObtainHandle function returns a handle to an existing TelNet98 session.

HWND WINAPI etnObtainHandle(
LPCTSTR lpSessionName,
DWORD dwMilliseconds
);

Parameters

lpSessionName: Points to a null-terminated string that specifies the name of the session. This parameter can be NULL for any session.
dwMilliseconds: Specifies the time-out interval, in milliseconds. The function returns if the interval elapses, even if nothing was opened. If dwMilliseconds is INFINITE, the function's time-out interval never elapses.

etnReceiveData

The etnReceiveData function reads data from a running TelNet98 session.

BOOL WINAPI etnReceiveData(
  HWND hSession,
  LPBYTE lpData,
  LPDWORD lpcbData,
  DWORD dwMilliseconds
);

Parameters

hSession: Identifies the session from which to read. The etnObtainHandle function returns this handle.
lpData: Points to a buffer that receives the incoming data.
lpcbData: Points to a variable that specifies the size, in bytes, of the buffer pointed to by the lpData parameter. When the function returns, the variable pointed to by the lpcbData parameter contains the number of bytes stored in the buffer.
dwMilliseconds: Specifies the time-out interval, in milliseconds. The function returns if the interval elapses, even if nothing was received. If dwMilliseconds is INFINITE, the function's time-out interval never elapses.

Remarks

If no incoming data is available, the etnReceiveData function blocks and waits for data to arrive. The data is copied into the buffer, but is not removed from the input queue. If the message is larger than the buffer specified, the buffer is filled with the first part of the message, and the excess data is lost. After the data has been read, the session suspends the execution to give the calling process time, to prepare for the next call. The default time interval for which the execution is suspended is 10 milliseconds. This value can be adjusted with the etnSetDelay function.

etnRegisterCallback

The etnRegisterCallback function associates a function that the session calls asynchronously to notify the application, whenever the session receives incoming data.

BOOL WINAPI etnRegisterCallback(
HWND hSession,
ETNDATAPROC lpDataProc
);

Parameters

hSession: Identifies the session to be associated with the callback function. The etnObtainHandle function returns this handle.
lpDataProc: Pointer to the function to be called when the session receives incoming data. The ETNDATAPROC type defines a pointer to this callback function. DataProc is a placeholder for the application-defined function name.

Syntax:

VOID CALLBACK DataProc(
  HWND hSession,
  LPBYTE lpData,
  DWORD cbData
);

// handle to session
// address of buffer
// the number of bytes stored in lpData

If lpDataProc is NULL, an associated callback function is unregistered.

Remarks

When you specify the ETNDATAPROC callback function, the default window procedure calls the callback function. Therefore, you need to dispatch messages in the calling thread.

etnReleaseHandle

The etnReleaseHandle function releases a session handle.

BOOL WINAPI etnReleaseHandle(
HWND hSession
);

etnSendData

The etnSendData function sends data to the specified session.

BOOL WINAPI etnSendData(
  HWND hSession,
  LPBYTE lpData,
  DWORD cbData
);

Parameters

hSession: Specifies the session handle.
lpData: Points to a buffer containing the data to be sent to the session.
cbData: Specifies the number of bytes to send to the session. The maximum allowed value for cbData is ETNBUFSIZ.

etnSetDelay

The etnSetDelay function adjusts the time interval, for which the session is suspended after a call to the etnReceiveData function.

VOID WINAPI etnSetDelay(
DWORD dwMilliseconds
);