pher Functions

The Gopher functions control the creation and use of the Internet Gopher utilities.

GopherCreateLocator

BOOL GopherCreateLocator( IN LPCTSTR lpszHost,

IN INTERNET_PORT nServerPort,

IN LPCTSTR lpszDisplayString OPTIONAL, IN LPCTSTR lpszSelectorString OPTIONAL, IN DWORD dwGopherType,

OUT LPCTSTR lpszLocator OPTIONAL, IN OUT LPDWORD lpdwBufferLength

);

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

Returns TRUE if successful, or FALSE otherwise. To get extended error information, call GetLastError or InternetGetLastResponseInfo .

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. For more information, see the GOPHER_FIND_DATA structure.

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.

GopherGetLocatorType

BOOL GopherGetLocatorType( IN LPCTSTR 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:

Value Meaning

GOPHER_TYPE_TEXT_FILE An ASCII text file.

GOPHER_TYPE_DIRECTORY A directory of additional Gopher items.

GOPHER_TYPE_CSO A CSO telephone book server.

GOPHER_TYPE_ERROR Indicator of an error condition.

GOPHER_TYPE_MAC_BINHEX A Macintosh file in BINHEX format.

GOPHER_TYPE_DOS_ARCHIVE An MS-DOS® archive file. GOPHER_TYPE_UNIX_UUENCODED A UUENCODED file.

GOPHER_TYPE_INDEX_SERVER An index server.

GOPHER_TYPE_TELNET A Telnet Server.

GOPHER_TYPE_BINARY A binary 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_TN3270 A TN3270 server.

GOPHER_TYPE_GIF A GIF graphics file.

GOPHER_TYPE_IMAGE An image file.

GOPHER_TYPE_BITMAP A bitmap file.

GOPHER_TYPE_MOVIE A movie file.

GOPHER_TYPE_SOUND A sound file.

GOPHER_TYPE_HTML An HTML document.

GOPHER_TYPE_PDF A PDF file.

GOPHER_TYPE_CALENDAR A calendar file.

GOPHER_TYPE_INLINE An inline file.

GOPHER_TYPE_UNKNOWN The item type is unknown.

GOPHER_TYPE_ASK An Ask+ item.

GOPHER_TYPE_GOPHER_PLUS A Gopher+ item.

The GopherGetLocatorType function 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.

GopherFindFirstFile

HINTERNET GopherFindFirstFile( IN HINTERNET hGopherSession,

IN LPCTSTR lpszLocator OPTIONAL,

IN LPCTSTR lpszSearchString OPTIONAL,

OUT LPGOPHER_FIND_DATA lpFindData OPTIONAL,

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.

Returns a valid search handle if successful, or NULL otherwise. To get extended error information, call GetLastError or InternetGetLastResponseInfo .

hGopherSession

Handle to a Gopher session returned by InternetConnect .

lpszLocator

Name of the item to locate. Can be one of the following items:

A Gopher locator returned by lpGopherFindData, or a locator obtained by a previous call to this function or the InternetFindNextFile function.
A NULL pointer or zero-length string indicating that the topmost information from a Gopher server is being returned.
A 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. For a list of the valid flag values, see InternetOpenUrl .

dwContext

Application-defined value that associates this search with any application data.

The GopherFindFirstFile function 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.

See also InternetCloseHandle, InternetConnect, InternetFindNextFile

GopherGetAttribute

BOOL GopherGetAttribute(

IN HINTERNET hGopherSession, IN LPCTSTR lpszLocator,

IN LPCTSTR lpszAttributeName OPTIONAL, OUT LPBYTE lpBuffer,

IN DWORD dwBufferLength,

OUT LPDWORD lpdwCharactersReturned,

IN GOPHER_ATTRIBUTE_ENUMERATOR lpfnEnumerator OPTIONAL,

IN DWORD dwContext

);

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

Returns TRUE if the request is satisfied, or FALSE otherwise. To get extended error information, call GetLastError or InternetGetLastResponseInfo .

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 will return 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).

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.

Returns TRUE to continue the enumeration, or FALSE to immediately stop it. This function is primarily used for returning the results of a Gopher+ ASK item.

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.

GopherOpenFile

HINTERNET GopherOpenFile(

IN HINTERNET hGopherSession, IN LPCTSTR lpszLocator,

IN LPCTSTR lpszView OPTIONAL,

IN DWORD dwFlags, IN DWORD dwContext

);

Begins reading a Gopher data file from a Gopher server.

Returns a handle if successful, or NULL if the file cannot be opened. To get extended error information, call GetLastError or InternetGetLastResponseInfo .

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

Any combination of the INTERNET_FLAG_* flag values. For a list of valid flag values, see InternetOpenUrl .

dwContext

Application-defined value that associates this operation with any application data.

This function opens a file at a Gopher server. Because a file cannot be actually 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 GopherFindFirstFile, GopherGetAttribute, InternetCloseHandle, InternetConnect, InternetFindNextFile, InternetOpenUrl, InternetReadFile