// Copyright 2009-2012 The MumbleKit Developers. All rights reserved. // Use of this source code is governed by a BSD-style // license that can be found in the LICENSE file. #import /** * @constant The default MKConnection ping interval. */ #define MKConnectionPingInterval 5.0f @class MKConnection; @class MKPacketDataStream; @class MKCryptState; @class MKCertificate; typedef enum { UDPVoiceCELTAlphaMessage = 0, UDPPingMessage, UDPVoiceSpeexMessage, UDPVoiceCELTBetaMessage, UDPVoiceOpusMessage, } MKUDPMessageType; typedef enum { VersionMessage = 0, UDPTunnelMessage, AuthenticateMessage, PingMessage, RejectMessage, ServerSyncMessage, ChannelRemoveMessage, ChannelStateMessage, UserRemoveMessage, UserStateMessage, BanListMessage, TextMessageMessage, PermissionDeniedMessage, ACLMessage, QueryUsersMessage, CryptSetupMessage, ContextActionModifyMessage, ContextActionMessage, UserListMessage, VoiceTargetMessage, PermissionQueryMessage, CodecVersionMessage, UserStatsMessage, RequestBlobMessage, ServerConfigMessage, } MKMessageType; /** * MKRejectReason is an integer describing the reason for a * rejected connection attempt. */ typedef enum { /** * There was no reason. */ MKRejectReasonNone = 0, /** * The client attempted to connect with an unsupported version. */ MKRejectReasonWrongVersion, /** * The specified username is not deemed valid by the remote server. */ MKRejectReasonInvalidUsername, /** * The given password is an incorrect password for the given username. */ MKRejectReasonWrongUserPassword, /** * The given password is not the correct server password. */ MKRejectReasonWrongServerPassword, /** * The username the connection attempted to connect with is already in use * on the server. */ MKRejectReasonUsernameInUse, /** * The server is full and cannot accept any new clients. */ MKRejectReasonServerIsFull, /** * The client did not present a certificate, but the server is set up to require * the presence of a client certificate. */ MKRejectReasonNoCertificate } MKRejectReason; /** * MKConnectionDelegate implements a set of methods that are called on the delegate * object of a MKConnection when important connection-related events happen. */ @protocol MKConnectionDelegate /** * This method is called once a connection has been established to the remote host, and * the TLS handshake has finished. * Once the MKConnection has sent this message to its delegate, it is safe to authenticate * with the server. * * @param conn The connection that was opened. */ - (void) connectionOpened:(MKConnection *)conn; /** * This method is called if a connection cannot be stablished to the given server. * * @param conn The connection that this occurred in. * @param err Error describing why the connection could not be established. */ - (void) connection:(MKConnection *)conn unableToConnectWithError:(NSError *)err; /** * This method is called whenever the connection is closed, be it by an error, or by * disconnection. If the disconnection was caused by an error, the err parameter will * be a non-nil value. * * This method can only be called after the connection has been opened. If an error occurs * during the connection phase, the method `connection:unableToConnectWithError:` will be * called instead. * * @param conn The connection that was closed. * @param err The error that caused the disconnection. (Nil if not caused by an error) */ - (void) connection:(MKConnection *)conn closedWithError:(NSError *)err; /** * This method is called if the MKConnection could not verify the TLS certificate chain * of the remote server as trusted. * * To implement support for self-signed certificates, one wold typically save the digest * of the leaf certificate of the server's certificate chain somewhere along with host * information for the server (hostname:port) that the trust failure happened on. * Then, every time a connection attempt is made, the trust failure can then be remedied * by setting setIgnoreSSLVerification property on the MKConnection and issuing a * reconnect to the MKConnection object. * * @param conn The connection that the trust failure occurred on. * @param chain The TLS certificate chain of the remote server. * (An array of MKCertificate objects) */ - (void) connection:(MKConnection *)conn trustFailureInCertificateChain:(NSArray *)chain; /** * The connection attempt was rejected. This could, for example, be an authentication failure. * * @param conn The MKConnection object whose connection was rejected. * @param reason The reason for the rejected connection attempt. (See MKRejectReason). * @param explanation A textual description of the reason for rejection. */ - (void) connection:(MKConnection *)conn rejectedWithReason:(MKRejectReason)reason explanation:(NSString *)explanation; @end /** * MKMessageHandler implements a set of methods that are called on the messageHandler * object of a MKConnection when new control channel messages arrive. Only messages that * the MKConnection itself does not know how to handle are delegated to the messageHandler. * * Typically, a consumer of MKConnection does not directly set a MKMessage handler, but instead * wrap the MKConnection in a MKServerModel object which */ @protocol MKMessageHandler /** * Called whenever a ban list message is received. (See MKMessageType's * BanListMessage value). * * @param conn The connection that received the message. * @param msg An internal representation of a ban list message. */ - (void) connection:(MKConnection *)conn handleBanListMessage: /* MPBanList */ (id)msg; /** * Called whenever a server sync message is received. (See MKMessageType's * ServerSyncMessage value). * * @param conn The connection that received the message. * @param msg An internal representation of a server sync message. */ - (void) connection:(MKConnection *)conn handleServerSyncMessage: /* MPServerSync */ (id)msg; /** * Called whenever a permission denied message is received. (See MKMessageType's * PermissionDeniedMessage value). * * @param conn The connection that received the message. * @param msg An internal representation of a permission denied message. */ - (void) connection:(MKConnection *)conn handlePermissionDeniedMessage: /* MPPermissionDenied */ (id)msg; /** * Called whenever a user state message is receieved. (See MKMessageType's * UserStateMessage value). * * @param conn The connection that received the message. * @param msg An internal representation of a user state message. */ - (void) connection:(MKConnection *)conn handleUserStateMessage: /* MPUserState */ (id)msg; /** * Called whenever a user remove message is received. (See MKMessageType's * UserRemoveMessage value). * * @param conn The connection that received the message. * @param msg An internal representation of a user remove message. */ - (void) connection:(MKConnection *)conn handleUserRemoveMessage: /* MPUserRemove */ (id)msg; /** * Called whenever a channel state message is recieved. (See MKMessageType's * ChannelStateMessage value). * * @param conn The connection that received the message. * @param msg An internal representation of a channel state message. */ - (void) connection:(MKConnection *)conn handleChannelStateMessage: /* MPChannelState */ (id)msg; /** * Called whenever a channel remove message is received (See MKMessageType's * ChannelRemoveMessage value). * * @param conn The connection that received the message. * @param msg An internal representation of a channel remove message. */ - (void) connection:(MKConnection *)conn handleChannelRemoveMessage: /* MPChannelRemove */ (id)msg; /** * Called whenever a text message message is recieved. (See MKMessageType's * TextMessageMessage value). * * @param conn The connection that received the message. * @param msg An internal representation of a text message message. */ - (void) connection:(MKConnection *)conn handleTextMessageMessage: /* MPTextMessage */ (id)msg; /** * Called whenever an ACL message is receieved. (See MKMessageType's ACLMessage value). * * @param conn The connection that received the message. * @param msg An internal representation of an ACL message. */ - (void) connection:(MKConnection *)conn handleACLMessage: /* MPACL */ (id)msg; /** * Called whenver a query users message is received. (See MKMessageType's * QueryUsersMessage value). * * @param conn The connection that received the message. * @param msg An internal representation of a query users message. */ - (void) connection:(MKConnection *)conn handleQueryUsersMessage: /* MPQueryUsers */ (id)msg; /** * Called whenever a context action message is receieved. (See MKMessageType's * ContextActionMessage value). * * @param conn The connection that received the message. * @param msg An internal representation of a context action message. */ - (void) connection:(MKConnection *)conn handleContextActionMessage: /* MPContextAction */ (id)msg; /** * Called whenever a context action add message is received. (See MKMessageType's * ContextActionModify value). * * @param conn The connection that received the message. * @param msg An internal representation of a context action add message. */ - (void) connection:(MKConnection *)conn handleContextActionModifyMessage: /* MPContextActionModify */ (id)msg; /** * Called whenever a user list message is received. (See MKMessageType's * UserListMessage value). * * @param conn The connection that received the message. * @param msg An internal representation of a user list message. */ - (void) connection:(MKConnection *)conn handleUserListMessage: /* MPUserList */ (id)msg; /** * Called whenever a voice target message is receieved. (See MKMessageType's * VoiceTargetMessage value). * * @param conn The connection that received the message. * @param msg An internal representation of a voice target message. */ - (void) connection:(MKConnection *)conn handleVoiceTargetMessage: /* MPVoiceTarget */ (id)msg; /** * Called whenever a permission query message is receieved. * * @param conn The connection that received the message. * @param msg An internal representation of a permission query message. */ - (void) connection:(MKConnection *)conn handlePermissionQueryMessage: /* MPPermissionQuery */ (id)msg; @end /** * MKConnection represents a connection to a Mumble server. * It is mostly used together with MKServerModel which translates the wire protocol * to Objective-C delegate callbacks. */ @interface MKConnection : NSThread /** * Initialize a new MKConnection object. */ - (id) init; /** * Deallocate a MKConnection object. */ - (void) dealloc; #pragma mark - /** * Establish a connection to the given host and port. * * @param hostName The hostname to connect to. * @param port The port on hostname to connect to. */ - (void) connectToHost:(NSString *)hostName port:(NSUInteger)port; /** * Re-establish the connection. This is often used together with the * setIgnoreSSLVerification: method to implement an "Are You Sure?" dialog * for self-signed certificates. */ - (void) reconnect; /** * Disconnect from the server. */ - (void) disconnect; /** * The current status of the connection. * * @returns Returns YES if the MKConnection is currently connected to a server. * Returns NO otherwise. */ - (BOOL) connected; /** * The hostname that the MKConnection is currently connected to. */ - (NSString *) hostname; /** * The port number on the host that the MKConnection is currently connected to. */ - (NSUInteger) port; /** * Set a certificate chain to be used for the MKConnection. This property is only * used during connection establishment, and as such, chaning this value while the * MKConnection object is a conncted to a server has no effect. * * @param chain A NSArray containing a SecIdentityRef as its first item, and SecCertificateRefs subsequently. */ - (void) setCertificateChain:(NSArray *)chain; /** * Returns the certificate chain that is to be presented to the server during the next connection attempt. */ - (NSArray *) certificateChain; #pragma mark Server Info /** * A textual description of the version number of the Mumble server that the MKConnection * object is currently connected to. */ - (NSString *) serverVersion; /** * A textual description of the release name of the Mumble server that the MKConnection * object is currently connected to. */ - (NSString *) serverRelease; /** * A textual description of the operating system that powers the Mumble server that the * MKConnection object is currently connected to. */ - (NSString *) serverOSName; /** * A textual description of the version of the operating system that powers the Mumble * server that the MKConnection object is currently connected to. */ - (NSString *) serverOSVersion; ///------------------------------------- /// @name Authenticating with the server ///------------------------------------- /** * Once a connection has been established (that is, once the connectionOpened: delegate * method has been called), this method must be used to authenticate with the remote * Mumble server. * * @param user The username of the user that the MKConnection should authenticate * itself as. This can be a registered user, or a new user that is currently * not registered. * * @param pass The password to authenticate with. If the specified username is that * of a registered user, the password will be treated as a user password. * Otherwise, it will be treated as a server password. * * @param tokens The initial set of access tokens for the user we are connecting as, in * the form of an NSArray of NSStrings. * This parameter may be nil if the user does not have any access tokens. */ - (void) authenticateWithUsername:(NSString *)user password:(NSString *)pass accessTokens:(NSArray *)tokens; ///---------------------- /// @name Message Handler ///---------------------- - (void) setMessageHandler: (id)messageHandler; - (id) messageHandler; ///---------------------- /// @name Delegate ///---------------------- - (void) setDelegate: (id)delegate; - (id) delegate; ///--------------------------- /// @name TLS connection state ///--------------------------- /** * Signals to the MKConnection that it should ignore most verification * errors that happen while verifying the server's certificate chain * during the TLS handshake. * * This is used to implement user trust of servers with self-signed * (or perhaps shady) certificates. * * @param shouldIgnoreVerification Should be YES if the connection should * ignore TLS certificate chain verification * errors. By default this is set to NO. * * */ - (void) setIgnoreSSLVerification:(BOOL)shouldIgnoreVerification; /** * Once a connection is established, this method returns an array * containing the TLS certificate chain of the remote server. * * Certificates in the chain are represented by MKCertificate objects. */ - (NSArray *) peerCertificates; /** * Once a connection is established, this method returns the system's * trust status of the server's certificate chain. This trust is based * on the system's list of root certificate authorities. */ - (BOOL) peerCertificateChainTrusted; ///---------------------- /// @name Forced TCP mode ///---------------------- /** * Set whether or not the server should force all UDP trafic to be tunelled * through TCP. If at all possible, this should be kept as NO (which is also * the default value). * * @param shouldForceTCP Should be YES if the connection shall tunnel all UDP * trafic through TCP. * */ - (void) setForceTCP:(BOOL)shouldForceTCP; /** * Returns the current Forced-TCP status of the MKConnection object. * * @returns Returns YES if all UDP trafic to and from the remote server * is being tunelled through a TCP connection. Returns NO otherwise. */ - (BOOL) forceTCP; ///---------------------------------------- /// @name Sending data to the remote server ///---------------------------------------- /** * Transmits a blob of data (presumed to be a message encoded as expected by * the Mumble server) using the given messageType as the token used for identifying * how the contents of the message are to be handled by the remote server. * * @param messageType A MKMessageType describing the kind of message that is to be * transmitted. * * @param data The raw data to be sent to the remote server. This is presumed to be * a message encoded as expected by the remote server. (That is, * MKConnection will not attempt to serialize the passed-in data). */ - (void) sendMessageWithType:(MKMessageType)messageType data:(NSData *)data; /** * Send a voice packet to the remote server. * The voice packet will be transported to the server using UDP, unless * the forceTCP property has been changed to force all UDP trafic to be * tunelled through TCP. * * @param data A raw Mumble voice packet. */ - (void) sendVoiceData:(NSData *)data; ///------------------------ /// @name Codec Information ///------------------------ /** * The current elected alpha codec, as determined by the server through a mojority vote. */ - (NSUInteger) alphaCodec; /** * The currently elected beta codec, as determined by the server through a majority vote. */ - (NSUInteger) betaCodec; /** * Returns whether or not clients should prefer the alpha codec over the beta codec (if at * all possible). */ - (BOOL) preferAlphaCodec; /** * Returns whether ot not the connected client should use the Opus codec. */ - (BOOL) shouldUseOpus; @end