Introduction

This document describes various routines exported by NetFinder that can be accessed via ICI script. The purpose of these exported routines, are to allow power users to write their own scripts to automate a task.

Examples of scripts that can be written are:

The list of ideas are endless.

Contents

Standard Lib Routines


NFLoadModuleConstants();

Description: Loads constants used by NetFinder exported routines to make scripts
             more readable.
Parameters:  none
Returns:     null



NFGetModuleVersion();

Description: Returns the version of the current set of exported routines by
             NetFinder.
Parameters:  none
Returns:     string representing the version of the routines exported.

FTP Routines


int = NFCreateFTPInstance();

Description: Creates an FTP reference (inRef in routines below) to be used to
             perform FTP operations.
Parameters:  none
Returns:     int = opaque reference.

History: v0.1.1 - now setup ISO etc prefs.


NFDeleteFTPInstance(int inRef);

Description: Cleans up memory among other things previously created by a call
             to NFCreateFTPInstance().
Parameters:  inRef = int (opaque reference) returned by NFCreateFTPInstance().
Returns:     null



int = NFConnect(int inRef, string inHostname, int inPort
                [, string inUsername, string inPassword]);

Description: Connects to a server using the protocol defined by inRef and
             the host and port as specificed. Optionally using the username
             and password provided, else anonymous/guest access is attempted.
Parameters:  inRef = protocol reference. eg from NFCreateFTPInstance().
             inHostname = host to connect to.
                   eg "ftp.cdrom.com" or "127.0.0.1"
             inPort = port to connect to.
             inUsername = account to login as. This parameter is optional
                   and is defaulted to "anonymous".
             inPassword = password associated with your login account.
                   This parameter is optional and is defaulted to
                   "netfinder@home.com".
Returns:     returns an int representing any errors that may have occured.
             Zero = no error.



int = NFDisconnect(int inRef);

Description: Disconnects from the server previously connected to via a call
             to NFConnect().
Parameters:  inRef = protocol reference. eg from NFCreateFTPInstance().
Returns:     returns an int representing any errors that may have occured.
             Zero = no error.



int = NFUseProxyServer(int inRef,
                string inProxyHost, int inProxyPort, string inProxyUsername,
                string inProxyPassword, int inProxyType);

Description: Setup the FTP instance to use a Proxy.
Parameters:  inRef = protocol reference. eg from NFCreateFTPInstance().
             inProxyHost = proxy hostname.
             inProxyPort = proxy port. Use zero to use default port for the 
                           specified type. eg 1080 for SOCKS, 21 for FTP Proxy.
             inProxyUsername = proxy username.
             inProxyPassword = proxy password.
             inProxyType = proxy type.
                           0 = No Proxy
                           1 = FTP Proxy
                           2 = SOCKS Proxy
Returns:     returns an int representing any errors that may have occured.
             Zero = no error.



int = NFSendFile(int inRef, string inPath, int inMode, string inLocalHDPath,
                 int inEncodingType, func inCallback, object inCallbackUsrData);

Description: Receives a files from the server.
Parameters:  inRef = protocol reference. eg from NFCreateFTPInstance().
             inPath = path to file to receive.
             inMode = eBinaryType (0) or eASCIIType (1).
             inLocalHDPath = path to local disk (includes filename).
             inDecodeType = eRawData ('RAWD'), eMacBinary ('.bin'),
                            eBinhex ('.hqx'), eText ('.txt'),
                            eUnknown ('????') = > Intelligent Download.
             inCallback = function which takes three parameters (can be NULL):
             	
             	Callback(object inCallbackUsrData, int inSelector, inSelectorData)
             	
             	inSelectorData type varies with inSelector.
             
             inCallbackUsrData = object that is passed to the callback. Can be NULL.
             		
Returns:     returns an int representing any errors that may have occured.
             Zero = no error.



int = NFReceiveFile(int inRef, string inPath, int inMode, string inLocalHDPath,
                    int inDecodeType, func inCallback, object inCallbackUsrData);
Description: Receives a files from the server.
Parameters:  inRef = protocol reference. eg from NFCreateFTPInstance().
             inPath = path to file to receive.
             inMode = eBinaryType (0) or eASCIIType (1).
             inLocalHDPath = path to local disk (includes filename).
             inDecodeType = eRawData ('RAWD'), eMacBinary ('.bin'),
                            eBinhex ('.hqx'), eText ('.txt'),
                            eUnknown ('????') = > Intelligent Download.
             inCallback = function which takes three parameters (can be NULL):
             	
             	Callback(object inCallbackUsrData, int inSelector, inSelectorData)
             	
             	inSelectorData type varies with inSelector.
             
             inCallbackUsrData = object that is passed to the callback. Can be NULL.
             		
Returns:     returns an int representing any errors that may have occured.
             Zero = no error.



int = NFMakeDirectory(int inRef, string inDirPath);

Description: Created a directory given the specified path.
Parameters:  inRef = protocol reference. eg from NFCreateFTPInstance().
             inDirPath = a string representing a full path of where to
                   create a new directory.
