INT WINAPI GopherGetItem(
	HCLIENT hClient,
	UINT nItemType,
	LPCTSTR lpszSelector,
	LPVOID lpvBuffer,
	LPDWORD lpdwLength,
	DWORD dwOptions
);

The GopherGetItem function retrieves an item from the server and copies the contents to the specified buffer.

Parameters

hClient

Handle to the client session.

nItemType

An integer value which specifies the selector item type. Refer to the GopherSelectItem function for a list of valid item types. The item type may not specify a directory or index, otherwise an error will be returned.

lpszSelector

A pointer to the null-terminated selector string which identifies the resource to be returned by the server. The selector may be the name of a file on the server, or it may be an unique sequence of characters which is used to access the item.

lpvBuffer

A pointer to a byte buffer which will contain the data transferred from the server, or a pointer to a global memory handle which will reference the data when the function returns.

lpdwLength

A pointer to an unsigned long integer which should be initialized to the maximum number of bytes that can be copied to the buffer specified by the lpvBuffer parameter. If the lpvBuffer parameter points to a global memory handle, the length value should be initialized to zero. When the function returns, this value will be updated with the actual length of the file that was downloaded.

dwOptions

An unsigned integer that specifies one or more options. This parameter is constructed by using a bitwise operator with any of the following values:

Constant	Description
GOPHER_TRANSFER_DEFAULT	The default transfer mode. The item data is copied to the local system exactly as it is stored on the server.
GOPHER_TRANSFER_CONVERT	If the item being retrieved from the server is textual, the data is automatically converted so that the end of line character sequence is compatible with the Windows platform. Individual carriage return or linefeed characters are converted to carriage return/linefeed character sequences.

Return Value

If the function succeeds, the return value is the server result code. If the function fails, the return value is GOPHER_ERROR. To get extended error information, call GopherGetLastError.

Remarks

The GopherGetItem function is used to retrieve an item from the server and copy it into a local buffer. The function may be used in one of two ways, depending on the needs of the application. The first method is to pre-allocate a buffer large enough to store the contents of the file. In this case, the lpvBuffer parameter will point to the buffer that was allocated, the value that the lpdwLength parameter points to should be initialized to the size of that buffer.

The second method that can be used is have the lpvBuffer parameter point to a global memory handle which will contain the file data when the function returns. In this case, the value that the lpdwLength parameter points to must be initialized to zero. It is important to note that the memory handle returned by the function must be freed by the application, otherwise a memory leak will occur. See the example code below.

This function will cause the current thread to block until the file transfer completes, a timeout occurs or the transfer is canceled. During the transfer, the GOPHER_EVENT_PROGRESS event will be periodically fired, enabling the application to update any user interface controls. Event notification must be enabled, either by calling GopherEnableEvents, or by registering a callback function using the GopherRegisterEvent function.

To determine the current status of a transfer while it is in progress, use the GopherGetTransferStatus function.

Example

HGLOBAL hgblBuffer = (HGLOBAL)NULL;
LPBYTE lpBuffer = (LPBYTE)NULL;
DWORD cbBuffer = 0;

// Return the file data into block of global memory allocated by
// the GlobalAlloc function; the handle to this memory will be
// returned in the hgblBuffer parameter
nResult = GopherGetItem(hClient,
                        nItemType,
                        lpszSelector,
                        &hgblBuffer,
                        &cbBuffer,
                        GOPHER_TRANSFER_DEFAULT);

if (nResult != GOPHER_ERROR)
{
    // Lock the global memory handle, returning a pointer to the
    // resource data
    lpBuffer = (LPBYTE)GlobalLock(hgblBuffer);
    
    // After the data has been used, the handle must be unlocked
    // and freed, otherwise a memory leak will occur
    GlobalUnlock(hgblBuffer);
    GlobalFree(hgblBuffer);
}

Requirements

Client: Requires Windows 7, Windows Vista or Windows XP.
Server: Requires Windows Server 2008 or Windows Server 2003.
Header: Include cstools7.h.
Library: Use csgprav7.lib.
Unicode: Implemented as Unicode and ANSI versions.

See Also

GopherEnableEvents, GopherGetTransferStatus, GopherSelectItem, GopherStoreItem, GopherRegisterEvent

Copyright © 2012 Catalyst Development Corporation. All rights reserved.