Inherits from NSObject
Conforms to IBitSwarmEvents
IConfigLoader
Declared in SmartFox2XClient.h
SmartFox2XClient.m

Overview

SmartFox2XClient is the main class in the SFS2X API.

This class is responsible for connecting to the Server and dispatching all asynchronous events.

Warning: Important: in the provided examples, smartFox always indicates a SmartFox2XClient instance.

Properties

buddyManager

Returns the Buddy Manager.

@property (strong) id<IBuddyManager> buddyManager

Discussion

Returns the Buddy Manager.

See Also

Declared In

SmartFox2XClient.h

compressionThreshold

Returns the current compression threshold.

@property (readonly) NSInteger compressionThreshold

Discussion

Returns the current compression threshold.

The value represent the maximum message size (in bytes) before the protocol compression is activated. The value is determined by the server configuration.

Declared In

SmartFox2XClient.h

config

Get the current client configuration.

@property (strong) ConfigData *config

Discussion

Get the current client configuration.

It can return null if the configuration was not loaded.

Declared In

SmartFox2XClient.h

connectionMode

Returns the mode of the connection (Socket or HTTP)

@property (weak, readonly) NSString *connectionMode

Discussion

Returns the mode of the connection (Socket or HTTP)

Declared In

SmartFox2XClient.h

currentIp

The address where the client is connected (if the client is connected)

@property (weak, readonly) NSString *currentIp

Discussion

The address where the client is connected (if the client is connected)

Declared In

SmartFox2XClient.h

currentPort

The TCP port of the server where the client is connected (if the client is connected)

@property (readonly) NSInteger currentPort

Discussion

The TCP port of the server where the client is connected (if the client is connected)

Declared In

SmartFox2XClient.h

currentZone

The current Zone in use, if user is logged in

@property (strong) NSString *currentZone

Discussion

The current Zone in use, if user is logged in

Declared In

SmartFox2XClient.h

debug

When set to true, provides detailed debugging data for all incoming/outgoing messages

@property (assign) BOOL debug

Discussion

When set to true, provides detailed debugging data for all incoming/outgoing messages

Declared In

SmartFox2XClient.h

isConnected

Returns true if the client connection is active

@property (readonly) BOOL isConnected

Discussion

Returns true if the client connection is active

Declared In

SmartFox2XClient.h

joinedRooms

Returns a list of Rooms currently joined by the client

@property (weak, readonly) NSMutableArray *joinedRooms

Discussion

Returns a list of Rooms currently joined by the client

See Also

Declared In

SmartFox2XClient.h

lastJoinedRoom

Return the last joined Room, if any.

@property (strong) id<Room> lastJoinedRoom

Discussion

Return the last joined Room, if any.

Null is returned if there’s no currently joined Room.

See Also

Declared In

SmartFox2XClient.h

logger

Get a reference to the logger

@property (weak, readonly) Logger *logger

Return Value

the logger

Discussion

Get a reference to the logger

Declared In

SmartFox2XClient.h

mySelf

This User object represents the User connected to SmartFoxServer 2X

@property (strong) id<User> mySelf

Discussion

This User object represents the User connected to SmartFoxServer 2X

See Also

Declared In

SmartFox2XClient.h

roomList

Returns the list of Rooms currently “watched” by the client.

@property (weak, readonly) NSArray *roomList

Discussion

Returns the list of Rooms currently “watched” by the client.

The list will contain all the Rooms that are currently joined and all the Rooms from the Room Groups that are subscribed. At login time the User is automatically subscribed to all Room Groups specified in the Zone’s Default Groups setting.

Declared In

SmartFox2XClient.h

roomManager

Returns the Room Manager.

@property (strong) id<IRoomManager> roomManager

Discussion

Returns the Room Manager.

See Also

Declared In

SmartFox2XClient.h

sessionToken

Returns the unique session token.

@property (strong) NSString *sessionToken

Discussion

Returns the unique session token.

The Session token is a String sent by the server to the client after the initial handshake.

Declared In

SmartFox2XClient.h

useBlueBox