Returns:     returns an int representing any errors that may have occured.
             Zero = no error.



int = NFChangeWorkingDirectory(int inRef, string inDirPath);

Description: Change to the directory specified.
Parameters:  inRef = protocol reference. eg from NFCreateFTPInstance().
             inDirPath = a string representing a full path of where to
                   change directories to.
Returns:     returns an int representing any errors that may have occured.
             Zero = no error.



int = NFGotoParentDirectory();

Description: Changes to the parent directory relative to the current working
             directory.
Parameters:  none
Returns:     returns an int representing any errors that may have occured.
             Zero = no error.



int = NFGetWorkingDirectory(int inRef, string* outDirPath);

Description: Obtains the current working directory.
Parameters:  inRef = protocol reference. eg from NFCreateFTPInstance().
             outDirPath = the current working directory path is returned
                   via this string parameter.
Returns:     returns an int representing any errors that may have occured.
             Zero = no error.



int = NFListDirectory(int inRef, string inDirPath, int inVerbose, 
                      array* outList);

Description: Obtains a listing of items from the specified path.
Parameters:  inRef = protocol reference. eg from NFCreateFTPInstance().
             inDirPath = path from which to get a listing from.
             inVerbose = 0, 1, which basically returns filenames only or
                   filenames plus other attirbutes like filesize etc.
             outList = an array of structures is returned in this parameter
                   (see below) representing the list of items plus their
                   attributes.
                   
                   ICI structure representation (with sample data):
                   
                   [array
                      [struct
                         name = "filename", /* string */
                         link = "sym link", /* string */
                         owner = "peter",   /* string */
                         group = "users",   /* string */
                         size = 1234,       /* int */
                         kind = 2,          /* int = bit field of attributes */
                         perm = 0,          /* int = bit field of attributes */
                         date_day = 1,      /* int = day */
                         date_month = 1,    /* int = month, Jan = 1 */
                         date_year = 2000,  /* int = 4 digit year */
                         time_minutes = 1   /* int = minutes since midnight */
                      ]
                   ]
                   
                   The following bit fields and constants are available for
                   the "kind" key and the "perm" key:
                   
                   kind
                   ----
                   o eUnknownItem           = 0x0000,
                   o eDirectoryItem         = 0x0001,
                   o eFileItem              = 0x0002,
                   o eExecutableItem        = 0x0004,
                   o eLinkItem              = 0x0008,
                   o eBlockItem             = 0x0010,
                   o eCharSpecialFileItem   = 0x0020,
                   o ePipeSpecialFileItem   = 0x0040,
                   
                   perm
                   ----
                   o eOwnerRdPerm = 0x400, // owner r
                   o eOwnerWrPerm = 0x200, // owner w
                   o eOwnerExPerm = 0x100, // owner x
                   o eGroupRdPerm = 0x040, // group r
                   o eGroupWrPerm = 0x020, // group w
                   o eGroupExPerm = 0x010, // group x
                   o eWorldRdPerm = 0x004, // everyone r
                   o eWorldWrPerm = 0x002, // everyone w
                   o eWorldExPerm = 0x001  // everyone x
                   
Returns:     returns an int representing any errors that may have occured.
             Zero = no error.



int = NFRename(int inRef, string inRenameFrom, string inRenameTo);

Description: Renames an object from an old name to a new name.
Parameters:  inRef = protocol reference. eg from NFCreateFTPInstance().
             inRenameFrom = path to the old object. eg "/bin/oldname"
             inRenameTo = path to the new object. eg "/bin/newname"
Returns:     returns an int representing any errors that may have occured.
             Zero = no error.



int = NFDeleteFile(int inRef, string inFilePath);

Description: Deletes a file specified by the path.
Parameters:  inRef = protocol reference. eg from NFCreateFTPInstance().
             inFilePath = path to the file to delete.
Returns:     returns an int representing any errors that may have occured.
             Zero = no error.



int = NFDeleteDirectory(int inRef, string inDirPath);

Description: Deletes a directory specified by the path.
Parameters:  inRef = protocol reference. eg from NFCreateFTPInstance().
             inFilePath = path to the directory to delete.
Returns:     returns an int representing any errors that may have occured.
             Zero = no error.



int = FNCopyFile(int inRef, string inSrcPath, string inDstPath);

Description: Copies a file from the source to the destination path.
Parameters:  inRef = protocol reference. eg from NFCreateFTPInstance().
             inSrcPath = path to the source file. eg "/bin/filename.txt"
             inDstPath = path to the destination. eg "/usr/bin/"
Returns:     returns an int representing any errors that may have occured.
             Zero = no error.



int = NFMoveFile(int inRef, string inSrcPath, string inDstPath);

Description: Moves an object from the source to the destination path.
Parameters:  inRef = protocol reference. eg from NFCreateFTPInstance().
             inSrcPath = path to the source file. eg "/bin/filename.txt"
             inDstPath = path to the destination. eg "/usr/bin/"
