# NGuestXLib::_INGuestXCtrlEvents Interface Reference

Event handler interface for INGuestX class. More...

List of all members.

## Public Member Functions
HRESULT | OnOpenPre ()
HRESULT | OnOpenPost ([in] VARIANT_BOOL Ok)
HRESULT | OnClosePre ()
HRESULT | OnClosePost ([in] VARIANT_BOOL Ok)
HRESULT | OnConnectPre ()
HRESULT | OnConnectPost ([in] VARIANT_BOOL Ok)
HRESULT | OnDisconnectPre ()
HRESULT | OnDisconnectPost ()
HRESULT | OnBeginSessionPre ([in] LONG Type)
HRESULT | OnBeginSessionPost ([in] LONG Type,[in] VARIANT_BOOL Ok)
HRESULT | OnEndSessionPre ([in] LONG Type)
HRESULT | OnEndSessionPost ([in] LONG Type,[in] VARIANT_BOOL Ok)
HRESULT | OnSessionStarted ([in] LONG Type)
HRESULT | OnEndedByHost ()
HRESULT | OnConnectionLost ()
HRESULT | OnLoginPassword ([in] LONG Reason,[in] INGuestXEventParam *EventParam)
HRESULT | OnLoginNetOp ([in] LONG Reason,[in] VARIANT_BOOL bNss,[in] INGuestXEventParam *EventParam)
HRESULT | OnLoginWindows ([in] LONG Reason,[in] INGuestXEventParam *EventParam)
HRESULT | OnLoginLdap ([in] LONG Reason,[in] INGuestXEventParam *EventParam)
HRESULT | OnLoginRsa ([in] LONG Reason,[in] LONG Shadow,[in] INGuestXEventParam *EventParam)
HRESULT | OnLoginFailed ([in] LONG Reason)
HRESULT | OnEnterRsaPincode ([in] LONG Reason,[in] LONG Mode,[in] BSTR SuggestedPin,[in] LONG MinLen,[in] LONG MaxLen,[in] VARIANT_BOOL AllowNonNumeric,[in] INGuestXEventParam *EventParam)
HRESULT | OnHostScreenSizeInfo ([in] LONG Width,[in] LONG Height)
HRESULT | OnHostMultiGuestInfo ([in] LONG Event,[in] LONG NumGuests,[in] LONG Error)
HRESULT | OnEraseBackground ([in] LONG hWnd,[in] LONG hDC,[in] INGuestXEventParam *EventParam)
HRESULT | OnChatMessageIn ([in] BSTR Msg,[in] INGuestXFont *Font,[in] INGuestXEventParam *EventParam)
HRESULT | OnChatMessageOut ([in] BSTR Msg,[in] INGuestXFont *Font,[in] INGuestXEventParam *EventParam)
HRESULT | OnErrorMsg ([in] LONG MsgNo,[in] BSTR Message,[in] INGuestXEventParam *EventParam)
HRESULT | OnInfoMsg ([in] LONG MsgNo,[in] BSTR Message,[in] INGuestXEventParam *EventParam)
HRESULT | OnConnectWindow ([in] INGuestXEventParam *EventParam)
HRESULT | OnStatusWindow ([in] INGuestXEventParam *EventParam)
HRESULT | OnPropertyWindow ([in] INGuestXEventParam *EventParam)
HRESULT | OnChatUIStart ([in] INGuestXEventParam *EventParam)
HRESULT | OnChatUIEnd ()
HRESULT | OnInfoWindow ([in] LONG Reason,[in] INGuestXEventParam *EventParam)
HRESULT | OnLicenseRequired ([in] LONG MsgNo,[in] BSTR Message,[in] INGuestXEventParam *EventParam)

## Detailed Description

Event handler interface for INGuestX class.

## Member Function Documentation

HRESULT NGuestXLib::_INGuestXCtrlEvents::OnOpenPre | ( |  | ) |

Fired when the NGA instance is about to open by INGuestXCtrl::Open() method.

The event is not fired when the instance is already opened when INGuestXCtrl::Open() is called.

The event is always followed by OnClosePost() event.

When the event is fired the INGuestXCtrl::IsOpen property is always false.

HRESULT NGuestXLib::_INGuestXCtrlEvents::OnOpenPost | ( | [in] VARIANT_BOOL | Ok | ) |

Fired when the NGA instance has been opened by INGuestXCtrl::Open() method.

When the event is fired INGuestXCtrl::IsOpen property is true if the instance was opened successfully. It is safe to call the INGuestXCtrl::Close() in response to OnOpenPost(true).

