1

Ac: Archie Client API

August 24, 1994.

Murali R. Krishnan (MuraliK)

Revised: Sept 20, 1994 ( MuraliK)

Contents
1. INTRODUCTION 2

2. ARCHIE DESCRIPTION 3

3. API FUNCTIONS 4

3.1. View of API Functions 4

3.2. Functions 4

3.2.1. AcQuery ( ) 4
3.2.2. AcFindNextFile ( ) 5
3.2.3. AcFindReset ( ) 6
3.2.5. AcClose ( ) 6

Appendix A.
ERROR CODES 8
Appendix B.
ADDITIONAL DOCUMENTATION 9
Appendix C.
Archie Client API Header File 10

Murali R. Krishnan 6/15/2019 6/15/2019

 2

1. INTRODUCTION

Archie system provides an Electronic Directory Service for the Internet resources. Archie is implemented using
client-server paradigm.
The Archie server automatically collects and indexes all filenames stored at anonymous FTP sites in the internet.
The server updates the information on a periodic basis. Archie Client accesses the server with a given query and requests
the location and attribute information about files available in the internet.
This Archie Client DLL provides API to ease Archie access and enable building applications using archie-based
access to internet resources. Using this DLL provides internet-wide access to files, indexed by archie servers.
The applications use the Archie Client DLL and invoke AcQuery() to make a query about locations of
filenames specified by search string and search criteria. The applications may optionally specify a set of hosts to perform
the search. This function call returns an “Archie Client Result Handle (HACR)” . The application can retrieve the
locations, filenames and attributes of all the matching results for given query, by using calls to AcFindNextFile(). The
handle is valid until closed with AcClose(). Optionally the iteration to get next file can be reset to start from the first file
by calling AcFindReset().
In the future, services provided by Archie Client DLL will be useful to search internet resources and retrieve the
files using FTP Client API. Currently the implementation provides APIs for extracting host, filename, size, modes and
access method for accessing the files resulting from an archie query. This will provide information to access the files.

Murali R. Krishnan 6/15/2019 6/15/2019

 3

2. ARCHIE DESCRIPTION

Archie system is based on client-server paradigm. The server is responsible for the bulk of functions. The
functions include collection, organization and indexing of the files available through anonymous FTP over internet and
maintaining the database. It replies client queries and sends responses with matches for searches using this database. The
current implementations of server and client are based on the Prospero File system for virtual directory access.
Archie client and server interact using Prospero protocol for querying virtual directory information. The server
maintains archie information under a special directory named archie in its virtual root. There is a special program filter
for archie that processes the queries on archie database. Responses for archie query are returned using Prospero protocol.
Prospero is a system implementing the virtual system model for resources stored in a distributed environment. Its
implementation uses a simple textual protocol, called Prospero protocol. This protocol is implemented on top of a
message based protocol. Prospero protocol uses a simple Asynchronous Reliable Datagram Protocol (ARDP) for
transferring messages using the UDP datagrams.
The following describes the processing of a typical archie query. Each query specifies the string to search for,
maximum number of hits to retrieve (to limit search), and search type (exact, substring, regular expression etc.). The
archie client translates the query into Prospero protocol messages and sends it to the server. The server processes the
received query as if it was a Prospero directory enquiry and returns the results in as a Prospero text message. The client
collects all returned response packets and parses them to generate results of search. The client may present the results in
one of the many display formats.
In our implementation we provide an API for remote search using Archie mechanisms. The AcQuery() function
takes an archie query and a set of archie server hosts. It performs a parallel search on the server hosts by sending the
query to all the servers. It parses and constructs the list of the files located, matching the search. The function then
constructs and returns a handle for the result. The parallel search helps to improve the performance over a one-at-a-time
search.

Murali R. Krishnan 6/15/2019 6/15/2019

 4

3. API FUNCTIONS

3.1. View of API Functions

AcQuery()

AcFindNextFile()

AcFindReset()

AcClose()

3.2. Functions

3.2.1. AcQuery

HANDLE AcQuery( IN LPCTSTR * plpszHosts,

IN LPCTSTR lpszSearchString,
IN DWORD dwMaxHits,
IN DWORD dwOffset,
IN DWORD dwPriority,
IN AC_SEARCH_TYPE searchType,
IN BOOL ( CALLBACK * pfnContinue) ( DWORD),
OUT LPDWORD lpdwNumFound );

