Initialization and Error Handlers

[C]

void __cdecl FlowSshC_Initialize(FlowSshC_ErrorHandler handler, void* handlerData);

[C++]

[Initializer] Initializer(RefPtr<ErrorHandler> errHandler);

[C#]

[SshNet] public static event ExceptionInEventEventHandler OnExceptionInEvent;

Methods and Parameters

• [C] FlowSshC_Initialize: Initializes the library and registers an error handler.
  Parameters:
  • handler: An ErrorHandler function.
  • handlerData: An application-defined value to be passed to the handler.
  
  
• [C++] Initializer: Initializes the library and registers an error handler.
  Parameters:
  • errHandler: An ErrorHandler object.
  
  
• [.NET] OnExceptionInEvent: Invoked to inform you about uncaught exceptions from other events/handlers.

Remarks

You should always initialize the FlowSshC/Cpp/Net library and register a global error handler before using any of its functionality. Once using the library, there are two possible kinds of errors:

InCall errors. Any FlowSshC/Cpp/Net call may fail. For instance, imagine the [Client]SetUserName operation fails. Then we say that an InCall error occurred and:

• [C] The registered error handler is invoked with the InCall flag.
• [C++/.NET] An Exception is thrown.

InHandler errors. Handlers are mostly invoked from internal FlowSshC worker threads. The consequence is that special treatment (at least for [C++/.NET]) is required for exceptions that get thrown by handlers. For instance, imagine that your [Client]OnHostKey handler throws an exception. Then we say that an InHandler error occurred and:

• [C] The registered error handler is invoked with the InHandler flag.
• [C++] An ErrorHandler registered with the Initializer is invoked.
• [.NET] The OnExceptionInEvent event is invoked.

[C] FlowSshC_Initialize may be called multiple times for the purpose of changing the error handler. Calling the function multiple times has no other effects - shutdown will always be performed with the first call to FlowSshC_Shutdown.

[C++] Before using any FlowSshCpp functionality, create a single instance of Initializer (i.e. at the beginning of your main function). Don't create a global instance of this class.
Beware: By default, every FlowSshC call can throw an Exception unless you register your own error handler through FlowSshC_Initialize. In this case, the custom error handler must also throw some kind of exceptions for InCall errors. This ensures the stack is unwinded correctly and that C++ objects created on that stack and affected by the error are destroyed properly.

[.NET] Before using any FlowSshNet functionality, register to the OnExceptionInEvent event. You may register multiple delegates - this has no side-effects as OnExceptionInEvent is an ordinary .NET event.