Returns:     returns an int representing any errors that may have occured.
             Zero = no error.



int = NFSendMACB(int inRef, int inEnable);

Description: Request MacBinary transfers from the server to be Enabled
             or Disables. Not all servers support this.
Parameters:  inRef = protocol reference. eg from NFCreateFTPInstance().
             inEnable = 0, 1 to signify disabling and enabling.
Returns:     returns an int representing any errors that may have occured.
             Zero = no error.



int = NFPing(int inRef);

Description: Sends a "ping" to the server to try and keep it connected.
             For FTP this represents a NOOP.
Parameters:  inRef = protocol reference. eg from NFCreateFTPInstance().
Returns:     returns an int representing any errors that may have occured.
             Zero = no error.



int = NFRemoteSystemType(int inRef, string* outRemoteSysType);

Description: Returns the result of a SYST command.
Parameters:  inRef = protocol reference. eg from NFCreateFTPInstance().
             outRemoteSysType = where to store the result.
Returns:     returns an int representing any errors that may have occured.
             Zero = no error.



int = NFSendCommandString(int inRef, string inCommandStr, string* outServerReply);

Description: Use this to send a FTP command to the server.
Parameters:  inRef = protocol reference. eg from NFCreateFTPInstance().
             inCommandStr = command to send to the server.
             outServerReply = reply of the server to the command sent.
Returns:     returns an int representing any errors that may have occured.
             Zero = no error.
             
NOTE:        This command only returns a single line reply (the last one) if
             a multi line reply is returned.



int = NFSetUMASK(int inRef, int inPermissions);

Description: Sets the default upload permissions of the server for the current
             login account.
Parameters:  inRef = protocol reference. eg from NFCreateFTPInstance().
             inPermissions = permissions to use. See NFListDirectory().
Returns:     returns an int representing any errors that may have occured.
             Zero = no error.



int = NFSetFilePermissions(int inRef, string inPath, int inPermissions);

Description: Sets the permissions of a file/folder on the server.
Parameters:  inRef = protocol reference. eg from NFCreateFTPInstance().
             inPath = path of the item you wish to set permissions of.
             inPermissions = permissions to use. See NFListDirectory().
Returns:     returns an int representing any errors that may have occured.
             Zero = no error.

TCPIP Routines


int = NFCreateSocket(int inOptions, int inOptionsData);

Description: Creates a TCP socket for you to sent and receive anything you like
             to the server you connect to. eg You may wish to create a very simple
             email sending script, so that you can mail yourself when a task
             is complete.

Parameters:  inOptions = pass zero.
             inOptionsData = pass zero.
Returns:     returns a reference to a socket.



int = NFDeleteSocket(int inSocketRef);

Description: Releases any resources used to create the socket.

Parameters:  inSocketRef = references to a socket.

Returns:     returns an int representing any errors that may have occured.
             Zero = no error.
 


int = NFOpenConnection(int inSocketRef, string inHostname, int inPort);

Description: Establishes a connection to the specified hostname and port.

Parameters:  inSocketRef = references to a socket.
             inHostname = server to connect to.
             inPort = port you wish to connect to. eg 21 = FTP, 80 = HTTP etc.

Returns:     returns an int representing any errors that may have occured.
             Zero = no error.



int = NFWaitForConnection(int inSocketRef [, int inPort [, int inRange]]);

Description: Request that the socket listen for an incoming connection.

Parameters:  inSocketRef = references to a socket.
             inPort = optional, specify the port you with to listen on.
             inRange = optional, if you specify a port, you can also specify
                   a range of ports to pick from.

Returns:     returns an int representing any errors that may have occured.
             Zero = no error.



int = NFBlockTillConnectionUp(int inSocketRef);

Description: Use this routine to guarentee everything is ready before sending
             or receiving data.

Parameters:  inSocketRef = references to a socket.

Returns:     returns an int representing any errors that may have occured.
             Zero = no error.



int = NFIsSecureConnection(int inSocketRef);

Description: Use this routine to determine if a connection that has been
             established is secured via SSL.

Parameters:  inSocketRef = references to a socket.

Returns:     returns 1 if connection is secure, otherwise it returns 0.



int = NFCloseConnection(int inSocketRef);

Description: Closes a connected socket.

Parameters:  inSocketRef = references to a socket.

Returns:     returns an int representing any errors that may have occured.
             Zero = no error.



int = NFAbortConnection(int inSocketRef);

Description: Aborts the connection established on a socket.

Parameters:  inSocketRef = references to a socket.

Returns:     returns an int representing any errors that may have occured.
             Zero = no error.



int = NFSend(int inSocketRef, string inData, int inLen [, int inUrgent]);

Description: Sends a specified amount of data through a socket.

Parameters:  inSocketRef = references to a socket.
             inData = data you wish to send through the socket.
             inLen = length of data you wish to send.
             inUrgent = optional, specify if you wish to send the data with
                   the "urgent" flag set.

Returns:     returns an int representing any errors that may have occured.
             Zero = no error.



