1 /* 2 Copyright (c) 2004-2019 by Jakob Schröter <js@camaya.net> 3 This file is part of the gloox library. http://camaya.net/gloox 4 5 This software is distributed under a license. The full license 6 agreement can be found in the file LICENSE in this distribution. 7 This software may not be copied, modified, sold or distributed 8 other than expressed in the named license agreement. 9 10 This software is distributed without any warranty. 11 */ 12 13 14 #ifndef CONNECTIONLISTENER_H__ 15 #define CONNECTIONLISTENER_H__ 16 17 #include "gloox.h" 18 19 namespace gloox 20 { 21 22 class Error; 23 24 /** 25 * @brief Derived classes can be registered as ConnectionListeners with the Client. 26 * 27 * This interface is mandatory to implement if a connection is to be made TLS-encrypted. 28 * In onTLSConnect(), the server's certificate information needs to be checked, and @b true 29 * returned if the certificate is to be accepted. 30 * 31 * @author Jakob Schröter <js@camaya.net> 32 */ 33 class GLOOX_API ConnectionListener 34 { 35 public: 36 /** 37 * Virtual Destructor. 38 */ ~ConnectionListener()39 virtual ~ConnectionListener() {} 40 41 /** 42 * This function notifies about successful connections. It will be called either after all 43 * authentication is finished if username/password were supplied, or after a connection has 44 * been established if no credentials were supplied. Depending on the setting of AutoPresence, 45 * a presence stanza is sent or not. 46 */ 47 virtual void onConnect() = 0; 48 49 /** 50 * This function notifies about disconnection and its reason. 51 * If @b e indicates a stream error, you can use @ref ClientBase::streamError() to find out 52 * what exactly went wrong, and @ref ClientBase::streamErrorText() to retrieve any explaining text 53 * sent along with the error. 54 * If @b e indicates an authentication error, you can use @ref ClientBase::authError() 55 * to get a finer grained reason. 56 * @param e The reason for the disconnection. 57 */ 58 virtual void onDisconnect( ConnectionError e ) = 0; 59 60 /** 61 * This function will be called when a resource has been bound to the stream. It 62 * will be called for any bound resource, including the main one. 63 * @note The bound resource may be different from the one requested. The server 64 * has the authority to change/overwrite the requested resource. 65 * @param resource The resource string. 66 * @since 1.0 67 */ onResourceBind(const std::string & resource)68 virtual void onResourceBind( const std::string& resource ) { (void)resource; } 69 70 /** 71 * This function is called (by a Client object) if an error occurs while trying to bind a resource. 72 * @param error A pointer to an Error object that contains more 73 * information. May be 0. 74 */ onResourceBindError(const Error * error)75 virtual void onResourceBindError( const Error* error ) { (void) (error); } 76 77 /** 78 * This function is called (by a Client object) if an error occurs while trying to establish 79 * a session. 80 * @param error A pointer to an Error object that contains more 81 * information. May be 0. 82 */ onSessionCreateError(const Error * error)83 virtual void onSessionCreateError( const Error* error ) { (void) (error); } 84 85 /** 86 * This function is called when the connection was TLS/SSL secured. 87 * @param info Comprehensive info on the certificate. 88 * @return @b True if cert credentials are accepted, @b false otherwise. If @b false is returned 89 * the connection is terminated. 90 */ 91 virtual bool onTLSConnect( const CertInfo& info ) = 0; 92 93 /** 94 * This function is called for certain stream events. Notifications are purely informational 95 * and implementation is optional. Not all StreamEvents will necessarily be emitted for 96 * a given connection. 97 * @param event A stream event. 98 * @since 0.9 99 */ onStreamEvent(StreamEvent event)100 virtual void onStreamEvent( StreamEvent event ) { (void) (event); } 101 102 }; 103 104 } 105 106 #endif // CONNECTIONLISTENER_H__ 107