Returns true if the client connection is http tunnelled

@property (assign) BOOL useBlueBox

Discussion

Returns true if the client connection is http tunnelled

Declared In

SmartFox2XClient.h

userManager

Returns the User Manager.

@property (strong) id<IUserManager> userManager

Discussion

Returns the User Manager.

See Also

Declared In

SmartFox2XClient.h

version

Return the API current version

@property (weak, readonly) NSString *version

Discussion

Return the API current version

Declared In

SmartFox2XClient.h

Class Methods

smartFoxWithDebugMode:delegate:

Initializes and returns SmartFox2XClient instance.

+ (id)smartFoxWithDebugMode:(BOOL)debug delegate:(id<ISFSEvents>)delegate

Parameters

debug

(BOOL) determines debugging mode.

delegate

(id ISFSEvents) delegate object that listens api events.

Discussion

Initializes and returns SmartFox2XClient instance.

Declared In

SmartFox2XClient.h

Instance Methods

connect

Establish connection with SmartFoxServer 2X.

- (void)connect

Discussion

Establish connection with SmartFoxServer 2X.

Client will use the settings loaded via loadConfig

Exceptions

NSException

if host/address or port in the config file is invalid.

Declared In

SmartFox2XClient.h

connect:port:

Establish connection with SmartFoxServer 2X.

- (void)connect:(NSString *)host port:(int)port

Parameters

host

(NSString *) the address of the server to connect to

port

(NSInteger) the TCP port (default port used by SFS2X is 9933)

Discussion

Establish connection with SmartFoxServer 2X.

Client will use the settings loaded via loadConfig if you pass nil value for host or -1 for port.

Exceptions

NSException

if an invalid host/address or port is passed

Declared In

SmartFox2XClient.h

connectWithConfig:

Establish connection with SmartFoxServer 2X using a defined Configuration Object

- (void)connectWithConfig:(ConfigData *)cfg

Parameters

cfg

(ConfigData *) configuration paramaters (host, port, etc)

Discussion

Establish connection with SmartFoxServer 2X using a defined Configuration Object

Client will use the settings loaded via loadConfig if you pass nil value for host or -1 for port.

Exceptions

NSException

if an invalid host/address or port is passed

Example:
The following example shows how to pass a ConfigData object to connect directly with SFS 2X.

smartFox = [[SmartFox2XClient alloc] initSmartFoxWithDebugMode:YES delegate:self];

ConfigData *cfg = [[ConfigData alloc] init];
cfg.host = @"127.0.0.1";
cfg.port = 9933;
cfg.zone = @"BasicExamples";
cfg.useBlueBox = YES;

// Start connection
[smartFox connectWithConfig:cfg];

See Also

Declared In

SmartFox2XClient.h

disconnect

Disconnect from SmartFoxServer.

- (void)disconnect

Discussion

Disconnect from SmartFoxServer.

Declared In

SmartFox2XClient.h

enableLagMonitor:

Enable the lag monitor.

- (void)enableLagMonitor:(BOOL)enabled

Parameters

enabled

(BOOL) toggles the state of the Lag Monitor

Discussion

Enable the lag monitor.

Toggles the automatic realtime monitoring of the lag between the client and the server (round robin). When turned on, the ISFSEvent.onPingPong event is called every 4 seconds, providing the average of the last ten measured lag values.

The Lag Monitor can be activated after the client has successfully logged in the Server. The monitoring is automatically turned off when the user logs out of a Zone or gets disconnected.

Declared In

SmartFox2XClient.h

enableLagMonitorWithInterval:interval:queueSize:

Enable the lag monitor with custom settings

- (void)enableLagMonitorWithInterval:(BOOL)enabled interval:(NSInteger)interval queueSize:(NSInteger)qSize

Parameters

enabled

(BOOL) toggles the state of the Lag Monitor

interval

(NSInteger) the number of seconds between each roundtrip calls (default = 4)

qSize

(NSInteger) the number of measuerments kept in the local queue upon which the average is calculated (default = 10)

Discussion

Enable the lag monitor with custom settings