int = NFReceive(int inSocketRef, int* ioLen, string* outData);

Description: Receives data from a specific socket.

Parameters:  inSocketRef = references to a socket.
             ioLen = on entry this specifies the amount of data to receive.
                   on exit this returns the amount of data read.
             outData = received data will be returned in here.

Returns:     returns an int representing any errors that may have occured.
             Zero = no error.

NOTE:        This routine blocks until the requested amount of data is obtained
             or the connection drops.
             Use NFGetUnreadDataLength() to determine how much data is available.



int = NFPeek(int inSocketRef, int* ioLen, string* outData);

Description: This routine is identical to NFReceive, except it does not remove the
             data from the receive buffer.

Parameters:  inSocketRef = references to a socket.
             ioLen = on entry this specifies the amount of data to receive.
                   on exit this returns the amount of data read.
             outData = received data will be returned in here.

Returns:     returns an int representing any errors that may have occured.
             Zero = no error.

NOTE:        This routine blocks until the requested amount of data is obtained
             or the connection drops.



int = NFFlushIncomingData(int inSocketRef);

Description: To flush any no longer needed incoming data from the socket, call
             this routine.

Parameters:  inSocketRef = references to a socket.

Returns:     returns an int representing any errors that may have occured.
             Zero = no error.



int = NFGetDataPipeState(int inSocketRef);

Description: Gets the state of the socket.

Parameters:  inSocketRef = references to a socket.

Returns:     The State.
             0 = uninitialized.
             1 = unbound.
             2 = idle.
             3 = out connect.
             4 = in connect.
             5 = connected.
             6 = out disconnect.
             7 = in disconnect.
             8 = unknown.




int = NFIsConnectionUp(int inSocketRef);

Description: Returns whether the connection is still up.

Parameters:  inSocketRef = references to a socket.

Returns:     0 = disconnected, 1 = connection up.



int = NFGetUnreadDataLength(int inSocketRef);

Description: Returns the amount of data available for reading.

Parameters:  inSocketRef = references to a socket.

Returns:     number of bytes available.



int = NFGetLocalAddress(int inSocketRef, int* outIP, int* outPort);

Description: Used to retrieve the local IP and port used upon establishing a
             connection.

Parameters:  inSocketRef = references to a socket.
             outIP = IP of the local connection.
             outPort = port of the local connection.

Returns:     returns an int representing any errors that may have occured.
             Zero = no error.



int = NFGetRemoteAddress(int inSocketRef, int* outIP, int* outPort);

Description: Used to retrieve the remote IP and port used upon establishing a
             connection.

Parameters:  inSocketRef = references to a socket.
             outIP = IP of the local connection.
             outPort = port of the local connection.

Returns:     returns an int representing any errors that may have occured.
             Zero = no error.



int = NFGetRxAvgRate(int inSocketRef);

Description: Returns a rough average receive transfer rate.

Parameters:  inSocketRef = references to a socket.

Returns:     returns the number of bytes per second.



int = NFGetTxAvgRate(int inSocketRef);

Description: Returns a rough average sending transfer rate.

Parameters:  inSocketRef = references to a socket.

Returns:     returns the number of bytes per second.



int = NFGetRxCurRate(int inSocketRef);

Description: Returns a rough current receive transfer rate.

Parameters:  inSocketRef = references to a socket.

Returns:     returns the number of bytes per second.



int = NFGetTxCurRate(int inSocketRef);

Description: Returns a rough current sending transfer rate.

Parameters:  inSocketRef = references to a socket.

Returns:     returns the number of bytes per second.



int = NFGetTotalSent(int inSocketRef);

Description: Used to determine the total number of bytes this socket sent.

Parameters:  inSocketRef = references to a socket.

Returns:     returns the number of bytes sent.



int = NFGetTotalRead(int inSocketRef);

Description: Used to determine the total number of bytes this socket received.

Parameters:  inSocketRef = references to a socket.

Returns:     returns the number of bytes received.



int = NFSendCommandStr(int inSocketRef, string inCommandStr);

Description: Used to send a internet command through the socket. Generally this
             means sending a string followed by CRLF. This routine is useful
             for implementing most Internet based protocols.

Parameters:  inSocketRef = references to a socket.
             inCommandStr = command you wish to send.

Returns:     returns an int representing any errors that may have occured.
             Zero = no error.



int = NFReceiveLine(int inSocketRef, string* outLine);

Description: Used to receive an internet reply through the socket. Generally this
             means receiving a string followed by CRLF. This routine is useful
             for implementing most Internet based protocols.

Parameters:  inSocketRef = references to a socket.
             outLine = received line of reply is returned in here.

Returns:     returns an int representing any errors that may have occured.
             Zero = no error.

-----------------------------

int = NFEstablishSecurePipe(int inSocketRef);

Description: Once a connection is established and you know you can establish
             a secure connection via SSL, call this routine. Upon a successful
             call to this routine, all data is then sent/received as encrypted
             data.

Parameters:  inSocketRef = references to a socket.

