Serial Port Monitoring Control - ActiveX Component Library for RS232 Data Monitoring, API for Software Developers
Docs

INativeListener Interface

The high-performance event interface for native (C/C++) listeners.

This is a local interface, which means that it can only be used by the in-proc binary compatible clients, written, for example, in unmanaged C++ language.

After you first register your native listener with a call to IMonitoring.AddNativeListener method call, your native listener is queried for its capabilities through the call to the INativeListener.GetCaps method. If it returns ACCEPT_RAW (value is 1) value, the Serial Monitoring Control library will call the INativeListener.ProcessRAWBuffer with a pointer to a raw buffer. The raw buffer contains unparsed monitored data. This is the fastest method of getting data from the Serial Monitoring Control library. Using this method, you will be able to match the performance of the HHD Software Serial Monitor application. Note, that the raw listeners never get their OnXXX methods called. All data is passed to the ProcessRAWBuffer method and you must parse the data in your code. If you want the control to parse data for you, do not return ACCEPT_RAW value from the GetCaps method.

If your GetCaps method returns zero, the control will parse the monitored data and call one of the following OnXXX methods, described below. For performance reasons, if one of the methods ever returns E_NOTIMPL error code, the control will stop parsing the corresponding request type and stop calling not implemented methods for your listener object. If you have multiple listeners registered for the single monitoring object, and one of your listeners returns E_NOTIMPL for one of the events, the control still continues processing and calling the method for other registered listeners.

Note, that the GetCaps method is called immediately after you register your listener. The control will not call the method anymore, so you cannot change the type of the listener once it has been determined.

Declaration

// This interface is not available in scripting environment
// This interface is not available in managed environment
struct INativeListener : IDispatch
{
    // Methods
    DWORD ${GetCaps}();
    HRESULT ${ProcessRAWBuffer}(void * pData, DWORD Size);
    HRESULT ${OnConnection}(FILETIME * fTime, BOOL bConnected, LPCTSTR DeviceName);
    HRESULT ${OnOpen}(FILTIME * fTime, LPCTSTR ProcessName, ULONG ProcessId);
    HRESULT ${OnClosed}(FILETIME * fTime);
    HRESULT ${OnRead}(FILETIME * fTime, void * pData, ULONG Size);
    HRESULT ${OnWrite}(FILETIME * fTime, void * pData, ULONG Size);
    HRESULT ${OnTransmit}(FILETIME * fTime, void * pData, ULONG Size);
    HRESULT ${OnBaudRate}(FILETIME * fTime, ULONG BaudRate, BOOL bGet);
    HRESULT ${OnSerialChars}(FILETIME * fTime,
        UCHAR Eof,
        UCHAR Error,
        UCHAR Break,
        UCHAR Event,
        UCHAR Xon,
        UCHAR Xoff,
        BOOL bGet);
    HRESULT ${OnCommStatus}(FILETIME * fTime,
        ULONG Errors,
        ULONG HoldReasons,
        ULONG AmountInInQueue,
        ULONG AmountInOutQueue,
        BOOL EofReceived,
        BOOL WaitForImmediate);
    HRESULT ${OnDTRRTS}(FILETIME * fTime, BOOL DTR, BOOL RTS);
    HRESULT ${OnHandflow}(FILETIME * fTime,
        ULONG ControlHandShake,
        ULONG FlowReplace,
        ULONG XonLimit,
        ULONG XoffLimit,
        BOOL bGet);
    HRESULT ${OnLineControl}(FILETIME * fTime,
        ULONG WordLength,
        ${STOPBITS} StopBits,
        ${PARITY} Parity,
        BOOL bGet);
    HRESULT ${OnStats}(FILETIME * fTime,
        ULONG ReceivedCount,
        ULONG TransmittedCount,
        ULONG FrameErrorCount,
        ULONG SerialOverrunErrorCount,
        ULONG BufferOverrunErrorCount,
        ULONG ParityErrorCount);
    HRESULT ${OnTimeouts}(FILETIME * fTime,
        ULONG ReadIntervalTimeout,
        ULONG ReadTotalTimeoutMultiplier,
        ULONG ReadTotalTimeoutConstant,
        ULONG WriteTotalTimeoutMultiplier,
        ULONG WriteTotalTimeoutConstant,
        BOOL bGet);
    HRESULT ${OnWaitMask}(FILETIME * fTime, ${EVENTS} WaitMask, BOOL bGet);
    HRESULT ${OnPurge}(FILETIME * fTime, ${PURGE} Purge);
    HRESULT ${OnSetQueueSize}(FILETIME * fTime, ULONG InSize, ULONG OutSize);
    HRESULT ${OnSetBreak}(FILETIME * fTime, BOOL bOn);
    HRESULT ${OnDTR}(FILETIME * fTime, BOOL bSet);
    HRESULT ${OnReset}(FILETIME * fTime);
    HRESULT ${OnRTS}(FILETIME * fTime, BOOL bSet);
    HRESULT ${OnXOFF}(FILETIME * fTime);
    HRESULT ${OnXON}(FILETIME * fTime);
    HRESULT ${OnWaitOnMask}(FILETIME * fTime, ${EVENTS} WaitMask);
    HRESULT ${OnGetModemStatus}(FILETIME * fTime, ${MODEMSTATUS} ModemStatus);
    HRESULT ${OnGetProperties}(FILETIME * fTime,
        USHORT PacketLength,
        USHORT PacketVersion,
        ULONG MaxTxQueue,
        ULONG MaxRxQueue,
        ULONG CurrentTxQueue,
        ULONG CurrentRxQueue,
        ${BAUDRATES} MaxBaudRate,
        ${PROVIDERTYPE} ProviderType,
        ${PROVIDERCAPS} ProviderCaps,
        ${PROVIDERSETTABLE} ProviderSettableParams,
        ${BAUDRATES} SettableBaudRates,
        ${DATABITS_ST} SettableData,
        ${STOPPARITY_ST} SettableStopParity);
    HRESULT ${OnClearStats}(FILETIME * fTime);
};

