/* FBExecHandler.h created by geert on Tue 09-Dec-1997 */

#import <Foundation/NSObject.h>
#import "FBDatabaseDefs.h"

@class NSData, NSDictionary, NSMutableArray, NSTimer, NSString;
@class FBAutoStartInfo;

@interface FBExecHandler : NSObject
{
@private
   NSString* execHostName;
   FBExecClientType clientType;
   id execSocket;
   BOOL ignoreBroadcasts;
   NSString *errorMsg;
   
   NSTimer *broadcastMessageTimer;
   NSMutableArray *broadcastMessageQueue;
}

// Each connection to a FBExec will register itself with its type (and
// other information) with the FBExec. Be sure to call +setClientType:
// before any handler is created, unless FBUnknownType will suffice for you.
+ (void) setClientType:(FBExecClientType) type;

//
// A connection to an FBExec on a given host is provided via a socalled
// handler object (FBExecHandler). Connection/handlers are cached and
// need not be retained nor released. If the connection cannot get
// established, nil is returned. A subsequent call to +errorMessage will
// return an error message.
//

+ (FBExecHandler *) handlerForHost:(NSString *) hostName clientType:(FBExecClientType) type;
+ (FBExecHandler *) handlerForHost:(NSString *) hostName;
+ (FBExecHandler *) handlerForThisHost;
+ (NSString *) errorMessage;

    // Use this when adding observers for broadcast messages
+ (NSString*) FBExecBroadcastNotification;


    ////////////////////////////////////////////////////////////////////////////////
    // Broadcast messages from various servers are ignored as default, but can be
    // enabled for all future handlers via the factory method. Individual
    // handlers can enable/disable the feature as they please.
    ////////////////////////////////////////////////////////////////////////////////

- (void) setIgnoreBroadcasts:(BOOL) ignore;
- (BOOL) ignoreBroadcasts;

- (NSString*)hostname;

- (void)setReadTimeout:(double)value;
- (void)setWriteTimeout:(double)value;

- (double)readTimeout;
- (double)writeTimeout
;
    ////////////////////////////////////////////////////////////////////////////////
    // Methods for inquiring about available databases and various pertinent
    // dynamic information.
    ////////////////////////////////////////////////////////////////////////////////

    // Available databases on the given host and their current status (as
    // an NSString, i.e. -intValue should be used to get the actual status)
- (NSDictionary *) availableDatabases;

    // The current status of the given database
- (FBDatabaseStatus) statusForDatabaseNamed:(NSString *) dbName;

    // The port number to use when connecting to the database
- (unsigned) portNumberForDatabaseNamed:(NSString *) dbName;

    // Remove "/usr/FrontBase/Databases/" and ".fb"
+ (NSString *) compactDatabaseName:(NSString *) dbName;

- (NSDictionary *)optionsForDatabaseNamed:(NSString *)databaseName;
    // Get the latest string of options the given database has been started with.
    // A return value of nil means that no options string is available.
- (NSString*) getOptionsForDatabaseNamed:(NSString *) dbName;


    ////////////////////////////////////////////////////////////////////////////////
    // Methods for managing the databases. All methods return YES if the action
    // seemingly went OK.
    ////////////////////////////////////////////////////////////////////////////////

    // Start an existing database
- (BOOL) startDatabaseNamed:(NSString *) dbName;
- (BOOL) startDatabaseNamed:(NSString *) dbName  fbexecPassword:(NSString*) clearTextPassword;

- (BOOL) startDatabaseNamed:(NSString *) dbName withOptions:(NSString*) options;
- (BOOL) startDatabaseNamed:(NSString *) dbName withOptions:(NSString*) options
             fbexecPassword:(NSString*) clearTextPassword;

    // Create a database from scratch. Please note that this will also start the
    // database (which is the only to create a database).
- (BOOL) createDatabaseNamed:(NSString *) dbName;
- (BOOL) createDatabaseNamed:(NSString *) dbName  fbexecPassword:(NSString*) clearTextPassword;

