|
The Gopher protocol is a document retrieval protocol that
pre-dates the Hypertext Transfer Protocol. The advantage that
Gopher offers is that it is a simpler, lightweight protocol that
doesn’t have the inherent overhead and complexity of a typical HTTP
server. It is most commonly used with internal corporate networks
to provide access to documents, although its use is less common
today than it was several years ago. Unlike some other protocols,
where you can connect once and then perform any number of
operations, the Gopher protocol requires that you establish a new
connection for each request that is made.
The first step that your application must take is to initialize
the library and then establish a connection. The following
functions are available for use by your application:
GopherInitialize
Initialize the library and load the Windows Sockets library for the
current process. This must be the first function call that the
application makes before calling the other Gopher API
functions.
GopherConnect
Connect to the remote host, using either a host name or IP address.
This function returns a client handle which is used in subsequent
calls to the library.
GopherDisconnect
Disconnect from the server and release the memory allocated for
that client session. After this function is called, the client
handle is no longer valid.
GopherUninitialize
Unload the Windows Sockets library and release any resources that
have been allocated for the current process. This is the last
function call that the application should make prior to
terminating.
Gopher Items
Documents and other resources on a Gopher server are referred to
as "items", where an item may be a text file, an executable program
or even something that isn't a file at all, such as a Telnet
session to a remote host. An item may also be a directory or index
of other items. Gopher servers store and return items in a
hierarchical fashion, similar to how folders can contain files and
other folders, which in turn may contain files and folders of their
own and so on.
Every item returned by a Gopher server is identified by a string
called its selector. By convention, the item selector is
typically a path to the resource on the server; however the only
requirement is that the selector be unique for each resource. On
some servers the selector may be a file path, and on other servers
it may be a number that specifies an index in a database table.
Gopher items are also identified by their assigned type, with codes
used to identify different types of resources such as text files,
HTML documents, image files, executable programs and so on.
GopherSelectItem
This function is used to retrieve an item from the server by
providing the item type and its selector string. If the item type
is a directory or index, then the server will return a list of
those items that it contains. If the item type is a file, then the
server will return the contents of the file to be read by the
client. The first thing an application should do after connecting
to the server is to call this function and specify an item type of
GOPHER_ITEM_DIRECTORY and a NULL or empty selector string. This
instructs the server to return the top-level directories and items
available to the client. Using this list, the client can then
select additional subdirectories to navigate through the item
hierarchy.
GopherGetFirstItem
If a directory or index has been selected, then this function will
provide information about the first item returned by the
server.
GopherGetNextItem
If a directory or index has been selected, then this function will
provide information about the next item returned by the server.
This function should be called in a loop until all of the listed
items have been returned.
GopherGetItem
This function transfers an item from the remote host to the local
system, storing the data in memory. This can be useful if your
application needs to perform some operation based on the contents
of the item, but does not need to store it locally. This function
can only be used with file-based resources on the Gopher server.
For example, you cannot use this function with a GOPHER_ITEM_TELNET
item because it represents a Telnet session, not a file.
GopherStoreItem
This function transfers an item from the remote host and stores it
in a file on the local system. As with the GopherGetItem function,
this function can only be used with file-based resources on the
Gopher server.
|