INativeListener Methods

GetCaps

// This method is not available in scripting environment
// This method is not available in managed environment
DWORD GetCaps();

Return the listener capabilities to the Monitor. If your listener returns ACCEPT_RAW value, it is considered the raw listener. The library will not parse the monitored data for a raw listener, instead, it will pass all data (buffered) to the INativeListener.ProcessRAWBuffer method.

This method is called only once.

ProcessRAWBuffer

// This method is not available in scripting environment
// This method is not available in managed environment
HRESULT ProcessRAWBuffer(void * pData, DWORD Size);
pData
Pointer to a raw data.
Size
The size of the buffer pointed to by the pData parameter.

Called by the control to process the monitored events at the lowest possible level. You will find the documentation for the raw processing in a separate topic.

OnConnection

// This method is not available in scripting environment
// This method is not available in managed environment
HRESULT OnConnection(FILETIME * fTime, BOOL bConnected, LPCTSTR DeviceName);
fTime
The time of the event.
bConnected
The connection state. Indicates whether the monitor is connecting to the device, or disconnecting from it. See the ConnectionState enumeration for more information.
DeviceName
Pointer to the null-terminated name of the serial device the monitor is connecting to (disconnecting from).

Called when the control attaches/detaches itself to/from the serial device.

OnOpen

// This method is not available in scripting environment
// This method is not available in managed environment
HRESULT OnOpen(FILTIME * fTime, LPCTSTR ProcessName, ULONG ProcessId);
fTime
The time of the event.
ProcessName
Pointer to the null-terminated string containing the name of the process opening the device.
ProcessId
The process identifier.

Called when the device is opened by monitored application.

OnClosed

// This method is not available in scripting environment
// This method is not available in managed environment
HRESULT OnClosed(FILETIME * fTime);
fTime
The time of the event.

Called when the device is closed by monitored application.

OnRead

// This method is not available in scripting environment
// This method is not available in managed environment
HRESULT OnRead(FILETIME * fTime, void * pData, ULONG Size);
fTime
The time of the event.
pData
Pointer to the data read by the application in one function call.
Size
The size of the buffer pointed to by the pData parameter.

Called when the monitored application is reading data.

OnWrite

// This method is not available in scripting environment
// This method is not available in managed environment
HRESULT OnWrite(FILETIME * fTime, void * pData, ULONG Size);
fTime
The time of the event.
pData
Pointer to the data written by the application in one function call.
Size
The size of the buffer pointed to by the pData parameter.

Called when the monitored application is writing data.

OnTransmit

// This method is not available in scripting environment
// This method is not available in managed environment
HRESULT OnTransmit(FILETIME * fTime, void * pData, ULONG Size);
fTime
The time of the event.
pData
Pointer to the data transmitted by the application in one function call.
Size
The size of the buffer pointed to by the pData parameter.

Called when the monitored application is transmitting data.

OnBaudRate

// This method is not available in scripting environment
// This method is not available in managed environment
HRESULT OnBaudRate(FILETIME * fTime, ULONG BaudRate, BOOL bGet);
fTime
The time of the event.
BaudRate
Baud rate to set or get.
bGet
TRUE if application is reading current baud rate, or FALSE if it is changing it.

Called when the monitored application retrieves/sets current baud rate.

OnSerialChars

// This method is not available in scripting environment
// This method is not available in managed environment
HRESULT OnSerialChars(FILETIME * fTime,
    UCHAR Eof,
    UCHAR Error,
    UCHAR Break,
    UCHAR Event,
    UCHAR Xon,
    UCHAR Xoff,
    BOOL bGet);
