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.

Called when the monitored application clears the statistics.

STOPBITS PARITY EVENTS PURGE MODEMSTATUS BAUDRATES PROVIDERTYPE PROVIDERCAPS PROVIDERSETTABLE DATABITS_ST STOPPARITY_ST