home *** CD-ROM | disk | FTP | other *** search
/ Amiga MA Magazine 1998 #3 / amigamamagazinepolishissue1998.iso / bazy / kingfisher-distribution / developer / kf-api.h < prev    next >
C/C++ Source or Header  |  1997-04-10  |  17KB  |  437 lines
  1. /*****************************************************************
  2.  * KingFisher Release 2
  3.  * Application Programming Interface
  4.  * Copyright © 1994,1995 Udo Schuermann
  5.  * All rights reserved
  6.  *****************************************************************
  7.  * $VER: KingFisher_API 2.26 (11.4.97)
  8.  *****************************************************************
  9.  * This software belongs to Udo Schuermann (author) and may not be
  10.  * redistributed or reproduced in any form without express written
  11.  * permission from the author:
  12.  *    Udo Schuermann
  13.  *    7022 Hanover Parkway, Apt. C2
  14.  *    Greenbelt, MD 20770-2049
  15.  *
  16.  *    walrus@wam.umd.edu
  17.  *****************************************************************
  18.  * By including this file and using the supplied functions, you
  19.  * ensure greater compatibility in future versions and reduce the
  20.  * chance of error through omitted parameters.  PLEASE USE THIS
  21.  * API FOR YOUR APPLICATIONS AS MUCH AS POSSIBLE, RATHER THAN THE
  22.  * THE MESSAGE PORT INTERFACE DIRECTLY!
  23.  *
  24.  * INSTRUCTIONS: In your project, include "kf-api.h" (which also
  25.  * includes "kf.h" for you) to define what is needed to interface
  26.  * with the KingFisher Release 2 Server.  Compile the file
  27.  * "kf-api.c" into an object file (kf-api.o) and link it with your
  28.  * other objects.
  29.  *****************************************************************
  30.  */
  31.  
  32. #ifndef KF_API_H
  33. #define KF_API_H
  34.  
  35. #include "kf.h"
  36.  
  37.  
  38. typedef struct KFMsg *KFHANDLE;   /* usage:  KFHANDLE myHandle  */
  39.  
  40. extern char KFAPIServerName[128];
  41. extern BOOL KFAPIServerDebug;
  42. extern BOOL KFAPISilentRun;
  43.  
  44. /* Some convenient and meaningful constructs, all beginning with KF_ */
  45. #define  KF_CURRENT_FISH   0L              /* Use for KFGetFish() */
  46. #define  KF_NIL_FISH       0L              /* "Not a valid fish" ID */
  47. #define  KF_DISK(Handle)   Handle->DParam  /* Disk Number */
  48. #define  KF_FISH(Handle)   Handle->BParam  /* Fish Number */
  49. #define  KF_FLAGS(Handle)  Handle->FParam  /* Flags */
  50. #define  KF_ERR(Handle)    Handle->Error   /* Error */
  51.  
  52.  
  53. /*****************************************************************
  54.  * The client may read and write the following variables.
  55.  * The API functions write to these appropriate times.
  56.  *****************************************************************
  57.  */
  58.  
  59. /* When 'ExitRequested' becomes TRUE, the server has requested
  60.  * us to quit as swiftly as possible so it can shutdown.  It is
  61.  * important to comply without much delay!
  62.  */
  63. extern BOOL ExitRequested;
  64.  
  65. /* The client may receive asynchronous messages from the server,
  66.  * that carry additional information about problems.  The last
  67.  * such error code (AsyncErr) and text (AsyncMsg) are kept here.
  68.  *    Your application should consult AsyncErr after unsuccessful
  69.  * calls to one of these functions to possibly obtain additional
  70.  * information and text on the problem that occurred.
  71.  */
  72. extern int   CallServerErr;
  73. extern int   AsyncErr;
  74. extern char  AsyncMsg[];
  75.  
  76.  
  77.  
  78. /*****************************************************************
  79.  * function prototypes for the KingFisher API
  80.  *****************************************************************
  81.  */
  82.  
  83. /*****************************************************************
  84.  * KFLogin()
  85.  * Required as the first call to the server.  Issue this command with a
  86.  * textual identifier, such as the name of your application.  A NULL
  87.  * pointer is permitted, but strongly discouraged!
  88.  *    The function returns a pointer to a KingFisher Server Message to
  89.  * be used in ALL FUTURE TRANSACTIONS with the server.
  90.  * NOTE: it is permitted for a single task to issue KFLogin() more than
  91.  * once to enable transactions between multiple databases or to allow a
  92.  * user to issue interactive commands while the main event loop keeps
  93.  * issuing "background" requests to the server (such as a search.)
  94.  *    You need to issue a KFLogout() command for every message returned
  95.  * by the KFLogin() command.  The function returns NULL if it is not
  96.  * possible to login to the server for one reason or another.
  97.  */
  98. struct KFMsg *KFLogin( char *Identifier );
  99.  
  100.  
  101. /*****************************************************************
  102.  * KFLogout()
  103.  * Required as the last call to the server.  Issue this command when
  104.  * you are finished with the server and wish to disconnect and exit.
  105.  */
  106. BOOL KFLogout( struct KFMsg *Msg );
  107.  
  108.  
  109. /*****************************************************************
  110.  * KFStatus()
  111.  * Retrieves status information from the server.  The text returned in
  112.  * the message .Buffer field is free-form and should not be relied upon
  113.  * to be in any particular format.  It is meant to be presented to the
  114.  * user.
  115.  */
  116. BOOL KFStatus( struct KFMsg *Msg );
  117.  
  118.  
  119. /*****************************************************************
  120.  * KFMaxClients()
  121.  * Returns the server's maximum client count.  The following
  122.  * ranges represent one of three types of the KFServer software:
  123.  *   0..1       Not available; never released; bogus
  124.  *   2          Freely Distributable KFServer
  125.  *   3..32767   Beta test versions, not for public use
  126.  *   32768+     Registered version
  127.  */
  128. ULONG KFMaxClients( struct KFMsg *Msg );
  129.  
  130.  
  131. /*****************************************************************
  132.  * KFCurFish()
  133.  * Retrieves the current position in the database, i.e. the current
  134.  * record.  The value returned may not fall in the proper range of
  135.  * available records if improper positions have been selected before.
  136.  */
  137. ULONG KFCurFish( struct KFMsg *Msg );
  138.  
  139.  
  140. /*****************************************************************
  141.  * KFCurFlags()
  142.  * Retrieves the flags of the current fish (record) in the database.
  143.  * If the current position in the database is not a valid record,
  144.  * then the information returned by this call will be undefined.
  145.  */
  146. UWORD KFCurFlags( struct KFMsg *Msg );
  147.  
  148.  
  149. /*****************************************************************
  150.  * KFCurDisk()
  151.  * Retrieves the disk position of the current fish (record).
  152.  * If the current position in the database is not a valid record,
  153.  * then the disk number returned by this call will be undefined.
  154.  */
  155. ULONG KFCurDisk( struct KFMsg *Msg );
  156.  
  157.  
  158. /*****************************************************************
  159.  * KFCurDatabaseDescription()
  160.  * Returns the long, descriptive name of the currently selected
  161.  * database.  This allows a program to present the user with a
  162.  * nice, understandable title for the current database in use.
  163.  */
  164. char *KFCurDatabaseDescription( struct KFMsg *Msg );
  165.  
  166.  
  167. /*****************************************************************
  168.  * KFCurDatabaseName()
  169.  * Returnes the name of the currently selected database.  This
  170.  * allows a program to make an alternate choice and "return" to
  171.  * the current database at will (see KFSelectDatabase() for more
  172.  * important information.)
  173.  */
  174. char *KFCurDatabaseName( struct KFMsg *Msg );
  175.  
  176.  
  177. /*****************************************************************
  178.  * KFCurDatabaseSize()
  179.  * Returns the number of records stored in the database.  If the
  180.  * function returns 0, then the database is empty (contains no
  181.  * records.)
  182.  */
  183. ULONG KFCurDatabaseSize( struct KFMsg *Msg );
  184.  
  185.  
  186. /*****************************************************************
  187.  * KFQuickIndex()
  188.  * Returns a pointer to the quick index.  In addition, the message
  189.  * field .DParam, when interpreted as a string, points to the name
  190.  * of the field that the index pertains to.
  191.  *
  192.  * The QuickIndex is a \0 terminated string:  "Name\nName2\n"
  193.  */
  194. char *KFQuickIndex( struct KFMsg *Msg );
  195.  
  196.  
  197.  
  198. /*****************************************************************
  199.  * KFSelectFish()
  200.  * Change the current position in the database.
  201.  */
  202. BOOL KFSelectFish( struct KFMsg *Msg, ULONG FishNumber );
  203.  
  204.  
  205. /*****************************************************************
  206.  * KFNextVersion()
  207.  * KFPrevVersion()
  208.  * Obtain record numbers of the next or previous version; if these
  209.  * numbers are == 0L then no such fish exists; otherwise a call
  210.  * can be made to load the selected fish.
  211.  * These calls are informational only, and do NOT cause the server
  212.  * to select a new fish; i.e. the currently defined record remains
  213.  * unchanged by these calls.
  214.  */
  215. ULONG KFNextVersion( struct KFMsg *Msg );
  216. ULONG KFPrevVersion( struct KFMsg *Msg );
  217.  
  218. /*****************************************************************
  219.  * KFSetNextVersion()
  220.  * KFSetPrevVersion()
  221.  * Update the next or previous version links for the current fish;
  222.  * a link value of 0L will clear the link.  The function returns
  223.  * -1L in case of a failure OR the previous value of that link.
  224.  */
  225. ULONG KFSetNextVersion( struct KFMsg *Msg, ULONG LinkValue );
  226. ULONG KFSetPrevVersion( struct KFMsg *Msg, ULONG LinkValue );
  227.  
  228. /*****************************************************************
  229.  * KFListDatabases()
  230.  * Retrieves a list of database names (those files with ".kfdb" at
  231.  * the end of their names) into the message .Buffer;  The names
  232.  * will be separated from each other by a newline \n and the list
  233.  * is terminated by a NUL (\0)
  234.  *    The format of the buffer will always be:
  235.  *       Descriptive text #1\01
  236.  *       filename1.kfdb\n
  237.  *       Descriptive text #2\01
  238.  *       filename2.kfdb\n
  239.  *       \0
  240.  * Note the continued use of \n as line terminator but the
  241.  * pre-pended descriptive text which is separated from the
  242.  * filename with a \1 (ASCII 01, ^A); the KFSelectDatabase()
  243.  * function expects to be given the string AFTER the \01
  244.  * character!
  245.  */
  246. BOOL KFListDatabases( struct KFMsg *Msg );
  247.  
  248.  
  249. /*****************************************************************
  250.  * KFSelectDatabase()
  251.  * Selects a new database by name.  The .kfdb extension is not
  252.  * strictly required, but the server will first try to open the
  253.  * database by the name exactly as given, and will THEN try it
  254.  * again (if failed) with the .kfdb extension added.
  255.  *    The name of the file may be terminated by either the
  256.  * standard ASCII NUL (\0) or a newline (\n) -- the latter is
  257.  * a convenience feature for use of this function in conjunction
  258.  * with KFListDatabases() from whose .Buffer it may be desireable
  259.  * to simply point at one of the names without regard if they are
  260.  * terminated with the \0 or \n.
  261.  *    The current position in the new database will be set to the
  262.  * first record.  If the function fails (returns FALSE) then the
  263.  * previously active database remains available undisturbed.
  264.  *    The R/W status of the database index is described by the
  265.  * Msg->BParam that is returned in case of a successful call.  If
  266.  * this value is 0 the index is not writable, otherwise it is.
  267.  */
  268. BOOL KFSelectDatabase( struct KFMsg *Msg, char *Filename );
  269.  
  270.  
  271. /*****************************************************************
  272.  * KFSetFlag()
  273.  * KFClrFlag()
  274.  * KFFindFlag()
  275.  * Sets or clears a particular flag for the current fish.  The
  276.  * flag's mask value is given in the second parameter.
  277.  * KFFindFlag() locates the next/previous fish matching the masks.
  278.  */
  279. BOOL KFSetFlag( struct KFMsg *Msg, UWORD Mask );
  280. BOOL KFClrFlag( struct KFMsg *Msg, UWORD Mask );
  281. BOOL KFFindFlag( struct KFMsg *Msg, BOOL Forward, UWORD MatchMask, UWORD AvoidMask );
  282.  
  283.  
  284. /*****************************************************************
  285.  * KFFindNextUsedLink()
  286.  * Returns the record number of the record that has either or both
  287.  * the previous/next VersionLinks set.  The operation begins with
  288.  * the indicated record (and may return that same record number!)
  289.  * The function returns the record number of the next matching
  290.  * record, this being a value 1+ if successful, 0 if not.
  291.  */
  292. ULONG KFFindNextUsedLink( struct KFMsg *Msg, ULONG FishNum );
  293.  
  294.  
  295. /*****************************************************************
  296.  * KFGetFish()
  297.  * Retrieve the current (or a specific) record from the current
  298.  * database.  If the 'FishNumber' parameter is set to 0 (as
  299.  * opposed to a valid record number 1 or greater) then the
  300.  * current record will be retrieved.  If a value greater than
  301.  * 0 is provided, then that specific record is retrieved.
  302.  * On successful return, .BParam has the fish number, .DParam
  303.  * has the disk number, and .FParam contains the returned fish's
  304.  * flags.
  305.  * NOTE: this function will fail if the indicated database is
  306.  * in use by any client application that has made calls to the
  307.  * KFAddFish() function without having released the database
  308.  * with a call to KFEndAdding().
  309.  */
  310. BOOL KFGetFish( struct KFMsg *Msg, ULONG FishNumber );
  311.  
  312.  
  313. /*****************************************************************
  314.  * KFGetDisk()
  315.  * Retrieve the first fish from the database that is stored on
  316.  * the indicated disk (according to the index.)  The function
  317.  * returns FALSE if such a disk cannot be located.  All disks
  318.  * must be numbered 1 or greater.  Values of 0 or less are not
  319.  * valid and will be rejected.
  320.  *    The current fish is retrieved in the same way as if that
  321.  * fish's exact record number had been given to KFGetFish();
  322.  * On successful return, all parameters are set as in the
  323.  * KFGetDisk() call.
  324.  * NOTE: this function will fail if the indicated database is
  325.  * in use by any client application that has made calls to the
  326.  * KFAddFish() function without having released the database
  327.  * with a call to KFEndAdding().
  328.  */
  329. BOOL KFGetDisk( struct KFMsg *Msg, ULONG DiskNumber );
  330.  
  331.  
  332. /* KFNextFish()
  333.  * Selects the fish following the current position.
  334.  */
  335. BOOL KFNextFish( struct KFMsg *Msg );
  336.  
  337.  
  338. /* KFPrevFish()
  339.  * Selects the fish preceeding the current position.
  340.  */
  341. BOOL KFPrevFish( struct KFMsg *Msg );
  342.  
  343.  
  344. /*****************************************************************
  345.  * KFAddFish()
  346.  * Adds the description in the .Buffer to the END of the current
  347.  * database and marks the Disk, Flags, and Prev- and Next-Version
  348.  * values into the index.
  349.  * NOTE: this function may fail for numerous reasons.  One thing
  350.  * to watch out for, especially, is that the function may fail if
  351.  * anyone else ALSO has access to the database.  If your client
  352.  * is the only one using a particular database, then the database
  353.  * is blocked until released with KFEndAdding().
  354.  */
  355. BOOL KFAddFish( struct KFMsg *Msg, UWORD Disk, UWORD Flags, LONG PrevVersion, LONG NextVersion );
  356.  
  357.  
  358. /*****************************************************************
  359.  * KFEndAdding()
  360.  * You *MUST* call this function after having added record(s) to
  361.  * the database.  You should not call this function after EACH
  362.  * addition, but only when everything you want to add has been
  363.  * added.
  364.  */
  365. BOOL KFEndAdding( struct KFMsg *Msg );
  366.  
  367.  
  368. /*****************************************************************
  369.  * KFTruncate()
  370.  * Truncates the database at the current position and moves back
  371.  * one fish; the return value is the new position in the database.
  372.  * A return value of -1 indicates an error, 0 means the database
  373.  * no longer contains any records, and 1+ is a valid position.
  374.  */
  375. LONG KFTruncate( struct KFMsg *Msg );
  376.  
  377.  
  378. /*****************************************************************
  379.  * KFParseFile()
  380.  * When this function is called the first time, it opens the
  381.  * indicated file, locates, and returns the first database
  382.  * record from it.
  383.  *    When called again, AFTER THE PREVIOUS CALL RETURNED
  384.  * TRUE, this function will continue to scan the indicated
  385.  * file, returning database records one at a time.  As long
  386.  * as the function returns TRUE, you may continue to call
  387.  * it, and the filename parameter serves no further purpose.
  388.  *    Once this function returns FALSE (on its first call or
  389.  * any subsequent call) the parsing is terminated and you
  390.  * should not use KFEndParsing() (see below)
  391.  *    If you wish to interrupt parsing a file BEFORE the
  392.  * function returns FALSE, the you MUST use KFEndParsing()
  393.  * to tell the server that you have no further interest in
  394.  * the file that it is prepared to continue parsing.
  395.  */
  396. BOOL KFParseFile( struct KFMsg *Msg, char *Filename );
  397.  
  398.  
  399. /*****************************************************************
  400.  * KFEndParsing()
  401.  * This function needs to be called whenever you have called
  402.  * upon the services of KFParseFile() but you wish to stop
  403.  * retrieving records from that file BEFORE the KFParseFile()
  404.  * function returns FALSE (i.e. no more records or another
  405.  * problem of sorts.)
  406. BOOL KFEndParsing( struct KFMsg *Msg );
  407.  
  408.  
  409. /*****************************************************************
  410.  * KFReindex()
  411.  * Rebuilds the index for the current database.  If more than
  412.  * one client has access to the current database, this call
  413.  * will fail.  After this function completes successfully,
  414.  * the current database record is reset to 1.
  415.  */
  416. BOOL KFReindex( struct KFMsg *Msg );
  417.  
  418.  
  419. /*****************************************************************
  420.  * KFLockDB()
  421.  * KFUnlockDB()
  422.  * Lock and unlock the database for operations that do not already
  423.  * provide their own locking.  This is an operation especially
  424.  * useful when modifying version links or performing other actions
  425.  * that should not occur while another client has access to the
  426.  * database.
  427.  *    The functions return TRUE if they succeed
  428.  */
  429. BOOL KFLockDB( struct KFMsg *Msg );
  430. BOOL KFUnlockDB( struct KFMsg *Msg );
  431.  
  432.  
  433. /* End of File */
  434. #endif   /* ifndef kf_api_h */
  435.  
  436.  
  437.