Processes archie query on given set of hosts, searching for instances specified by search string and returns a
handle to the result.
Parameter Description

plpszHosts Pointer to an array of null terminated character strings. This list is to be terminated
with a string with two nulls in it. These strings contain the name of archie hosts to use
for conducting the search. If plpszHosts == NULL, all the default archie servers in
Archie Client DLL are used for search.

lpszSearchString Points to the search string. The search string may be a plain string or
may contain standard regular expression wildcard symbols ( wildcards like ‘*’, ‘.’
and optional parantheses). This is used in conjunction with search type for search.

Murali R. Krishnan 6/15/2019 6/15/2019

 5

dwMaxHits Specifies the maximum number of entries to retrieve per archie server among all
matched entries. The parameter is used with the offset (dwOffset) specified to index
into the list of matched entries. This limits the number of entries pulled for certain
worst cases like regular expression or substring search with a single character. If
unspecified (negative), a default of 100 is assumed.

dwOffset Offset in the list of entries on each server from where to start collecting matched
entries ( defaults to 0).

dwPriority Priority of search (specified to help server optimize performance). It can be one of the
three manifest constants ACP_LOW, ACP_MEDIUM and ACP_HIGH.

searchType Specifies type of search. The choices include:

AcstExact Matches all filenames that are exactly same as search string.
AcstRegexp Matches filenames using regular expression given in search string.
AcstExactOrRegexp Matches filenames exact or based on regular expression.
AcstSubstring Matches all filenames with given search string as a substring.
AcstExactOrSubstring Matches all filenames exact or substring based.
AcstCaseSubstring Matches all filenames like AcstSubstring but is case sensitive.
AcstExactOrCaseSubstring Matches all filenames exact or like AcstSubstring but
case sensitive.

pfnContinue Pointer to a callback function taking a DWORD as argument and returning BOOL.
This function is called periodically when archie query is processed. This function
receives as parameter the number of milliseconds elapsed since start of processing.
If this function returns TRUE, processing continues. If it returns FALSE, processing
is aborted. If there are any valid matches, they are returned, otherwise AcQuery()
returns INVALID_HANDLE_VALUE and sets error code as ARCE_ABORT.

lpdwNumFound Pointer to double word. This parameter on successful return contains the number of
matches found for given keyword.

Returns
On Success, this function returns a handle to the archie client result. Otherwise returns
INVALID_HANDLE_VALUE. Applications should use GetLastError() to retrieve the error code.

Comments
This function is a blocking call. It performs a vectored search across the supplied list of hosts or all the hosts for
given search string with given search criteria. It collects the responses from the hosts, parses them and constructs a list of
internal objects containing the location and attribute information for files. The application can use the returned handle to
access the file information. Threads of a single process do not share any data across calls to AcQuery. The count of
matches found is returned in lpdwNumFound.

3.2.2. AcFindNextFile

BOOL AcFindNextFile( IN HANDLE hacr,

OUT LPAC_FIND_DATA lpffdOutput );

The AcFindFirstFile function retrieves the next matched entry and returns a copy of the result in the structure
pointed by given parameter.
Parameter Description

Murali R. Krishnan 6/15/2019 6/15/2019

 6

hacr A valid handle for Archie Client Query results

lpffdOutput Points to AC_FIND_DATA structure that holds information about found file,
including attributes and host containing the file.

Returns
On success, this functions returns a value of TRUE; otherwise it returns FALSE. If it succeeds the file
information is present in the returned structure. On failure, additional information can be obtained from GetLastError()
function. If no files matched the archie query, the GetLastError() will return ERROR_NO_MORE_FILES.

Comments
The information about file location includes specifying the host name and access method in addition to the
normal file attributes and file name information. An explicit copy is made to avoid conflicts between different threads in
accessing the AC_FIND_DATA. The application is responsible for managing the space used by the structure.
If this API is called for the first time or called after a call to AcFindReset(), the first entry in the matched list is
returned. Thus the application can restart the scan from the first match found.

3.2.4. AcFindReset

DWORD AcFindReset( IN HANDLE hacr );