Returns:     returns an int representing any errors that may have occured.
             Zero = no error.

Misc Network Routines


int = NFStringToAddress(string inName [, int inTimeout]);

Description: Give an internet name, this routines looks up the IP address.
Parameters:  inName - name to resolve.
             inTimeout - timeout. Default is 10 seconds.
Returns:     returns the IP address or zero if an error/timeout occured.



int = NFAddressToString(int inIP, string* outName [, int inTimeout]);

Description: Converts an IP address into a name.

Parameters:  inIP - ip address to convert.
             outName - where to return the result.
             inTimeout - optional timeout. Defaults to 10 seconds.
Returns:     returns anny errors that occured or zero for no error.

Example:     string name;
             int err = NFAddressToString(NFGetLocalIP(), & name);
             
             /* if local IP is 192.168.0.1 
                (hex = 0xC0A80001, dec = 3232235521)
                then name could be returned as "192.168.0.1"
                or say "machine1.mysite.com"
              */



int = NFGetLocalIP();

Description: Returns a 4 byte IP address of the local machine.
Parameters:  none
Returns:     IP address of local machine.



int = NFIsSSLAvailable();

Description: Used to determine if SSL is available to NetFinder.
Parameters:  none
Returns:     returns 1 if SSL is available, 0 otherwise.

NetFinder Preference Routines


int = NFGetPrefs(int inPrefID);

Description: Gets the current value of a NetFinder preferences. See list of
             available preferences below.

Parameters:  inPrefID = ID of the preferences to receive.

Returns:     value of preference returned.



int = NFSetPrefs(int inPrefID, int inNewPrefValue);

Description: Sets the current value of a NetFinder preferences. See list of
             available preferences below.

Parameters:  inPrefID = ID of the preferences to set.
             inNewPrefValue = new value of preference, see list below.

Returns:     returns any errors, or zero for no error.



int = NFSyncPrefs();

Description: Syncs all existing objects in the system to use the new prefs.

Parameters:  none

Returns:     null


//////////// Preference ID Definitions ///////////////


//  connections:
    ePrefConnectionLogTransfersCheckBox     =    'Tfer',        //    0 = no logging of transfers, 1 = otherwise
    ePrefConnectionLogTranscriptCheckBox    =    'Tscr',        //    0 = no logging of transcript, 1 = otherwise
    ePrefConnectionKeepAliveCheckBox        =    'Aliv',        //    0 = do not keep connections alive, 1 = otherwise
    ePrefConnectionPORTPASVCheckBox         =    'CTyp',        //    0 = PORT, 1 = PASV
    ePrefConnectRetryInterval               =    'RtIn',        //    in seconds
    ePrefConnectionUseOneConnPerServer      =    '1Con',        //    0 = false, 1 = true

//  listings:
    ePrefListingShowInvisiblesCheckBox      =    'LInv',        //    0 = do not show invisibles, 1 = otherwise
    ePrefListingResolveCheckBox             =    '-alL',        //    0 = do not resolve links, 1 = otherwise
    ePrefListingGuessAliasTypeCheckBox      =    '?Lnk',        //    0 = dont guess alias type, 1 = otherwise
    ePrefListingCacheCheckBox               =    'Cach',        //    0 = do not cache listings, 1 = always use cache, 2 = always use cache (but update once per session).
    ePrefListingRefreshCheckBox             =    'Refr',        //    0 = do not refresh, 1 = otherwise
    ePrefListingCWDLISTRadioGroup           =    'LIST',        //    0 = LIST only; 1 = CWD/LIST
    ePrefListingFontSize                    =    'FntS',        //    font size = { 9, 10, 12, 14, 16, 18, 24 }
    ePrefListingFontName                    =    'FntN',        //    family ID [ stored on disk as font name ]

//  display:
    ePrefDisplayScriptAwareSortingCheckBox  =    'Scri',        //    0 = assume english; 1 = use Script Manager
    ePrefDisplayFolderIconsCheckBox         =    'FldI',        //    0 = plain folders; 1 = use world permission
    ePrefDisplayAllowRenameCheckBox         =    'RNOK',        //    0 = disallow renaming; 1 = allow renaming
    ePrefDisplayNoRenameDelayCheckBox       =    'NoRD',        //    0 = rename with delay; 1 = rename but no delay
    ePrefDisplaySmoothRedrawsCheckBox       =    'SRDr',        //    1 = smooth, 0 = less smooth.