fTime
The time of the event.
Eof
EOF character.
Error
ERROR character.
Break
BREAK character.
Event
EVENT character.
Xon
XON character.
Xoff
XOFF character.
bGet
TRUE if application is reading special characters, or FALSE if it is changing them.

Called when the monitored application retrieves/sets special serial characters.

OnCommStatus

// This method is not available in scripting environment
// This method is not available in managed environment
HRESULT OnCommStatus(FILETIME * fTime,
    ULONG Errors,
    ULONG HoldReasons,
    ULONG AmountInInQueue,
    ULONG AmountInOutQueue,
    BOOL EofReceived,
    BOOL WaitForImmediate);
fTime
The time of the event.
Errors
The number of errors for the port.
HoldReasons
The number of hold reasons on the port.
AmountInInQueue
Amount of data in the input queue, in bytes.
AmountInOutQueue
Amount of data in the output queue, in bytes.
EofReceived
TRUE if the EOF has been received.
WaitForImmediate
TRUE if the port is in wait state.

Called when the monitored application reads the comm port status.

OnDTRRTS

// This method is not available in scripting environment
// This method is not available in managed environment
HRESULT OnDTRRTS(FILETIME * fTime, BOOL DTR, BOOL RTS);
fTime
The time of the event.
DTR
DTR line state.
RTS
RTS line state.

Called when the monitored application retrieves DTR and RTS line states.

OnHandflow

// This method is not available in scripting environment
// This method is not available in managed environment
HRESULT OnHandflow(FILETIME * fTime,
    ULONG ControlHandShake,
    ULONG FlowReplace,
    ULONG XonLimit,
    ULONG XoffLimit,
    BOOL bGet);
fTime
The time of the event.
ControlHandShake
ControlHandShake
FlowReplace
FlowReplace
XonLimit
XonLimit
XoffLimit
XoffLimit
bGet
TRUE if the application reads the handshake information or FALSE otherwise.

OnLineControl

// This method is not available in scripting environment
// This method is not available in managed environment
HRESULT OnLineControl(FILETIME * fTime,
    ULONG WordLength,
    ${STOPBITS} StopBits,
    ${PARITY} Parity,
    BOOL bGet);
fTime
The time of the event.
WordLength
Byte size.
StopBits
Stop bits. One of the values from the STOPBITS enumeration.
Parity
Parity. One of the values from the PARITY enumeration.
bGet
TRUE if the application reads the line control settings, FALSE if writes it.

Called when the monitored application retrieves/sets the line control options (such as stop bits, parity and word length).

OnStats

// This method is not available in scripting environment
// This method is not available in managed environment
HRESULT OnStats(FILETIME * fTime,
    ULONG ReceivedCount,
    ULONG TransmittedCount,
    ULONG FrameErrorCount,
    ULONG SerialOverrunErrorCount,
    ULONG BufferOverrunErrorCount,
    ULONG ParityErrorCount);
fTime
The time of the event.
ReceivedCount
The number of received bytes.
TransmittedCount
The number of transmitted bytes.
FrameErrorCount
The number of frame errors.
SerialOverrunErrorCount
The number of serial overrun errors.
BufferOverrunErrorCount
The number of buffer overrun errors.
ParityErrorCount
The number of parity errors.

Called when the monitored application reads port statistics.

OnTimeouts

// This method is not available in scripting environment
// This method is not available in managed environment
HRESULT OnTimeouts(FILETIME * fTime,
    ULONG ReadIntervalTimeout,
    ULONG ReadTotalTimeoutMultiplier,
    ULONG ReadTotalTimeoutConstant,
    ULONG WriteTotalTimeoutMultiplier,
    ULONG WriteTotalTimeoutConstant,
    BOOL bGet);
fTime
The time of the event.
ReadIntervalTimeout
Read interval timeout.
ReadTotalTimeoutMultiplier
Read total timeout multiplier.
ReadTotalTimeoutConstant
Read total timeout constant.
WriteTotalTimeoutMultiplier
Write total timeout multiplier.
WriteTotalTimeoutConstant
Write total timeout constant.
bGet
TRUE if the application reads this information or FALSE otherwise.

Called when the monitored application retrieves/sets port timeouts.

OnWaitMask

// This method is not available in scripting environment
// This method is not available in managed environment
HRESULT OnWaitMask(FILETIME * fTime, ${EVENTS} WaitMask, BOOL bGet);
fTime
The time of the event.
WaitMask
The wait mask. See the EVENTS enumeration.
bGet
TRUE if the monitored application reads the wait mask or FALSE otherwise.

Called when the monitored application retrieves/sets the wait mask.

OnPurge