Marks the traversal of Archie Query Results as just begun.

Parameter Description

hacr A valid handle for Archie Client Query Results.

Returns
This function returns ARCE_NO_ERROR or ARCE_INVALID_HANDLE.

Comments
This function marks the traversal as just started. Next call to AcFindNextFile() will start fetching the matched
entries from the start of the matched list of Archie Query results. This allows an application to rescan the results of an
Archie Query.

3.2.5. AcClose

DWORD AcClose( IN HANDLE hacr );

Terminates the current traversal if any and cleans up resources allocated for this handle.
Parameter Description

Murali R. Krishnan 6/15/2019 6/15/2019

 7

hacr A valid handle to Archie Client Results.

Returns
This function returns ARCE_NO_ERROR or ARCE_INVALID_HANDLE.

Comments
This function cleans up all dynamically allocated data structures and marks this handle as invalid for future use.
If any traversal is in progress on the returned results, it is terminated.

Murali R. Krishnan 6/15/2019 6/15/2019

 8

Appendix A.

ERROR CODES

Error Description
ARCE_NO_ERROR Successful completion of previous operation.
ARCE_INVALID_ARGS Invalid arguments given. Unable to process query.
ARCE_INVALID_HANDL Invalid handle passed to Archie Client DLL.
E
ARCE_NONE_FOUND Search returned with no results. No match for given search string.
ARCE_NETWORK Low-level network error has occurred.
ARCE_ABORTED Server aborted this request. Reason unknown.
ARCE_TIMEOUT Search timed out. The archie client DLL aborted the search as it took long
time. (Default is 5 minutes)

Murali R. Krishnan 6/15/2019 6/15/2019

Appendix B.

ADDITIONAL DOCUMENTATION

Additional Documentation about Prospero Protocol and ARDP is available in “The Prospero Protocol” document by
Clifford Neuman and Steven Serger Augart. This is available through anonymous FTP from prospero.isi.edu as
/pub/prospero/doc/prospero-protocol.ps.Z.
Archie is described in “archie—An Electronic Directory Service for the Internet”, by Alan Emtage and Peter Deutsch.
This paper appears in Conference Proceedings of USENIX Winter 1992 Technical Conference.
Appendix C.

Archie Client API Header File

/*++

Copyright (c) 1994 Microsoft Corporation

Module Name :

acapi.h

Abstract:

This module defines the API prototypes for Archie Client Interface.

Author:

Murali R. Krishnan ( MuraliK ) 29-Aug-1994

Revision History:

--*/

# ifndef _ACAPI_H_
# define _ACAPI_H_

/**************************************************
* AC_SEARCH_TYPE
* Specifies the type of search to be performed
**************************************************/

typedef enumAC_SEARCH_TYPE_TAG {
AcstExact = '=',
AcstRegexp = 'r',
AcstSubstring = 's',
AcstCaseSubstring = 'c' /* substring with case sensitiveness */
} AC_SEARCH_TYPE;

/*************************************************
* ACP: Archie Client Query Priority value
* Following values are used to indicate the priority for processing
* given archie query. This helps the archie server to optimize
* performance.
**************************************************/

# define ACP_LOW (+32767)

# define ACP_MEDIUM (0)
# define ACP_HIGH (-32767)

/**************************************************
* AC_TRANSFER_TYPE
* Specifies the type of transfer for the file located
* using archie search.
**************************************************/
typedef enum AC_TRANSFER_TYPE_TAG {

AcTransferUnknown = 0x0,
AcTransferBinary = 0x1,
AcTransferAscii = 0x2

} AC_TRANSFER_TYPE;

/**************************************************
* AC_ACCESS_METHOD_TYPE
* Specifies the type of access method used for accessing
* a file located by archie search.
**************************************************/

typedef enum AC_ACCESS_METHOD_TYPE_TAG {

AcAmError = 0x0,
AcAmAftp = 0x1, /*Anonymous FTP */
AcAmFtp = 0x2,
AcAmNfs = 0x4, /* NFS File System */
AcAmKnfs = 0x8, /* Kerberized NFS */
AcAmPfs = 0x10, /* Andrew File System */

} AC_ACCESS_METHOD_TYPE;