//  download:
    ePrefDownloadPostProcessCheckBox        =    'DPP?',        //    0 = do not post process, 1 = otherwise
    ePrefDownloadPPInBackgroundCheckBox     =    'DPPB',        //    0 = post process in foreground, 1 = otherwise
    ePrefDownloadPlaySoundCheckBox          =    'DSnd',        //    0 = no sound, 1 = otherwise
    ePrefDownloadDuplicateRadioGroup        =    'DDup',        //    0 = new name, 1 = ask, 2 = replace file
    ePrefDownloadPartialRadioGroup          =    'DPar',        //    0 = keep, 1 = ask, 2 = delete
    ePrefDownloadDLTypeRadioGroup           =    'DTyp',        //    0 = intelligent, 1 = binary, 2 = text
    ePrefDownloadResumableVsSpeed           =    'RvsS',        //    0 = slow + most reliable, 1 = fast + reliable, 2 = fastest + not reliable (crash proof resumes)
    ePrefDownloadIntelligentRadioGroup      =    'Inte',        //    0 = try binhex first; 1 = try MacBinary first
    ePrefDownloadAddURL                     =    '+URL',        //    0 = dont add URL to get info comments, 1 = otherwise

//  upload:
    ePrefUploadInvisibleFilesRadioGroup     =    'UInv',        //    0 = do not upload, 1 = upload
    ePrefUploadDontAddDotHqxExtension       =    'HqxE',        //    0 = append .hqx on BinHex uploads, 1 = dont add extension.
    ePrefUploadDontAddDotBinExtension       =    'BinE',        //    0 = append .bin on MacBinary uploads, 1 = dont add extension.
    ePrefUploadUploadFilesRadioGroup        =    'UTyp',        //    0 = use IC, 1 = MacBinary, 2 = Binhex 4.0, 3 = binary, 4 = text
    ePrefUploadULPermActive                 =    'ULPA',        //    0 = inactive, 1 = active
    ePrefUploadDefaultUploadPermission      =    'DFUP',        //    (short 9 bits long)

//  deleting:
    ePrefDeleteConfirmRadioGroup            =    'XAsk',        //    0 = always ask, 1 = ask for directories, 2 = always delete

//  misc:
    ePrefNOOPInterval                       =    'NOOP',        //    in ticks (1/60 sec)

//  general:
    ePrefGeneralExportPasswords             =    'ExPW',        //    0 = never export password, 1 = do export password
    ePrefGeneralRetryIfBusy                 =    'Rtry',        //    0 = dont retry if server busy, 1 = otherwise
    ePrefGeneralShowNewConnectionDialog     =    'SNCD',        //    0 = no show, 1 = show
    ePrefGeneralISOCheckBox                 =    'ISO ',        //    0 = dont use ISO text encoding, 1 = otherwise
    ePrefGeneralIconsInMenus                =    'MIcn',        //    0 = dont show icons, 1 = otherwise

//  get attention:
    ePrefGetAttentionSoundCheckBox          =    'Snd ',        //    0 = dont use sound notification, 1 = otherwise

    ePaneGettingAttentionConnectCheckBox    =    'SndC',        //    0 = dont play sound on connect, 1 = otherwise
    ePaneGettingAttentionDownloadCheckBox   =    'SndD',        //    0 = dont play sound on download completion, 1 = otherwise
    ePaneGettingAttentionUploadCheckBox     =    'SndU',        //    0 = dont play sound on upload completion, 1 = otherwise
    ePaneGettingAttentionRemoteCopyCheckBox =    'SndR',        //    0 = dont play sound on copy completion, 1 = otherwise
    ePaneGettingAttentionDeleteCheckBox     =    'SndX',        //    0 = dont play sound on delete completion, 1 = otherwise
    ePaneGettingAttentionAbortCheckBox      =    'SndA',        //    0 = dont play sound on abort, 1 = otherwise

    ePrefGetAttentionGetAttentionRadioGroup =    'Attn',        //    0 = none; 1 = icon + system alert sound; 2 = alert

//	edit/actions:
    ePrefEditOpenBehaviour                  =    'EOpB',        //    0 = normal, 1 = finder_open, 2 = view, 3 = edit in BBEdit
    ePrefEditUploadBehaviour                =    'EULB',        //    0 = ask user, 1 = always, 2 = never
    ePrefEditTransferFormat                 =    'ETFM',        //    0 = Binary, 1 = Text
    ePrefEditEditorCreatorID                =    'ECID',        //    creator ID of editor, default is 'R*ch' = BBEdit

    ePrefActionEnableStreamedDL             =    'StDL',        //    0 = false, 1 = true

NetFinder Miscellaneous Routines


NFSetICIPeriodicalTime([int inPeriodicalTimeInSeconds]);

Description: Sets the time between periodical script executions to the
             specified number of seconds.

Parameters:  inPeriodicalTimeInSeconds - period in seconds. This field is
                   optional and defaults to 60 seconds.

Returns:     none.



NFSendEngineFTPCommand( string inCommand, 
                        [string inHost,
                        [int inPort,
                        string inUsername,
                        string inPassword]]);

Description: Sends a FTP command to the specified active FTP connections.

Parameters:  inCommand - command to send to server. eg "SITE HELP"
             inHost - optional, host to send command to.
             inPort - optional, port for the specified host.
             inUsername - optional, username of the specified host.
             inPassword - optional, password of the specified host.

Returns:     none.

NetFinder GUI Helpers


NFSetModifiersForCommand(int inCommandID, string inModifierStr);

Description: Changes or deletes a modifier key for a command for a given
             menu item in NetFinder.

