## Gopher 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).

See also InternetConnect

### 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

© 1996 Microsoft Corporation