/**************************************************
* Error Codes (returned by Archie Client DLL)
* The Prefix (ARCE) stands for ARchie Client Errors.
* All Archie Client DLL errorcodes are specified
* with respect to a common base ARCE_ERROR_BASE
* Modify ARCE_ERROR_BASE, if changes are required
**************************************************/

# ifndef ARCE_ERROR_BASE
# define ARCE_ERROR_BASE (0x12000)
# endif

# define ARCE_NO_ERROR ((ARCE_ERROR_BASE) + 0)

# define ARCE_INVALID_ARGS
# define ARCE_INVALID_HANDLE
# define ARCE_NONE_FOUND
# define ARCE_NETWORK
# define ARCE_ABORT
# define ARCE_TIMEOUT
((ARCE_ERROR_BASE) + 1)
((ARCE_ERROR_BASE) + 2)
((ARCE_ERROR_BASE) + 3)
((ARCE_ERROR_BASE) + 4)
((ARCE_ERROR_BASE) + 5)
((ARCE_ERROR_BASE) + 6)

// Definitions of various string lengths

# define MAX_HOST_TYPE_LEN (20) /* eg: INTERNET-D */
# define MAX_HOST_NAME_LEN (80) /* eg: lucy.ifi.unibase.ch */
# define MAX_HOST_ADDR_LEN (30) /* eg: 131.152.82.1 */
# define MAX_USERNAME_LEN (30)
# define MAX_PASSWD_LEN (30)
# define MAX_PATH_LEN (260) /*same as MAX_PATH */

/************************************************************
* AC_FIND_DATA
* Structure which stored the data found about a file that matches
* an archie query.
* It stores information about file name, attributes, location, size, and access
* method to be used for accessing the file.
* The path of the file instead of just the filename is stored.
************************************************************/

typedef struct _AC_FIND_DATA {

DWORD dwAttributes;
DWORD dwSize;

AC_TRANSFER_TYPE tfrType;
AC_ACCESS_METHOD_TYPE acmType;

TCHAR rgchHostType[MAX_HOST_TYPE_LEN]; /* Type of Host */

TCHAR rgchHostName[MAX_HOST_NAME_LEN]; /* Name of the Host */
TCHAR rgchHostAddr[MAX_HOST_ADDR_LEN]; /* Host Internet Address
in dotted format */
TCHAR rgchFileName[MAX_PATH_LEN]; /* Path and name of the file */

/* Following fields are valid only for non anonymous FTP access type */
TCHAR rgchUserName[MAX_USERNAME_LEN];
TCHAR rgchPasswd[MAX_PASSWD_LEN];
} AC_FIND_DATA;

typedef AC_FIND_DATA * LPAC_FIND_DATA;

/************************************************************
* Define interface functions to mask of UNICODE dependencies
************************************************************/
# ifdef UNICODE

# define AcQuery AcQueryW

# else /* UNICODE */

# define AcQuery AcQueryA

# endif /* UNICODE */

/************************************************************
* Prototypes of API Functions
************************************************************/

# ifdef __cplusplus
extern "C" {
# endif /* __cplusplus */

HANDLE AcQueryA
(
IN LPCSTR * plpszHosts,
IN LPCSTR lpszSearchString,
IN DWORD dwMaxHits,
IN DWORD dwOffset,
IN DWORD dwPriority,
IN AC_SEARCH_TYPE searchType,
IN BOOL ( CALLBACK * pfnContinue) ( DWORD),
OUT LPDWORD lpdwNumFound
);
HANDLE AcQueryW
(
IN LPCWSTR * plpszHosts,
IN LPCWSTR lpszSearchString,
IN LPDWORD dwMaxHits,
IN DWORD dwOffset,
IN DWORD dwPriority,
IN AC_SEARCH_TYPE searchType,
IN BOOL ( CALLBACK * pfnContinue) ( DWORD),
OUT LPDWORD lpdwNumFound
);

BOOL AcFindNextFile
(
IN HANDLE hacr,
OUT LPAC_FIND_DATA lpffdOutput
);

BOOL AcFindReset
(
IN HANDLE hacr
);

DWORD AcClose
(
IN HANDLE hacr
);

# ifdef __cplusplus
} /* extern "C" */
# endif /* _cplusplus */

# endif /* _ACAPI_H_ */