Parameters:  inCommandID - See list below.
             inModifierStr - is say "\aocsP", where
             
             \ = command/modifier key sequence begin tag
             a = Apple Key Modifier
             o = Option Key Modifier
             c = Control Key Modifier
             s = Shift Key Modifier
             P = command key to use, in this case the letter 'P'.
             
             NOTE: the order of modifiers is important.

Returns:     none.

Example:     NFLoadModuleConstants();
             NFSetModifiersForCommand(kCmdSetPermissions, "\\oP");  /* OPTION + P */
             
             /* NOTE: the "\\" since we must escape the "\" which is a special
                character in ICI */

//////////// Command ID Definitions ///////////////


    // File Menu:
    kCmdNewConnection       =    'NEWC',        // maps to "cmd_New"
    kCmdNewFolder           =    'NDir',
    kCmdFileOpen            =    'OPEN',        // maps to "cmd_Open"
    kCmdFileClose           =    'CLOS',        // maps to "cmd_Close"

    kCmdFileSave            =    'SAVE',        // maps to "cmd_Save"
    kCmdFileSaveAs          =    'SAVA',        // maps to "cmd_SaveAs"

    kCmdRefreshSelection    =    'Refr',
    kCmdGetInfo             =    'Info',

    kCmdDuplicateSelection  =    'Dupl',
    kCmdDeleteSelection     =    'DelS',
    kCmdMakeAlias           =    'Alis',
    kCmdPutAway             =    'PutA',
    
    kCmdUpToParentDir       =    'CDUP',
    
    kCmdFilePageSetup       =    'PGSU',        // maps to "cmd_PageSetup"
    kCmdFilePrintWindow     =    'PRIN',        // maps to "cmd_Print"
    kCmdFileQuit            =    'QUIT',        // maps to "cmd_Quit"
    
    // View As (Sub Menu)
    kCmdView                =    'View',
    kCmdViewInBrowser       =    'VBrw',
    kCmdViewAsText          =    'VTxt',
    kCmdViewAsGraphic       =    'VGrf',
    
    // Edit Menu:
    kCmdEditUndo            =    'EUnd',        // maps to "cmd_Undo"
    kCmdEditCut             =    'ECut',        // maps to "cmd_Cut"
    kCmdEditCopy            =    'ECpy',        // maps to "cmd_Copy"
    kCmdEditPaste           =    'EPst',        // maps to "cmd_Paste"
    kCmdEditClear           =    'EClr',        // maps to "cmd_Clear"
    kCmdEditSelectAll       =    'SAll',        // maps to "cmd_SelectAll"
    kCmdEditInBBEdit        =    'BBEd',
    kCmdShowICPrefsWin      =    'ICfg',        // Bring up InternetConfig Prefs Window
    kCmdShowNFPrefsWin      =    'NFPW',        // Bring up NF Prefs Window
    
    // Tools Menu:
    kCmdSetPermissions      =    'SPrm',
    kCmdUpload              =    'STOR',
    kCmdChangeDirectory     =    'CWD ',
    kCmdNewFile             =    'NFil',
    
    // Label Menu:
    kCmdLabelNone           =    'Lab0',
    kCmdLabel7              =    'Lab7',
    kCmdLabel6              =    'Lab6',
    kCmdLabel5              =    'Lab5',
    kCmdLabel4              =    'Lab4',
    kCmdLabel3              =    'Lab3',
    kCmdLabel2              =    'Lab2',
    kCmdLabel1              =    'Lab1',

    // Lists Menu:
    kCmdNewBookmarkList     =    'NwBL',
    kCmdNewMirrorList       =    'NwML',
    kCmdNewDownloadQueue    =    'NwDQ',
//  kCmdFileOpen            =    'OPEN',        // maps to "cmd_Open"
    kCmdNewBookmarkItem     =    'NBkm',
    kCmdImportBookmarkItem  =    'Impt',
    kCmdExportBookmarkItem  =    'Expt',        // not implemented
    kCmdNewMirrorItem       =    'NwMI',
    
    // Windows Menu:
    kCmdZoomWindow          =    'ZOOM',
    kCmdShowTranscriptWin   =    'STrn',
    kCmdShowTransferLogWin  =    'STxL',
    kCmdShowPartialFileWin  =    'SPFl',

    // Scripts Menu:
    kCmdOpenScriptsFolder   =    'Scpt',
    kCmdRefreshScriptsMenu  =    'SptR',

    // Favorites/Shortcuts Menu:
    kCmdAddToFavorites      =    'FavA',
    kCmdOrganizeFavorites   =    'FavO',
    kCmdRefreshFavorites    =    'FavR',


NFSetGlyphForCommand(int inCommandID, int inGlyph);

Description: Sets a Glyph for a command key, eg F12.

Parameters:  inCommandID - see list above.
             inGlyph - glyph ID. See sample script in "NetFinder Startup Items"
                       called "Command Key Setup Script"

Returns:     none.


int = NFFindCommandStatus(string inCommandID);