- (BOOL) createDatabaseNamed:(NSString *) dbName withOptions:(NSString*) options;
- (BOOL) createDatabaseNamed:(NSString *) dbName withOptions:(NSString*) options
              fbexecPassword:(NSString*) clearTextPassword;

    // Delete a database, i.e. remove the physical file and associated log file.
    // This requires that the database isn't running.
- (BOOL) deleteDatabaseNamed:(NSString *) dbName;
- (BOOL) deleteDatabaseNamed:(NSString *) dbName  fbexecPassword:(NSString*) clearTextPassword;

    // Kill (unconditionally) the given database. This is supposed
    // be to the last resort. The preferred way is to send stopDatabase
    // via an FBDatabaseConnection instance.
- (BOOL) killDatabaseNamed:(NSString *) dbName;

    // Rename the given (stopped) database
- (BOOL) renameDatabaseNamed:(NSString *) oldName to:(NSString*) newName;
- (BOOL) renameDatabaseNamed:(NSString *) oldName to:(NSString*) newName  fbexecPassword:(NSString*) clearTextPassword;

    // Start some app in <install path>/FrontBase/bin
- (BOOL) startFrontBaseBinApp:(NSString *) appName  options:(NSString*) options  fbexecPassword:(NSString*) clearTextPassword;

    ////////////////////////////////////////////////////////////////////////////////
    // Methods for retrieving information about replicators
    ////////////////////////////////////////////////////////////////////////////////

    // Keys are databases and values are replicator ports.  A replicator port of zero
    // indicates that no replicator is running for that database.  Ports are stored as
    // strings, so use -intValue as appropriate.
- (NSDictionary *)availableReplicators;

    ////////////////////////////////////////////////////////////////////////////////
    // Misc. methods for extracting useful information
    ////////////////////////////////////////////////////////////////////////////////

- (NSString *)uniqueIdentifier;
    // Identical to [NSHost hostWithName:hostName], where hostName is as given
    // to +handlerForHost:

    // If any method failed, -errorMessage will typically provide an explanation
- (NSString *) errorMessage;

- (BOOL)connected;

    // Disconnect the handler from the FBExec
- (void) disconnect;

    // Send a command to the FBExec and get a response. If the response
    // indicates an error, the reply will be nil and a subsequent call
    // to -errorMessage will return the message. If everything is OK,
    // the actual reply is returned. For commands that do not generate
    // a response per se, "OK" is returned.

- (NSString *) sendCommandToExec:(NSString *) cmd;

    // Returns an FBAutoStartInfo object representing the list of databases (and the associated
    // start options) that the FBExec will start when itself has been started with the -autostart
    // option.
- (FBAutoStartInfo*) autoStartInfo;

    // Specifies a list to the FBExec detailing the databases and the associated options that
    // are to be started automatically when the FBExec is started with the -autostart option.
    // NO is returned if there was a problem, -errorMessage will give the reason.
- (BOOL) setAutoStartInfo:(FBAutoStartInfo*) startInfo  :(NSString*) clearTextPassword;

    // Misc. (for internal use)
- (NSString*) keywordsText;

    // Get a property list denoting the directories and files found in the FrontBase installation
    // directory. A return value of nil indicates an error condition (use -errorMessage).
- (id)getFBDirAsPropertyList:(NSString *)clearTextPassword;

    // Get the contents of a text file located somewhere in the FrontBase installation directory
    // (the full path name has to be specified).
- (NSString *)getFBTextFile:(NSString *)fullPathName fbexecPassword:(NSString *)clearTextPassword;

    // Get the contents of a data file located somewhere in the FrontBase installation directory
    // (the full path name has to be specified).
- (NSData *)getFBDataFile:(NSString *)fullPathName fbexecPassword:(NSString *)clearTextPassword;

    // Get the last entry from the database log file.  Useful for figuring out why a database
    // won't start.
- (NSString *) getDatabaseLogTailForDatabaseNamed:(NSString *) dbName;

- (BOOL)deleteReplicatorFileForDatabaseNamed:(NSString *)databaseName;

- (unsigned int)portForClientNamed:(NSString *)clientName;
- (unsigned int)portForClientNamed:(NSString *)clientName type:(FBExecClientType)type;

@end

extern NSString *FBExecHandlerBroadcastMessageKey;
