Gopher Functions

Gopher Functions


The Gopher functions described in this section control the creation and use of the Internet Gopher utilities.
GopherAttributeEnumerator
GopherCreateLocator
GopherFindFirstFile
GopherGetAttribute
GopherGetLocatorType
GopherOpenFile

GopherAttributeEnumerator

BOOL GopherAttributeEnumerator(
    LPGOPHER_ATTRIBUTE_TYPE lpAttributeInformation,
    DWORD dwError
);

Defines a callback function that processes attribute information from a Gopher server. This callback function is installed by a call to the GopherGetAttribute function.

lpAttributeInformation
Address of a buffer that contains a single GOPHER_ATTRIBUTE_TYPE structure. The lpBuffer parameter to GopherGetAttribute is used for storing this structure. The lpBuffer size must be equal to or greater than the value of MIN_GOPHER_ATTRIBUTE_LENGTH.
dwError
Error value. This parameter is NO_ERROR if the attribute was parsed and written to the buffer successfully. If a problem was encountered, an error value is returned.

GopherCreateLocator

BOOL GopherCreateLocator(
    IN LPCSTR lpszHost,
    IN INTERNET_PORT nServerPort,
    IN LPCSTR lpszDisplayString,
    IN LPCSTR lpszSelectorString,
    IN DWORD dwGopherType,
    OUT LPCSTR lpszLocator,
    IN OUT LPDWORD lpdwBufferLength
);

Creates a Gopher or Gopher+ locator string from its component parts.

lpszHost
Address of a string that contains the name of the host, or a dotted-decimal IP address (such as 198.105.232.1).
nServerPort
Number of the port on which the Gopher server at lpszHost lives, in host byte order. If nServerPort is INTERNET_INVALID_PORT_NUMBER, the default Gopher port is read from the \etc\services file.
lpszDisplayString
Gopher document or directory to be displayed. If this parameter is NULL, the function returns the default directory for the Gopher server.
lpszSelectorString
Address of the selector string to send to the Gopher server in order to retrieve information. This parameter can be NULL.
dwGopherType
Value that specifies whether lpszSelectorString refers to a directory or document, and whether the request is Gopher+ or Gopher. The default value, GOPHER_TYPE_DIRECTORY, is used if the value of dwGopherType is zero. Can be one of the following values:
GOPHER_TYPE_ASK Ask+ item.
GOPHER_TYPE_BINARY Binary file.
GOPHER_TYPE_BITMAP Bitmap file.
GOPHER_TYPE_CALENDAR Calendar file.
GOPHER_TYPE_CSO CSO telephone book server.
GOPHER_TYPE_DIRECTORY Directory of additional Gopher items.
GOPHER_TYPE_DOS_ARCHIVE MS-DOS® archive file.
GOPHER_TYPE_ERROR Indicator of an error condition.
GOPHER_TYPE_GIF GIF graphics file.
GOPHER_TYPE_GOPHER_PLUS Gopher+ item.
GOPHER_TYPE_HTML HTML document.
GOPHER_TYPE_IMAGE Image file.
GOPHER_TYPE_INDEX_SERVER Index server.
GOPHER_TYPE_INLINE Inline file.
GOPHER_TYPE_MAC_BINHEX Macintosh file in BINHEX format.
GOPHER_TYPE_MOVIE Movie file.
GOPHER_TYPE_PDF PDF file.
GOPHER_TYPE_REDUNDANT Indicator of a duplicated server. The information contained within is a duplicate of the primary server. The primary server is defined as the last directory entry that did not have a GOPHER_TYPE_REDUNDANT type.
GOPHER_TYPE_SOUND Sound file.
GOPHER_TYPE_TELNET Telnet server.
GOPHER_TYPE_TEXT_FILE ASCII text file.
GOPHER_TYPE_TN3270 TN3270 server.
GOPHER_TYPE_UNIX_UUENCODED UUENCODED file.
GOPHER_TYPE_UNKNOWN Item type is unknown.
lpszLocator
Address of a buffer that receives the locator string. If lpszLocator is NULL, lpdwBufferLength receives the needed buffer length, but the function performs no other processing.
lpdwBufferLength
Length of the lpszLocator buffer. When the function returns, this parameter receives the number of bytes written to the lpszLocator buffer. If GetLastError returns ERROR_INSUFFICIENT_BUFFER, this parameter receives the number of bytes required to form the locator successfully.

To retrieve information from a Gopher server, an application must first get a Gopher "locator" from the Gopher server.

The locator, which the application should treat as an opaque token, is normally used for calls to the GopherFindFirstFile function to retrieve a specific piece of information.

GopherFindFirstFile