Parameters:

  | Ok | - status of Open request true - the NGA was opened successfully false - failed to open NGA instance.

HRESULT NGuestXLib::_INGuestXCtrlEvents::OnClosePre | ( |  | ) |

Fired when the NGA instance is about to close by INGuestXCtrl::Close() method.

The event is not fired when the instance is already closed when INGuestXCtrl::Close() is called.

There will be OnClosePost() event fired for each OnClosePre() event.

When the event is fired INGuestXCtrl::IsOpen is always true.

HRESULT NGuestXLib::_INGuestXCtrlEvents::OnClosePost | ( | [in] VARIANT_BOOL | Ok | ) |

Fired when the NGA instance has been closed by INGuestXCtrl::Close() method.

When the event is fired INGuestXCtrl::IsOpen property is false if the instance was closed successfully. It is safe to call the INGuestXCtrl::Open() in response to OnClosePost(true).

Parameters:

  | Ok | - status of Close() request true - the NGA was closed successfully false - failed to close NGA.

HRESULT NGuestXLib::_INGuestXCtrlEvents::OnConnectPre | ( |  | ) |

Fired if a new connection should be established in response to INGuestXCtrl::BeginSession() function.

The event is fired before any long lasting network operations started.

HRESULT NGuestXLib::_INGuestXCtrlEvents::OnConnectPost | ( | [in] VARIANT_BOOL | Ok | ) |

Fired after OnConnectPre() when a connection was established successfully or NGA failed to establish a new connection.

Parameters:

  | Ok | - operation status true - the connection established successfully false - failed to establish a connection

HRESULT NGuestXLib::_INGuestXCtrlEvents::OnDisconnectPre | ( |  | ) |

Fired after OnEndSessionPre() in response to EndSession() if the connection should be terminated because there is no more active session.

HRESULT NGuestXLib::_INGuestXCtrlEvents::OnDisconnectPost | ( |  | ) |

Fired after OnDisconnectPre() method when NGA has been disconnected from Host.

HRESULT NGuestXLib::_INGuestXCtrlEvents::OnBeginSessionPre | ( | [in] LONG | Type | ) |

The very first event that can be fired in response to INGuestXCtrl::BeginSession() before any long lasting network operations started.

Parameters:

  | Type | - session type INGuestXCtrl::SessionType_RemoteControl - Remote control INGuestXCtrl::SessionType_Chat - Text chat

HRESULT NGuestXLib::_INGuestXCtrlEvents::OnBeginSessionPost | ( | [in] LONG | Type,
|  | [in] VARIANT_BOOL | Ok |
| ) |  |  |

Fired after OnBeginSessionPre() when a session was established successfully or NGA failed to establish a new session.

When a new connection is created after INGuestXCtrl::BeginSession(), after having OnBeginSessionPre() event, the authentication event should be expected (e.g. OnLoginPassword, OnLoginNetop, etc).

It is safe to open a new session of another type in response to this event only if a INGuestXCtrl::BeginSession() was called with active connection. Othewise it will be safe to start a session only after authentication, i.e. in response to OnSessionStarted() event.

Parameters:

  | Type | - session type INGuestXCtrl::SessionType_RemoteControl - Remote control INGuestXCtrl::SessionType_Chat - Text chat
  | Ok | - status of BeginSession request true - the session established successfully false - failed to establish a session

HRESULT NGuestXLib::_INGuestXCtrlEvents::OnEndSessionPre | ( | [in] LONG | Type | ) |

Fired when NGA was requested to close a session by INGuestXCtrl::EndSession() method before any long lasting network operations started.

Parameters:

  | Type | - session type INGuestXCtrl::SessionType_RemoteControl - Remote control INGuestXCtrl::SessionType_Chat - Text chat

HRESULT NGuestXLib::_INGuestXCtrlEvents::OnEndSessionPost | ( | [in] LONG | Type,
|  | [in] VARIANT_BOOL | Ok |
| ) |  |  |

Fired after OnEndSessionPre() when the session was closed by INGuestXCtrl::EndSession().

It is safe to open a new session of the same type in response to this event.

Parameters:

  | Type | - session type INGuestXCtrl::SessionType_RemoteControl - Remote control INGuestXCtrl::SessionType_Chat - Text chat
  | Ok | - status of EndSession request true - the session closed successfully false - failed to close a session

HRESULT NGuestXLib::_INGuestXCtrlEvents::OnSessionStarted | ( | [in] LONG | Type | ) |