Description: Used to see if a menu command is currently available.

Parameters:  inCommandID = command ID. These ID's are not released to the pubic.
                        If you like to hack, then these are Metrowerks Constructor command ID's.

Returns:     1 = command is available, 0 = command is not available.

Version:    v0.2

NFObeyCommand(string inCommandID);

Description: Executes a command as if the user selected a menu item.

Parameters:  inCommandID = command to execute. These ID's are not released to the pubic.
                        If you like to hack, then these are Metrowerks Constructor command ID's.

Returns:     none.

Version:    v0.2

NFListenToMessage(string inMessageIDStr [, int inDataIsPtrToLong, int inDataValue]);

Description: Post a message to the current window.

Parameters:  inMessageIDStr = message ID to send. Use Metrowerks Constructor.
             inDataIsPtrToLong = optional, specifies if the data is a long or a pounter to long.
             inDataValue = optional, the data to pass with the message.

Returns:     none.

Version:    v0.2

NFGetDescriptor(string inPaneID);

Description: Gets the text of an object in a window.

Parameters:  inPaneID = ID of the object to get text from. Use Metrowerks Constructor.

Returns:     a string containing the text displayed by the GUI element.

Notes: GUI objects include text captions, edit fields... basically anything that has text.

Version:    v0.2

NFSetDescriptor(string inPaneID, string inText);

Description: Sets the text of a GUI object in the current window.

Parameters:  inPaneID = GUI object ID. Use Metrowerks Constructor.
             inText = text to set the object to.

Returns:     none.

Notes: GUI objects include text captions, edit fields... basically anything that has text.

Version:    v0.2

NFGetValue(string inPaneID);

Description: Similar to PSGetDescriptor() except returns a number.

Parameters:  inPaneID = GUI object ID. Use Metrowerks Constructor.

Returns:     number representing the data being displayed.

Notes: GUI objects include:
    - text captions displaying numbers
    - Nth item selected in a popup menu, etc etc.

Version:    v0.2

NFSetValue(string inPaneID, int inNewValue);

Description: Similar to PSSetDescriptor() except set a number.

Parameters:  inPaneID = GUI object ID. Use Metrowerks Constructor.
             inNewValue = new value to get GUI object to.

Returns:     none.

Notes: GUI objects include:
    - text captions displaying numbers
    - Nth item selected in a popup menu, etc etc.

Version:    v0.2

NFSimulateHotSpotClick(string inPaneID, int inHotSpotMsg);

Description: Simulates a click in say a button.

Parameters:  inPaneID = GUI object ID. Use Metrowerks Constructor.
             inHotSpotMsg = hot spot message ID, for buttons its generally 10.

Returns:     none.

Notes: To "click" on a checkbox, you can simply set the value of a checkbox to 0 or 1.
       ie use PSSetValue().

Version:    v0.2

NFSwitchTarget(string inPaneID);

Description: Makes the GUI object the target of focus. eg an Edit Field

Parameters:  inPaneID = GUI object ID. Use Metrowerks Constructor.

Returns:     none.

Version:    v0.2

NFSelectFirstWindowWithID(string inWindowID);

Description: Makes the first window with inWindowID found to be selected (brought to front).

Parameters:  inWindowID = ID of window... obviously. Use Metrowerks Constructor.

Returns:     none.

Version:    v0.2

string = NFGestalt(string inGestaltID);

Description: Used to get OS information.

Parameters:  inGestaltID - ID from Gestalt.h (Universal Headers) as a string
                           eg "sysv"

Returns:     a hex number representing the result returned from the Gestalt OS call.
             eg auto result = NFGestalt("sysv");
             may set result to "0x00000910" = OS 9.1

Version:    v0.2

NetFinder Support Helpers


int = NFGetInternetStatus(int inReportType, string* outReport);

Description: Gets some TCP info.

Parameters:  inReportType - pass 1 to 7.
             outReport - report as string is returned.

Returns:     any errors, or zero for no error.

NOTE: This routine will not be supported under OSX.

int = NFNetworkPing(string inHostname);

Description: does a ping.

Parameters:  inHostname - the host to ping.

Returns:     any errors, or zero for no error.

NOTE: This routine will not be supported under OSX.

int = NFNetworkTraceRoute(string inHostname);

Description: does a traceroute.

Parameters:  inHostname - the host to ping.

Returns:     any errors, or zero for no error.

NOTE: This routine will not be supported under OSX.

NetFinder Utilities

int = NFExecuteAppleScript(string inScript [, string* outScriptReturnVal]);

Purpose:    Executes an AppleScript.
Parameters: inScript = AppleScript to execute.
            outScriptReturnVal = optional return value from AppleScript. 
                ie the AppleScript has "return result" at the end of the script.
Returns:    any errors that occured as a number, or ZERO for no error.

Version:    v0.3

Note:       This routine seems to only work 100% under MacOS 9 or higher. Prior OS's give varied results.


(c) 2000-2001 Peter Li, All Rights Reserved.