HINTERNET GopherFindFirstFile(
    IN HINTERNET hGopherSession,
    IN LPCSTR lpszLocator,
    IN LPCSTR lpszSearchString,
    OUT LPGOPHER_FIND_DATA lpFindData,
    IN DWORD dwFlags,
    IN DWORD dwContext
);

Uses a Gopher locator and some search criteria to create a session with the server and locate the requested documents, binary files, index servers, or directory trees.

hGopherSession
Handle to a Gopher session returned by InternetConnect.
lpszLocator
Name of the item to locate. Can be one of the following items:
  • Gopher locator returned by a previous call to this function or the InternetFindNextFile function.
  • NULL pointer or zero-length string indicating that the topmost information from a Gopher server is being returned.
  • Locator created by the GopherCreateLocator function.
lpszSearchString
Address of a buffer that contains the strings to search, if this request is to an index server. Otherwise, this parameter should be NULL.
lpFindData
Address of a GOPHER_FIND_DATA structure that receives the information retrieved by this function.
dwFlags
Action flag that can be a combination of the following values:
INTERNET_FLAG_DONT_CACHE
Does not add the returned entity to the cache. Identical to the preferred value, INTERNET_FLAG_NO_CACHE_WRITE.
INTERNET_FLAG_HYPERLINK
Forces a reload if there was no Expires time and no Last-Modified time returned from the server when determining whether to reload the item from the network.
INTERNET_FLAG_MAKE_PERSISTENT
No longer supported.
INTERNET_FLAG_MUST_CACHE_REQUEST
Causes a temporary file to be created if the file cannot be cached. Identical to the preferred value, INTERNET_FLAG_NEED_FILE.
INTERNET_FLAG_NEED_FILE
Causes a temporary file to be created if the file cannot be cached.
INTERNET_FLAG_NO_CACHE_WRITE
Does not add the returned entity to the cache.
INTERNET_FLAG_RELOAD
Forces a download of the requested file, object, or directory listing from the origin server, not from the cache.
INTERNET_FLAG_RESYNCHRONIZE
Reloads the FTP resource.
dwContext
Application-defined value that associates this search with any application data.

GopherFindFirstFile closely resembles the Win32 FindFirstFile function. It creates a connection with a Gopher server, and then returns a single structure containing information about the first Gopher object referenced by the locator string.

After calling GopherFindFirstFile to retrieve the first Gopher object in an enumeration, an application can use the InternetFindNextFile function to retrieve subsequent Gopher objects.

Use the InternetCloseHandle function to close the handle returned from GopherFindFirstFile. If there are any pending operations described by the handle when the application calls InternetCloseHandle, they are canceled or marked as closed pending. Any open sessions are terminated, and any data waiting for the caller is discarded. In addition, any allocated buffers are freed.

GopherGetAttribute

BOOL GopherGetAttribute(
    IN HINTERNET hGopherSession,
    IN LPCSTR lpszLocator,
    IN LPCSTR lpszAttributeName,
    OUT LPBYTE lpBuffer,
    IN DWORD dwBufferLength,
    OUT LPDWORD lpdwCharactersReturned,
    IN GOPHER_ATTRIBUTE_ENUMERATOR lpfnEnumerator,
    IN DWORD dwContext
);

Allows an application to retrieve specific attribute information from the server.

hGopherSession
Handle to a Gopher session returned by InternetConnect.
lpszLocator
Address of a string that identifies the item at the Gopher server on which to return attribute information.
lpszAttributeName
Address of a space-delimited string specifying the names of attributes to return. If lpszAttributeName is NULL, GopherGetAttribute returns information about all attributes.
lpBuffer
Address of an application-defined buffer from which attribute information is retrieved.
dwBufferLength
Size, in bytes, of the lpBuffer buffer.
lpdwCharactersReturned
Number of characters read into the lpBuffer buffer.
lpfnEnumerator
Address of a callback function that enumerates each attribute of the locator. This parameter is optional. If it is NULL, all the Gopher attribute information is placed into lpBuffer. If lpfnEnumerator is specified, the callback function is called once for each attribute of the object.
The callback function receives the address of a single GOPHER_ATTRIBUTE_TYPE structure with each call. The enumeration callback function allows the application to avoid having to parse the Gopher attribute information.
dwContext
Application-defined value that associates this operation with any application data.

Generally, applications call this function after calling GopherFindFirstFile or InternetFindNextFile.

The size of the lpBuffer parameter must be equal to or greater than the value of MIN_GOPHER_ATTRIBUTE_LENGTH (currently defined in Wininet.h as 256 bytes).

GopherGetLocatorType

BOOL GopherGetLocatorType(
    IN LPCSTR lpszLocator,
    OUT LPDWORD lpdwGopherType
);