Fired after the session went into the running state after having a new connection established.

Parameters:

  | Type | - session type INGuestXCtrl::SessionType_RemoteControl - Remote control INGuestXCtrl::SessionType_Chat - Text chat

HRESULT NGuestXLib::_INGuestXCtrlEvents::OnEndedByHost | ( |  | ) |

Fired when a session and connection was ended by host.

OnErrorMsg() event will be fired with message #?? after this event.

HRESULT NGuestXLib::_INGuestXCtrlEvents::OnConnectionLost | ( |  | ) |

Fired after connection was lost.

OnErrorMsg() event will be fired with message #?? after this event.

HRESULT NGuestXLib::_INGuestXCtrlEvents::OnLoginPassword | ( | [in] LONG | Reason,
|  | [in] INGuestXEventParam * | EventParam |
| ) |  |  |

Fired when NetOp password should be sent to Host.

Default action: Built-in dialog will be shown to prompt password. Event handler can suppress the built-in login dialog and send password with INGuestXCtrl::SendLoginPassword() method.

To Cancel login INGuestXCtrl::EndSession() function can be called.

Parameters:

  | Reason | - The why this prompt is needed
  | EventParam | - event parameter object. Handler can change its property Handled to true to suppress the default action.

HRESULT NGuestXLib::_INGuestXCtrlEvents::OnLoginNetOp | ( | [in] LONG | Reason,
|  | [in] VARIANT_BOOL | bNss,
|  | [in] INGuestXEventParam * | EventParam |
| ) |  |  |

Fired when NetOp guest ID and password should be sent to Host.

Default action: Built-in dialog will be shown to prompt for ID and password. Event handler can suppress the built-in login dialog and send password with INGuestXCtrl::SendLoginNetOp() method.

To Cancel login INGuestXCtrl::EndSession() function can be called.

Parameters:

  | Reason | - The why this prompt is needed
  | bNss | - If the Host is configured for NetOp Security Server authentication. When a Host is configured for Nss authentication Guest can change by sending new password with INGuestXCtrl::SendLoginNetOp() method.
  | EventParam | - event parameter object. Handler can change its property Handled to true to suppress the default action.

HRESULT NGuestXLib::_INGuestXCtrlEvents::OnLoginWindows | ( | [in] LONG | Reason,
|  | [in] INGuestXEventParam * | EventParam |
| ) |  |  |

Fired when Windows login, domain and password should be sent to Host.

Default action: Built-in dialog will be shown to prompt for login, domain and password. Event handler can suppress the built-in login dialog and send password with INGuestXCtrl::SendLoginWindows() method.

To Cancel login INGuestXCtrl::EndSession() function can be called.

Parameters:

  | Reason | - The why this prompt is needed
  | EventParam | - event parameter object. Handler can change its property Handled to true to suppress the default action.

HRESULT NGuestXLib::_INGuestXCtrlEvents::OnLoginLdap | ( | [in] LONG | Reason,
|  | [in] INGuestXEventParam * | EventParam |
| ) |  |  |

Fired when LDAP server name, login and password should be sent to Host.

Default action: Built-in dialog will be shown to prompt for server name, login and password. Event handler can suppress the built-in login dialog and send password with INGuestXCtrl::SendLoginLdap() method.

To Cancel login INGuestXCtrl::EndSession() function can be called.

Parameters:

  | Reason | - The why this prompt is needed
  | EventParam | - event parameter object. Handler can change its property Handled to true to suppress the default action.

HRESULT NGuestXLib::_INGuestXCtrlEvents::OnLoginRsa | ( | [in] LONG | Reason,
|  | [in] LONG | Shadow,
|  | [in] INGuestXEventParam * | EventParam |
| ) |  |  |

Fired when login name, RSA SecurID passcode and password should be sent to Host.

Default action: Built-in dialog will be shown to prompt for login, RSA passcode and password. Event handler can suppress the built-in login dialog and send password with INGuestXCtrl::SendLoginRsa() method.

To Cancel login INGuestXCtrl::EndSession() function can be called.

Parameters:

  | Reason | - The why this prompt is needed
  | Shadow | - 1 if a NetOp password is required in addition to the RSA SecurID PASSCODE.
  | EventParam | - event parameter object. Handler can change its property Handled to true to suppress the default action.

HRESULT NGuestXLib::_INGuestXCtrlEvents::OnLoginFailed | ( | [in] LONG | Reason | ) |

