home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Amiga MA Magazine 1998 #3
/
amigamamagazinepolishissue1998.iso
/
bazy
/
kingfisher-distribution
/
developer
/
kf.h
< prev
next >
Wrap
C/C++ Source or Header
|
1996-06-05
|
31KB
|
631 lines
/***************************************************************************
**
** 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 <walrus@wam.umd.edu>
** or via standard (snail) mail to
** Udo Schuermann
** 7022 Hanover Parkway, Apt. C2
** Greenbelt, Maryland 20770-2049
** USA
**
***************************************************************************/
#include <exec/types.h>
#include <exec/ports.h>
/* 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 */