Parses a Gopher locator and determines its attributes.

lpszLocator
Address of the Gopher locator string to parse.
lpdwGopherType
Address of a variable that receives the type of the locator. The type is a bitmask that consists of a combination of the following values:
GOPHER_TYPE_ASK Ask+ item.
GOPHER_TYPE_BINARY Binary file.
GOPHER_TYPE_BITMAP Bitmap file.
GOPHER_TYPE_CALENDAR Calendar file.
GOPHER_TYPE_CSO CSO telephone book server.
GOPHER_TYPE_DIRECTORY Directory of additional Gopher items.
GOPHER_TYPE_DOS_ARCHIVE MS-DOS archive file.
GOPHER_TYPE_ERROR Indicator of an error condition.
GOPHER_TYPE_GIF GIF graphics file.
GOPHER_TYPE_GOPHER_PLUS Gopher+ item.
GOPHER_TYPE_HTML HTML document.
GOPHER_TYPE_IMAGE Image file.
GOPHER_TYPE_INDEX_SERVER Index server.
GOPHER_TYPE_INLINE Inline file.
GOPHER_TYPE_MAC_BINHEX Macintosh file in BINHEX format.
GOPHER_TYPE_MOVIE Movie file.
GOPHER_TYPE_PDF PDF file.
GOPHER_TYPE_REDUNDANT Indicator of a duplicated server. The information contained within is a duplicate of the primary server. The primary server is defined as the last directory entry that did not have a GOPHER_TYPE_REDUNDANT type.
GOPHER_TYPE_SOUND Sound file.
GOPHER_TYPE_TELNET Telnet server.
GOPHER_TYPE_TEXT_FILE ASCII text file.
GOPHER_TYPE_TN3270 TN3270 server.
GOPHER_TYPE_UNIX_UUENCODED UUENCODED file.
GOPHER_TYPE_UNKNOWN Item type is unknown.

GopherGetLocatorType returns information about the item referenced by a Gopher locator. Note that it is possible for multiple attributes to be set on a file. For example, both GOPHER_TYPE_TEXT_FILE and GOPHER_TYPE_GOPHER_PLUS are set for a text file stored on a Gopher+ server.

GopherOpenFile

HINTERNET GopherOpenFile(
    IN HINTERNET hGopherSession,
    IN LPCSTR lpszLocator,
    IN LPCSTR lpszView,
    IN DWORD dwFlags,
    IN DWORD dwContext
);

Begins reading a Gopher data file from a Gopher server.

hGopherSession
Handle to a Gopher session returned by InternetConnect.
lpszLocator
Address of a string that identifies the file to open. Generally, this locator is returned from a call to GopherFindFirstFile or InternetFindNextFile. Because the Gopher protocol has no concept of a current directory, the locator is always fully qualified.
lpszView
Address of a string that describes the view to open if several views of the file exist at the server. If lpszView is NULL, the function uses the default file view.
dwFlags
Conditions under which subsequent transfers occur. Can be any combination of the following values:
INTERNET_FLAG_DONT_CACHE
Does not add the returned entity to the cache. Identical to the preferred value, INTERNET_FLAG_NO_CACHE_WRITE.
INTERNET_FLAG_HYPERLINK
Forces a reload if there was no Expires time and no Last-Modified time returned from the server when determining whether to reload the item from the network.
INTERNET_FLAG_MAKE_PERSISTENT
No longer supported.
INTERNET_FLAG_MUST_CACHE_REQUEST
Causes a temporary file to be created if the file cannot be cached. Identical to the preferred value, INTERNET_FLAG_NEED_FILE.
INTERNET_FLAG_NEED_FILE
Causes a temporary file to be created if the file cannot be cached.
INTERNET_FLAG_NO_CACHE_WRITE
Does not add the returned entity to the cache.
INTERNET_FLAG_RELOAD
Forces a download of the requested file, object, or directory listing from the origin server, not from the cache.
INTERNET_FLAG_RESYNCHRONIZE
Causes the Gopher resource to be reloaded from the server.
dwContext
Application-defined value that associates this operation with any application data.

GopherOpenFile opens a file at a Gopher server. Because a file cannot actually be opened or locked at a server, this function simply associates location information with a handle that an application can use for file-based operations such as InternetReadFile or GopherGetAttribute.

Use the InternetCloseHandle function to close the handle returned from GopherOpenFile. If there are any pending operations described by the handle when the application calls InternetCloseHandle, they are canceled or marked as closed pending. Any open sessions are terminated, and any data waiting for the caller is discarded. In addition, any allocated buffers are freed.

See also InternetOpenUrl

© 1997 Microsoft Corporation. All rights reserved. Terms of Use.