Toggles the automatic realtime monitoring of the lag between the client and the server (round robin) with custom settings.

The Lag Monitor can be activated after the client has successfully logged in the Server. The monitoring is automatically turned off when the user logs out of a Zone or gets disconnected.

Declared In

SmartFox2XClient.h

getRoomById:

Finds a Room from its Id or returns nil if no Room with that Id exist in the room list

- (id<Room>)getRoomById:(NSInteger)roomId

Parameters

roomId

(NSInteger) the id of the room.

Discussion

Finds a Room from its Id or returns nil if no Room with that Id exist in the room list

Declared In

SmartFox2XClient.h

getRoomByName:

Finds a Room from its name or returns nil if no Room with that name exist in the room list

- (id<Room>)getRoomByName:(NSString *)roomName

Parameters

roomName

(NSString *) the name of the room.

Discussion

Finds a Room from its name or returns nil if no Room with that name exist in the room list

Declared In

SmartFox2XClient.h

getRoomListFromGroup:

Return the list of Rooms from a specific Room Group

- (NSArray *)getRoomListFromGroup:(NSString *)groupId

Parameters

groupId

(NSString *)the name of the Group

Return Value

the list of rooms

Discussion

Return the list of Rooms from a specific Room Group

See Also

Declared In

SmartFox2XClient.h

httpUploadURI

Returns the HTTP URI that can be used to upload files to, using regular HTTP POST. For more details on how to use this functionality see the Upload File tutorial

- (NSString *)httpUploadURI

Discussion

Returns the HTTP URI that can be used to upload files to, using regular HTTP POST. For more details on how to use this functionality see the Upload File tutorial

NOTE: this property will return null if no API configuration has been set or the local User is not already logged in the server.

Declared In

SmartFox2XClient.h

initCrypto

Initializes the connection cryptography. Once this process is successfully completed all of the server’s data will be encrypted using standard AES 128-bit algorithm, using a secure key served over HTTPS.

- (void)initCrypto

Discussion

Initializes the connection cryptography. Once this process is successfully completed all of the server’s data will be encrypted using standard AES 128-bit algorithm, using a secure key served over HTTPS.

NOTE: It is necessary to send this request right after a successful connection event, before login.

Example:
The code below allows to easily toggle the use of encryption for local vs production testing.

BOOL useEncryption = YES;
smartFox = [[SmartFox2XClient alloc] initSmartFoxWithDebugMode:YES delegate:self];

ConfigData *cfg = [[ConfigData alloc] init];
cfg.host = @"127.0.0.1";
cfg.port = 9933;
cfg.zone = @"BasicExamples";

// Start connection
[smartFox connectWithConfig:cfg];


-(void) onConnection:(SFSEvent *)evt
{
    NSNumber *success = [evt.params objectForKey:@"success"];

    if (success)
    {
        if (useEncryption)
            [smartFox initCrypto];
        else 
            [self sendLogin];
    }
    else
        NSLog(@"Connection failed");
}

 - (void)onCryptoInit:(SFSEvent *)evt
 {
    NSNumber* success = [evt.params objectForKey:@"success"];

    if (success)
    {
        NSLog(@"Crypto Init Success!");
        [self sendLogin];
    }
    else
        NSLog(@"Crypto Init Failure!");
 }


-(void) sendLogin
{
    [smartFox send:[LoginRequest requestWithUserName:@"" password:@"" zoneName:smartFox.config.zone  params:nil]];
}

-(void) onLogin:(SFSEvent *)evt
{
    NSLog("Logged in as: %@", smartFox.mySelf.name];
}

Declared In

SmartFox2XClient.h

initSmartFoxWithDebugMode:delegate:

Initializes SmartFox Client

- (id)initSmartFoxWithDebugMode:(BOOL)debug delegate:(id<ISFSEvents>)delegate

Parameters

debug

(BOOL) determines debugging mode.

delegate

(id ISFSEvents) delegate object that listens api events.

Discussion

Initializes SmartFox Client

Declared In

SmartFox2XClient.h

initUDP:::

Initialize the UDP Manager to create a UDP connection. If the host and port parameters are left nil and -1

