/*************************************************************************** ** ** KingFisher Release 2 Public Definitions ** Copyright © 1992-1995 Udo Schuermann ** All rights reserved ** ** Global Definitions ** $VER: KingFisher_PublicDefs 2.13 (28.10.95) ** ** These definitions define the message port interface for KingFisher 2.0 ** Any and all applications that wish to interface directly to Kingfisher ** must take care to follow the proper protocols. ** ** The message port interface is designed for high speed, flexible, and ** reliable operation between a potentially unlimited number of clients ** with the KingFisher Primary Process. KingFisher must have been started ** before any client can "talk" with it. ** ** It is strongly suggested to use the API outlined in the kf-api.(h|c) ** files as much as possible. Your program need include only "kf-api.h" ** to also gain access to the "kf.h" definitions below. If you choose to ** ignore the API (as the demo CLIent.c does) then merely include "kf.h" ** ** Never, ever, change anything in this file! ** ** Suggestions should be addressed via electronic mail to ** Udo Schuermann ** or via standard (snail) mail to ** Udo Schuermann ** 7022 Hanover Parkway, Apt. C2 ** Greenbelt, Maryland 20770-2049 ** USA ** ***************************************************************************/ #include #include /* KingFisher's public message port name. All messages sent to this port * must be of the type (struct KFMsg) as defined below. * * NOTE: It is HIGHLY recommended that you use the interface in kf-api.c * whenever possible. Changes to the underlying protocols can and * will occur; by using the kf-api.c you will save yourself at * least SOME work. */ #define KFPortName "KingFisher-Port" #define KFAPIVER 0x0010 /* check that .VERSIONID >= than this value * after a kfcHELLO, otherwise you may not * use the KFServer safely!!! * This is an internal value only and has no * bearing on the actual release/version * number of any of the software. */ struct KFMsg { struct Message AmigaMsg; /* standard system stuff */ UWORD Error; /* Non-zero ==> error return (text in *Buffer) */ UWORD Command; /* One of the kfc* commands */ ULONG BParam; /* Binary parameter (may be an address) */ ULONG DParam; /* Disk number */ UWORD FParam; /* Fish flags */ UWORD FInfo; /* Fish Position Info (see kfcGETFISH) */ ULONG BufferSize; /* Originator's buffer size */ char *Buffer; /* Originator's buffer */ UWORD VERSIONID; /* Check after kfcHELLO that it's >= KFAPIVER */ void *RESERVED; /* IMPORTANT: set to NULL before first call */ char *RESERVED2; /* either NULL or a 256+ byte buffer (see kfeFILEOPEN) */ }; /***************************************************************** * .Command values */ #define kfcHELLO 0x0001 /* Login to server * PROVIDE: * .BParam = FindTask(0L); * .Buffer = A scratch buffer containing a nice login identifier * .BufferSize = size of the scratch buffer * .RESERVED = 0 ... that's important here! * Do not ever change this field after the * kfcLOGIN call, or the server will reject * your messages! * .RESERVED2 = a different buffer (256+ bytes) which the * kfeFILEOPEN error can use to provide you * with volume:path/filename that failed. * You may leave this value NULL if you don't * care to make use of this feature. * RETURNS: * .VERSIONID = a value you should test for (see above!) * .BParam = the minimum recommended size for the .Buffer * If your current (scratch) buffer is smaller * than this, you should allocate a larger one, * or else you may frequently receive kfeTRUNC * errors. Do not forget to update the * .BufferSize field accordingly! * We assume henceforth that you ALWAYS provide this buffer * area. */ #define kfcBYE 0x0002 /* Logout of server */ #define kfcQUIT 0x0003 /* RESERVED: Tell server to shutdown * Information on this command is not made public. * Do not use. */ #define kfcFLUSH 0x0004 /* Ask server to flush all file buffers, updated index files, etc * You should not need to use this command at all, because the * KFServer performs this command at certain times. It is * provided here for those times when you must be absolutely * sure... */ #define kfcEXIT 0x000f /* OBSOLETE: KFServer asks client(!) to shutdown */ /* Instead of a kfcEXIT message, the client will now */ /* receive a ^C (CTRL_C) signal to which is should */ /* respond. IGNORE kfcEXIT */ #define kfcSTATUS 0x0010 /* Client status * RETURNS: * .Buffer = filled with printable text, multiple lines. * Do not rely on a specific format for this * text, as its layout and wording may change. */ #define kfcMAXCLIENTS 0x0011 /* Indicates free/beta/registered version of KFServer * RETURNS: * .BParam = number of clients that the server supports. * These value are likely to be found: * = 2 Freely distributable * > 32767 Registered * else Beta test (non public!) */ #define kfcISTATUS 0x001f /* RESERVED * Information on this command is not made public. * Do not use. */ #define kfcLISTDBASES 0x0020 /* Obtain list of all databases * RETURNS: * .Buffer = multiple lines of information such as: * "human-readable-name\1filename.kfdb\n" * terminated with a \0 byte. Note \1 is * a ctrl-A (0x01 byte) */ #define kfcSELECTDBASE 0x0021 /* select a database * PROVIDE: * .BParam = (char *) to "filename.kfdb" * Note: the string may be terminated * with a \n instead of the typical \0 * to allow you to point directly into * the .Buffer field as returned by the * kfcLISTDBASES command (above) * RETURNS: * .BParam = Largest record in this database. * If your current .Buffer is not at * least this large, then allocate a * new one! * .FParam = 0 if the database is NOT writable * (You should not call ANY database * update functions!) * 1 if the database can be updated * NOTE: Some previous versions of the KFServer * were totally confused about these values. * and returned only a value in .BParam that * had nothing to do with the intended use. */ #define kfcGETDBASENAME 0x0022 /* obtain the name of the current database * RETURNS: * .Buffer = The \0 terminated name of the database * file (.kfdb) in use. You may save this * value and later pass it back to the * kfcSELECTDBASE command. */ #define kfcGETDBASESIZE 0x0023 /* obtain the number of records in database * RETURNS: * .BParam = number of records in the database. * If this value is 0 then the database * is empty. */ #define kfcGETQINDEX 0x0024 /* obtain a pointer to the current database's quick index * RETURNS: * .BParam = (char *) to the QuickIndex. * This index is a \0 terminated list of * field values, each on a line by itself: * "Aquarium\n * KingFisher\n * NewAqua\n * FishCat\n" * .DParam = (char *) to the QuickIndex Field. * This points to a \0 terminated string * of the field to which the QuickIndex * pertains: * "name" * NOTE: The memory does not belong to you. Do not make * ANY modifications to this index!!! * NOTE: The pointer obtained becomes invalid after ANY * command that adds records to the database and * must be obtained again with kfcGETQINDEX! */ #define kfcGETDBASEDESCRIPT 0x0025 /* obtain long, descriptive label of current database * RETURNS: * .Buffer = The \0 terminated name of the database * as given in the .kfdb file's * 'database-name' item. */ #define kfcSETPOS 0x0030 /* move to absolute position in database * PROVIDE: * .BParam = record number to select (1 or greater) * RETURNS: * .DParam = Disk * .FParam = Flags * .FInfo = Prev/Next flags for Disk/Version/Fish * (see the Fish Flags (kfi#?) below) * No record will be retrieved from disk, no data * about it will be returned. Operations such as * kfcNEXTFISH will proceed from the new position. */ #define kfcSETDISKPOS 0x0031 /* move to first fish on indicated disk (1+) * PROVIDE: * .BParam = disk number to select (1+) * RETURNS: * (nothing) * Not every database records that its records are * located on disks other than the default, disk 1. */ #define kfcNEXTFISH 0x0032 /* move forward to next fish * PROVIDE: * (nothing) * RETURNS: * (nothing) * If the function does not return an error, then * the internal database position is updated. */ #define kfcPREVFISH 0x0033 /* move backward to previous fish * PROVIDE: * (nothing) * RETURNS: * (nothing) * If the function does not return an error, then * the internal database position is updated. */ #define kfcGETPOS 0x0040 /* obtain current position in database * RETURNS: * .BParam = 0 if the database is empty * 1+ for a database record * No data is actually retrieved. */ #define kfcGETDISKPOS 0x0041 /* obtain current fish's disk location * RETURNS: * .BParam = 0 if the database is empty * 1+ for a database record * No data is actually retrieved. */ #define kfcGETFISH 0x0050 /* retrieve the information on the current fish * PROVIDE: * .BParam = 0 to retrieve the current database record. * 1+ to retrieve a specific database record. * RETURNS: * .Buffer = The record from the database. * .BParam = The actual record number (1+) * .DParam = The disk on which the record is stored. * .FParam = The flags associated with this record. * .FInfo = Prev/Next flags for Disk/Version/Fish * (see the Fish Flags (kfi#?) below) * The record is returned in the "raw" database format. * It is up to the client to reformat this data for the * user! */ #define kfcPARSEFILE 0x0070 /* begin or continue parsing a file that conforms to the * Product Info Specification. * PROVIDE: * .BParam = (char *) filename to begin parsing * This value is ignored on subsequent calls. * RETURNS: * .Error = kfeNOMORE => no more record remain in the * file; the file has been closed, and the * NEXT kfcPARSEFILE call is assumed to begin * a NEW file and must provide a valid filename * with the .BParam field again. * else: * .Buffer = The contents of a record from the file, * which you may (or may not) want to present * to the user for approval. You may then use * a kfcADDFISH call to append the record to * the database. * A future version will also update the following if the * record was preceded with an .INDEXINFO key: * .DParam = Disk on which the record is supposed to be * stored. * .FParam = Flags that the .INDEXINFO key claimed for * this record. If the record comes from a * foreign database, you may wish to mask out * all but the standard flags. * If the "error" return value is kfeOK, then you may * pass this record to the server with a kfcADDFISH command * and then call kfcPARSEFILE again. * If you wish to interrupt kfcPARSEFILE you must send * the server a kfcSTOPPARSE command or else certain other * operations will fail due to the server's inability to * re-use certain internal state values that the parsing * continues to keep locked. */ #define kfcSTOPPARSE 0x0071 /* stop parsing before parsing fails */ #define kfcADDFISH 0x0072 /* add parsed fish from buffer to end of current database * PROVIDE: * .Buffer = Text to be added * It is strongly (yes, *STRONGLY*) warned * against passing arbitrary text to the * server to add to the database. Such an * action is COMPLETELY unsupported and can * confuse many operations, including the * kfcREINDEX operation, causing loss of * data, even undefined and unpredictable * behavior! * Information returned by a kfcPARSEFILE * command is defined to be valid data. * The absolute minimum is two lines of * text, the first of which is * .name * and the second of which is at least one * character. Both lines should be ended * with a newline. In 'C' this string would * look like: * ".name\nProgramName\n" * .BParam = Disk on which the record is stored * No, BParam is not a typo; the .DParam * field was added somewhat late in the * game, after this command was already * defined without the benefit of the new * field. For backward compatibility, this * command continues to use .BParam. * .FParam = Flags to set for this record. * RETURNS: * .BParam = Record number of the new fish. * The first time you call kfcADDFISH, the KFServer will * reserve the current database for your exclusive use. * This requires that no other client is using that database * or else the kfcADDFISH command will fail. * Once the kfcADDFISH command has succeeded, you may * safely call the command any number of times. When you * are finished adding records, release the database again * with the kfcENDADDING command, so that other clients can * again access it, too. * If you fail to use kfcENDADDING, then similar restrictions * apply as mentioned above, under the kfcPARSEFILE command! * Notice that the use of kfcADDFISH invalidates any * previously obtained QuickIndex pointers (see kfcGETQINDEX) * No check is made that the disk numbers of successive * records are actually in sequential order. You may confuse * any and all DISK related functions (such as kfcSETDISKPOS) * if you do not add records with disk numbers in sequential * order. */ #define kfcENDADDING 0x0073 /* stop adding fish to the current database; release database */ #define kfcSCANTREE 0x0074 /* scans tree on disk and returns contents of .Product-Info files * »»»»» THIS COMMAND IS NOT IMPLEMENTED! ««««« * If this functionality is required, it is recommended that you * implement a tree-walking routine yourself, perhaps base on * the 'dirwalker' example provided with SAS/C. */ #define kfcSTOPSCAN 0x0075 /* stops a tree-scan that is in progress before SCANTREE fails. * Not implemented; see kfcSCANTREE above. */ #define kfcTRUNCATE 0x0076 /* truncate the database at (and including) the current fish * Removes all records from the database, beginning with the * current database record. At present, the records are not * physically removed, which can cause problems when subsequent * additions are made and the database is then reindexed. A * future version of the KFServer will physically remove the * records, rather than just updating the index. * RETURNS: * .BParam = Last record number in the database * (this is 0 if the database is empty) * You should use a kfcGETFISH command to read a new record * from the database. */ #define kfcREINDEX 0x0077 /* rebuilds the main database index and/or the field index * This command MUST BE CALLED multiple times, so long as it * returns kfeOK. When it returns kfeNOMORE, the operation * has been successfully completed. * PROVIDE: * .BParam = a mask of kfr#? flags. * These are currently ignored but may be used * in future versions of the software. You * must set all available flags at this time. * RETURNS: * .Buffer = Three numbers formatted into a string to * provide some form of progress feedback. * The first number is the Disk, the second, * the record (fish), and the third is the * total number of bytes that have been * processed. The numbers are incremented * by an internally defined value. What you * do with this information is entirely up to * you. Example: * "15 143 548765" * refers to disk 15, fish 143, and 548765 * bytes that have been processed. * The need to call this function repeatedly comes from the * fact that a reindex operation usually requires far longer * than a multitasking server can afford to ignore other * clients. Until KFServer becomes a multi-threaded * application, this requirement will not change. Please * note that a reindexing operation imposes a SEVERE * penalty on other clients, as the server may not process * more than one or two messages per second, thereby * slowing other clients to a crawl (although not freezing * them altogether, which is the reason for the repeated-call * implementation.) */ #define kfcLOCKDB 0x0078 /* Begins possibly long-term operation on the database, * such as modifying flags, version links, etc. * Do not use this with commands that already provide their * own database locking (such as kfcREINDEX, kfcADDFISH, * kfcPARSEFILE, etc.) * You must use a matching kfcUNLOCKDB to relinquish * access to the database when done. * RETURNS: * (none) */ #define kfcUNLOCKDB 0x0079 /* Unlocks the database after a successful kfcLOCKDB. * Never EVER use kfcUNLOCKDB in lieu of a kfcENDADDING or * kfcSTOPSCAN command! */ #define kfcGETFLAGS 0x0080 /* obtain the flags for the current fish * RETURNS: * .BParam = Record number of current fish * .FParam = Flags of the current fish */ #define kfcGETNEXTLINK 0x0081 /* obtain the link to the next version * RETURNS: * .BParam = Record number of following version * A value of 0 indicates no link */ #define kfcGETPREVLINK 0x0082 /* obtain the link to the previous version * RETURNS: * .BParam = Record number of preceding version * A value of 0 indicates no link */ #define kfcSETFLAG 0x0086 /* set a particular flag for current fish * PROVIDE: * .FParam = A mask of one or more flags that * should be set. * RETURNS: * .FParam = The current flags (new flags * merged with previous flags) */ #define kfcCLRFLAG 0x0087 /* clear a particular flag for current fish * PROVIDE: * .FParam = A mask of one or more flags that * should be cleared. * RETURNS: * .FParam = The current flags (previous * minus cleared flags) */ #define kfcSETFLAGS 0x0088 /* set new flags for the current fish * PROVIDE: * .FParam = A completely new set of flags * to replace all previous ones. */ #define kfcSETNEXTLINK 0x0089 /* set link to next version * PROVIDE: * .BParam = New link to following version (1+) * A value of 0 clears the link */ #define kfcSETPREVLINK 0x008a /* set link to previous version * PROVIDE: * .BParam = New link to preceding version (1+) * A value of 0 clears the link */ #define kfcFINDMASKFORWARD 0x008b /* locate the next fish matching the masks * PROVIDE: * .BParam = Number of first record to consider. * .DParam = Mask of flags to avoid (never match) * .FParam = Mask of flags to match * RETURNS: * .BParam = Record number that matched * Returns kfeNOMORE if nothing matched. */ #define kfcFINDMASKREVERSE 0x008c /* locate the prev fish matching the masks * PROVIDE: * .BParam = Number of first record to consider. * .DParam = Mask of flags to avoid (never match) * .FParam = Mask of flags to match * RETURNS: * .BParam = Record number that matched * Returns kfeNOMORE if nothing matched. */ #define kfcFINDNEXTUSEDLINK 0x008d /* locate the next fish that uses a Version Link * PROVIDE: * .BParam = Number of first record to consider. * RETURNS: * .BParam = Record number that matched. * Returns kfeNOMORE if nothing matched. */ /***************************************************************** * .Error return values */ #define kfeOK 0x00 /* All is fine. This is not an error. */ #define kfeREFUSED 0x01 /* Command refused. * Further information is in the .Buffer field. * The client may not be authorized to use the * command or the server is otherwise prevented * from complying with a request. */ #define kfeUNREG 0x02 /* The client has not registered! * The client seems not to be properly registered * with the server. This may happen when the * server is unexpectedly shutdown, then a new * one started before the client even noticed * that the old server went away. */ #define kfeNOMORE 0x03 /* An operation found no more data. * This can be a move, search, or parse operation, * and is one of the most commonly encountered * "errors" ... your software should not "freak * out" when it encounters this. */ #define kfeBADEXPR 0x04 /* An expression could not be evaluated. * UNUSED. FORGET ABOUT IT. NO NEED TO HANDLE THIS. */ #define kfeCONFUSED 0x05 /* KFServer is confused; it might be best to quit! */ #define kfeTRUNC 0x06 /* The .Buffer's size is too small. * An error returned when the KFServer attempts to * store more information in the .Buffer than the * .BufferSize field indicates it can hold. This * is a rare occurrence, and you may wish to ignore * it and use the partial contents of the buffer, * or re-allocate the buffer to the size indicated * by the .BParam field and try the call again. */ #define kfeMEMORY 0x07 /* The server ran out of memory. * The KFServer performs numerous dynamic allocations * of memory. If it fails to allocate a necessary * chunk of memory, it returns this error. */ #define kfeBOGUSMSG 0x08 /* The client RETURNED a bogus message to the server. * This can be encountered only when you are responding * to messages at your message port which you did not * send, but the message gets somehow mangled and the * KFServer doesn't recognize it as one of its own, * either. This should never occur if you're using the * kfc-api.c */ #define kfeFILEOPEN 0x09 /* The server could not open a file that was needed. * If the .RESERVED2 field was not NULL, the KFServer * will fill that field with the filename it failed * to open; if KFAPI_USE_INTUITION is defined _AND_ * KFAPIVolumePrompts has not been set to FALSE, the * API will provide prompting for the disk volume * automatically. */ #define kfeBADFISH 0x0a /* Selected fish doesn't exist */ #define kfeSEEKERROR 0x0b /* Possibly bad index in the database index */ #define kfeREADERROR 0x0c /* Some or all of the fish could not be read */ #define kfeWRITEERROR 0x0d /* Some or all of the fish could not be written */ #define kfeNODBASE 0x0e /* No database has been selected. */ #define kfeBADDBASE 0x0f /* Access to the database failed */ #define kfeNOSERVICE 0x10 /* Service request denied or unavailable */ /* The following are generated by the kf-api.c by any (even implicit) call to the * CallServer() routine; i.e. any call to functions in the kf-api.c file can generate * errors like these: */ #define kfeNOSERVER 0x81 /* Server did not start within required timeframe */ #define kfeSERVERGONE 0x82 /* The server vanished while a call was in progress */ /***************************************************************** * Fish Flags * The following are flags retrievable and settable with the kfcGETFLAGS and kfcSETFLAGS * commands. The values in the range 0x0100 through 0xff00 are reserved for pre-defined * flags. The bits defined below are made into a mask by ORing them together. * NOTE: The values 0x0800, 0x1000, 0x2000, and 0x4000 are not defined at the moment and * are reserved for future implementation. For your own uses, employ the kffUSERx * flags or define equivalent (more meaningful) values in your own code that match * the eight values available to you. * NOTE: Use of the kfcREINDEX command will lose all the information below. This behavior * *MAY* change in a future release. */ #define kffDELETED 0x8000 /* fish has been deleted */ #define kffUNDEF1 0x4000 /* belongs to system; undefined */ #define kffUNDEF2 0x2000 /* belongs to system; undefined */ #define kffUNDEF3 0x1000 /* belongs to system; undefined */ #define kffHASTWIN 0x0800 /* fish has twins/duplicates in the database */ #define kffHIDDEN 0x0400 /* fish has been marked hidden */ #define kffOWNED 0x0200 /* fish has already been obtained/downloaded */ #define kffMARKED 0x0100 /* fish has been marked for later retrieval */ #define kffUSER7 0x0080 #define kffUSER6 0x0040 #define kffUSER5 0x0020 #define kffUSER4 0x0010 #define kffUSER3 0x0008 #define kffUSER2 0x0004 #define kffUSER1 0x0002 #define kffUSER0 0x0001 /***************************************************************** * Fish Info * The following flags are returned by the kfcGETFISH command to * give a GUI information on existence of previous and next fish, * disks, and versions. The .FInfo field will contain this mask. */ #define kfiPREVDISK 0x0001 /* This is not the first disk */ #define kfiNEXTDISK 0x0002 /* This is not the last disk */ #define kfiPREVVERS 0x0004 /* A previous version is registered */ #define kfiNEXTVERS 0x0008 /* A succeeding version is registered */ #define kfiPREVFISH 0x0010 /* This is not the first fish */ #define kfiNEXTFISH 0x0020 /* This is not the last fish */ /***************************************************************** * Options for the kfcREINDEX command * These are ignored by the current incarnation of the KFServer; * The KFServer currently assumes that the actions indicated by * both flags are always desired, and always reindexes both. * This behavior may change in a future version if there is call * for it. */ #define kfrREBUILDMAIN 0x0001 /* Rebuild main index */ #define kfrREBUILDQUICK 0x0002 /* Rebuild quick (name) index */ /* EOT */