Fired when the login has been failed.

?? Is it safe to open a new session.

Parameters:

  | Reason | - the reason of why login has failed

HRESULT NGuestXLib::_INGuestXCtrlEvents::OnEnterRsaPincode | ( | [in] LONG | Reason,
|  | [in] LONG | Mode,
|  | [in] BSTR | SuggestedPin,
|  | [in] LONG | MinLen,
|  | [in] LONG | MaxLen,
|  | [in] VARIANT_BOOL | AllowNonNumeric,
|  | [in] INGuestXEventParam * | EventParam |
| ) |  |  |

Fired when the server side requires RSA SecurID pin code.

Default action: Built-in dialog will be shown to prompt RSA SecurID pin code. Event handler can suppress the built-in login dialog and send password with INGuestXCtrl::SendLoginRsaPin() method.

Parameters:

  | Reason | - The why this prompt is needed
  | Mode | - 0 = fixed, 1,2 = selectable (2 has no suggestion).
  | SuggestedPin | - The suggested pin code if any. May be NULL.
  | MinLen | - The minimum length for a valid pin code.
  | MaxLen | - The maximum length for a valid pin code.
  | AllowNonNumeric | - True if characters other than 0-9 are allowed
  | EventParam | - event parameter object. Handler can change its property Handled to true to suppress the default action.

HRESULT NGuestXLib::_INGuestXCtrlEvents::OnHostScreenSizeInfo | ( | [in] LONG | Width,
|  | [in] LONG | Height |
| ) |  |  |

Fired when the size of the remote screen is changed.

Parameters:

  | Width | - new width of the remote screen
  | Height | - new height of the remote screen

HRESULT NGuestXLib::_INGuestXCtrlEvents::OnHostMultiGuestInfo | ( | [in] LONG | Event,
|  | [in] LONG | NumGuests,
|  | [in] LONG | Error |
| ) |  |  |

Fired when multi guest parameters have been updated on Host.

Parameters:

  | Event | - bitwise combination of the MultiguestEvent_t flags: INGuestXCtrl::MultiguestEvent_InputAssigned - This Guest is assigned input control INGuestXCtrl::MultiguestEvent_InputRevoked - This Guest is revoked input control INGuestXCtrl::MultiguestEvent_InputDenied - This Guest requested input control but it was denied. See error for optional error code. INGuestXCtrl::MultiguestEvent_ConnectionsChanged - Number of session changed INGuestXCtrl::MultiguestEvent_MultiSessionsSuspended - More sessions suspended INGuestXCtrl::MultiguestEvent_MultiSessionsAllowed - More sessions allowed INGuestXCtrl::MultiguestEvent_MultiSessionsDeninied - Change of sessions denied
  | NumGuest | - new number of connected Guest (only on INGuestXCtrl::MultiguestEvent_ConnectionsChanged event)
  | Error | - additional information (only for INGuestXCtrl::MultiguestEvent_InputDenied and INGuestXCtrl::MultiguestEvent_MultiSessionsDeninied events).

HRESULT NGuestXLib::_INGuestXCtrlEvents::OnEraseBackground | ( | [in] LONG | hWnd,
|  | [in] LONG | hDC,
|  | [in] INGuestXEventParam * | EventParam |
| ) |  |  |

Fired when NGA control background should be erased.

Default action: If there is an RC session the background is erased by black color. When there is no RC session the default NGA bitmap is shown.

Parameters:

  | hWnd | - NGA window handler
  | hDC | - device context for erase background windows message
  | EventParam | - event parameter object. Handler can change its property Handled to true to suppress the default action.

HRESULT NGuestXLib::_INGuestXCtrlEvents::OnChatMessageIn | ( | [in] BSTR | Msg,
|  | [in] INGuestXFont * | Font,
|  | [in] INGuestXEventParam * | EventParam |
| ) |  |  |

Fired on incoming chat message.

Default action: show the message in the chat dialog if the one is opened.

Parameters:

  | Msg | - received chat message
  | EventParam | - event parameter object. Handler can change its property Handled to true to suppress the default action.

HRESULT NGuestXLib::_INGuestXCtrlEvents::OnChatMessageOut | ( | [in] BSTR | Msg,
|  | [in] INGuestXFont * | Font,
|  | [in] INGuestXEventParam * | EventParam |
| ) |  |  |

Fired on outgoing chat message.

The event fired after INGuestXCtrl::SendChatMessage() was called. The message can be different from one passed to INGuestXCtrl::SendChatMessage() method because "<PC Name>" string is inserted.