// This method is not available in scripting environment
// This method is not available in managed environment
HRESULT OnPurge(FILETIME * fTime, ${PURGE} Purge);
fTime
The time of the event.
Purge
The bit mask indicating what data to purge. See the PURGE enumeration for more information.

Called when the monitored application purges the port.

OnSetQueueSize

// This method is not available in scripting environment
// This method is not available in managed environment
HRESULT OnSetQueueSize(FILETIME * fTime, ULONG InSize, ULONG OutSize);
fTime
The time of the event.
InSize
The size of the input queue.
OutSize
The size of the output queue.

Called when the monitored application sets queue sizes.

OnSetBreak

// This method is not available in scripting environment
// This method is not available in managed environment
HRESULT OnSetBreak(FILETIME * fTime, BOOL bOn);
fTime
The time of the event.
bOn
TRUE if application sets the break signal, or FALSE otherwise.

Called when the monitored application sets/resets the break signal.

OnDTR

// This method is not available in scripting environment
// This method is not available in managed environment
HRESULT OnDTR(FILETIME * fTime, BOOL bSet);
fTime
The time of the event.
bSet
TRUE if the application sets the DTR line state, or FALSE if the application resets it.

Called when the monitored application sets/resets DTR line state.

OnReset

// This method is not available in scripting environment
// This method is not available in managed environment
HRESULT OnReset(FILETIME * fTime);
fTime
The time of the event.

Called when the monitored application resets the port.

OnRTS

// This method is not available in scripting environment
// This method is not available in managed environment
HRESULT OnRTS(FILETIME * fTime, BOOL bSet);
fTime
The time of the event.
bSet
TRUE if the application sets the RTS line state, or FALSE if the application resets it.

Called when the monitored application sets/resets RTS line state.

OnXOFF

// This method is not available in scripting environment
// This method is not available in managed environment
HRESULT OnXOFF(FILETIME * fTime);
fTime
The time of the event.

Called when the monitored application sends the XOFF character.

OnXON

// This method is not available in scripting environment
// This method is not available in managed environment
HRESULT OnXON(FILETIME * fTime);
fTime
The time of the event.

Called when the monitored application sends the XON character.

OnWaitOnMask

// This method is not available in scripting environment
// This method is not available in managed environment
HRESULT OnWaitOnMask(FILETIME * fTime, ${EVENTS} WaitMask);
fTime
The time of the event.
WaitMask
The wait mask to wait. See the EVENTS enumeration for more information.

Called when the monitored application waits on mask.

OnGetModemStatus

// This method is not available in scripting environment
// This method is not available in managed environment
HRESULT OnGetModemStatus(FILETIME * fTime, ${MODEMSTATUS} ModemStatus);
fTime
The time of the event.
ModemStatus
The modem status is returned as a combination of flags in the MODEMSTATUS enumeration.

Called when the monitored application reads the modem status.

OnGetProperties

// This method is not available in scripting environment
// This method is not available in managed environment
HRESULT OnGetProperties(FILETIME * fTime,
    USHORT PacketLength,
    USHORT PacketVersion,
    ULONG MaxTxQueue,
    ULONG MaxRxQueue,
    ULONG CurrentTxQueue,
    ULONG CurrentRxQueue,
    ${BAUDRATES} MaxBaudRate,
    ${PROVIDERTYPE} ProviderType,
    ${PROVIDERCAPS} ProviderCaps,
    ${PROVIDERSETTABLE} ProviderSettableParams,
    ${BAUDRATES} SettableBaudRates,
    ${DATABITS_ST} SettableData,
    ${STOPPARITY_ST} SettableStopParity);
fTime
The time of the event.
PacketLength
The packet length, in bytes.
PacketVersion
The packet version.
MaxTxQueue
Maximum transmit queue size, in bytes.
MaxRxQueue
Maximum receive queue size, in bytes.
CurrentTxQueue
Current transmit queue size, in bytes.
CurrentRxQueue
Current receive queue size, in bytes.
MaxBaudRate
Maximum baud rate.
ProviderType
Provider type. See the PROVIDERTYPE enumeration for more information.
ProviderCaps
Provider capabilities. See the PROVIDERCAPS enumeration for more information.
ProviderSettableParams
Provider settable parameters. Indicates what port parameters may be set for a given device. See the PROVIDERSETTABLE enumeration for more information.
SettableBaudRates
The bit mask indicating what baud rates are supported for a given device. See the BAUDRATES enumeration for more information.
SettableData
The bit mask indicating what data bits are supported for a given device. See the DATABITS_ST enumeration for more information.
SettableStopParity
The bit mask indicating what stop bits and parity are supported for a given device. See the STOPPARITY_ST enumeration for more information.

Called when the monitored application retrieves the comm properties.

OnClearStats

// This method is not available in scripting environment
// This method is not available in managed environment
HRESULT OnClearStats(FILETIME * fTime);
fTime
The time of the event.