- (void)initUDP:(NSString *)udpHost :

Parameters

udpHost

(NSString *) the host (IP) of the SFS Server

udpPort

(NSInteger) the port of the SFS Server to handle UDP

-(void)onLogin:(SFSEvent *)evt
{
    NSArray *keys = [evt.params allKeys];
    for (NSString *key in keys)
    {
        // do somthing...
    }
    //initialize the UDP socket
    [smartFox initUDP :nil :-1];
}

Discussion

Initialize the UDP Manager to create a UDP connection. If the host and port parameters are left nil and -1

The UDP Manager will use the settings found in the config XML. UDP is only available through an ExtensionRequest.

Warning: Important: It is recommended to initialize the UDP connection after successful login to a zone.

Declared In

SmartFox2XClient.h

killConnection

Simulate an abrupt disconnection

- (void)killConnection

Discussion

Simulate an abrupt disconnection

To be used for testing/simulations only.

Declared In

SmartFox2XClient.h

loadConfig:connectOnSuccess:

Load a client configuration file.

- (void)loadConfig:(NSString *)filePath connectOnSuccess:(BOOL)connectOnSuccess

Parameters

filePath

(NSString *) external xml configuration file name (optional).

connectOnSuccess

(BOOL) a boolean flag indicating if the connection to SmartFoxServer must be attempted upon configuration loading completion.

Usage Note:
The external xml configuration file has the following structure; ip, port and zone parameters are mandatory, all other parameters are optional.

 <SmartFoxConfig>
     <ip>127.0.0.1</ip>
     <port>9933</port>
     <udpHost>127.0.0.1</udpHost>
     <udpPort>9934</udpPort>
     <zone>BasicExamples</zone>
     debugtrue</debug>
     useBlueBoxtrue</useBlueBox>
     <httpPort>8080</httpPort>
     <blueBoxPollingRate>750</blueBoxPollingRate>
 </SmartFoxConfig>

Example:
The following example shows how to load an external configuration file.

[smartfox loadConfig:@"sfs-config.xml" connectOnSuccess:NO];

-(void)onConfigLoadSuccess:(SFSEvent *)evt
{
    NSLog(@"Config file loaded, now connecting...");
    [smartFox connect:smartFox.ipAddress, smartFox.port];
}

 -(void)onConfigLoadFailure:(SFSEvent *)evt
{
    NSLog(@"Failed loading config file: %@", [evt.params objectForKey:@"message"]);
}

Discussion

Load a client configuration file.

The SmartFox2XClient instance can be configured through an external xml configuration file loaded at run-time. By default, the loadConfig method loads a file named sfs—config.xml, placed in the main bundle of the application. If the connectOnSuccess parameter is set to YES, on loading completion the connect:port: method is automatically called by the API, otherwise the onConfigLoadSuccess event is dispatched. In case of a loading error, the onConfigLoadFailure (ISFSEvents) event is fired.

Warning: Important: The SmartFox2XClient configuration file (client-side) should not be confused with the SmartFoxServer configuration file (server-side).

Declared In

SmartFox2XClient.h

send:

Sends a request to the Server.

- (void)send:(id<IRequest>)request

Parameters

request

(id IRequest) a request object.

Discussion

Sends a request to the Server.

All the available request objects are found in the documentation.

Declared In

SmartFox2XClient.h

setClientDetails:::

Allows to specify custom client details what will be used to gather statistics about the client platform via the Analytics Module. By default no details are sent.

- (void)setClientDetails:(NSString *)platformId :

Parameters

platformId:

(NSString *) The id of the runtime platform: for example “Unity WebPlayer” or “iOS”.

version:

(NSString *) An optional version of the runtime platform: for example “2.0.0”.

[smartFox setClientDetails:@"MyPlatform" :@"version 001"];

Discussion

Allows to specify custom client details what will be used to gather statistics about the client platform via the Analytics Module. By default no details are sent.

This method must be called before the connection is started. The length of the two strings combined must be < 512 characters.

Declared In

SmartFox2XClient.h