Default action: show the message in the chat dialog if the one is opened.

Parameters:

  | Msg | - received chat message
  | EventParam | - event parameter object. Handler can change its property Handled to true to suppress the default action.

HRESULT NGuestXLib::_INGuestXCtrlEvents::OnErrorMsg | ( | [in] LONG | MsgNo,
|  | [in] BSTR | Message,
|  | [in] INGuestXEventParam * | EventParam |
| ) |  |  |

Fired before any NGA error message is shown.

Default action: Built-in error message box is shown. Event handler can suppress the message box.

Parameters:

  | MsgNo | - id of message format string
  | Message | - message to be shown
  | EventParam | - event parameter object. Handler can change its property Handled to true to suppress the default action.

HRESULT NGuestXLib::_INGuestXCtrlEvents::OnInfoMsg | ( | [in] LONG | MsgNo,
|  | [in] BSTR | Message,
|  | [in] INGuestXEventParam * | EventParam |
| ) |  |  |

Fired before any NGA information message is shown.

Parameters:

  | MsgNo | - id of message format string
  | Message | - message to be shown
  | EventParam | - event parameter object. Handler can change its property Handled to true to suppress the default action.

Default action: Status changed in the built-in window if the window is open.

HRESULT NGuestXLib::_INGuestXCtrlEvents::OnConnectWindow | ( | [in] INGuestXEventParam * | EventParam | ) |

Fired when user left clicks on ActiveX area when there is no active connection.

Default action: Built-in dialog will be shown to setup a new connection. Event handler can suppress the built-in dialog.

Parameters:

  | EventParam | - event parameter object. Handler can change its property Handled to true to suppress the default action.

HRESULT NGuestXLib::_INGuestXCtrlEvents::OnStatusWindow | ( | [in] INGuestXEventParam * | EventParam | ) |

Fired when user pressed the keyboard shortcut for connection status window when there is an active connection.

Default action: Built-in Connection Status dialog will be shown. Event handler can suppress the built-in dialog.

Parameters:

  | EventParam | - event parameter object. Handler can change its property Handled to true to suppress the default action.

HRESULT NGuestXLib::_INGuestXCtrlEvents::OnPropertyWindow | ( | [in] INGuestXEventParam * | EventParam | ) |

Fired when user right clicks on ActiveX area when there is no active connection.

Default action: Built-in Connection Properties dialog will be shown. Event handler can suppress the built-in dialog.

Parameters:

  | EventParam | - event parameter object. Handler can change its property Handled to true to suppress the default action.

HRESULT NGuestXLib::_INGuestXCtrlEvents::OnChatUIStart | ( | [in] INGuestXEventParam * | EventParam | ) |

Fired when a Chat UI should be shown.

Default action: show the chat window.

Parameters:

  | EventParam | - event parameter object. Handler can change its property Handled to true to suppress the default action.

HRESULT NGuestXLib::_INGuestXCtrlEvents::OnChatUIEnd | ( |  | ) |

Fired when a Chat UI should be hidden.

NGA hides the chat window if the one is opened.

HRESULT NGuestXLib::_INGuestXCtrlEvents::OnInfoWindow | ( | [in] LONG | Reason,
|  | [in] INGuestXEventParam * | EventParam |
| ) |  |  |

Fired when an info window should be shown.

Default action: open the modal info window to show info messages.

Parameters:

  | Reason | one of the INGuestXCtrl::InfoWindowReason_t constants

HRESULT NGuestXLib::_INGuestXCtrlEvents::OnLicenseRequired | ( | [in] LONG | MsgNo,
|  | [in] BSTR | Message,
|  | [in] INGuestXEventParam * | EventParam |
| ) |  |  |

Fired when current license does not allow to start the connection initiated either via GUI or BeginSession() method.

Default ActiveX handler shows the License GUI window. Default GUI can be suppressed by setting the property Handled of the param object to TRUE in application event handler.

This event will be fired continuously until either the license will be accepted by the ActiveX or the connection will be canceled by setting the property Canceled of the param object to TRUE.

Parameters:

  | MsgNo | - id of message format string
  | Message | - Either contains the description that a license is required for non web connect connections or the Sentinel error why current license key cannot be used.
  | EventParam | - event parameter object. Handler can change its property Handled to true to suppress the default action. Handler can change its property Canceled to true to terminate connection process. Property Canceled is checked only if Handled was set to true.

Default action: open the modal license dialog window to enter the license.