INT NntpGetArticle(
	HCLIENT hClient,
	LONG nArticleId,		// article to retrieve
	LPVOID lpvBuffer,		// pointer to buffer which will contain the article
	LPDWORD lpdwLength,
	DWORD dwReserved
);

The NntpGetArticle function retrieves the specified article and copies the contents to a local buffer.

Parameters

hClient

Handle to the client session.

nArticleId

Number of article to retrieve from the server. This value must be greater than zero.

lpvBuffer

A pointer to a byte buffer which will contain the data transferred from the remote 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.

dwReserved

A reserved parameter. This value should always be zero.

Return Value

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

Remarks

The NntpGetArticle function is used to retrieve an article 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 article. 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 article 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 complete article has been retrieved, a timeout occurs or the operation is canceled. During the transfer, the NNTP_EVENT_PROGRESS event will be periodically fired, enabling the application to update any user interface controls. Event notification must be enabled, either by calling NntpEnableEvents, or by registering a callback function using the NntpRegisterEvent function.

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

Example

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

// Return the article into block of global memory allocated by
// the GlobalAlloc function; the handle to this memory will be
// returned in the hgblBuffer parameter
nResult = NntpGetArticle(hClient,
                         nArticleId,
                         &hgblBuffer,
                         &cbBuffer,
                         0);

if (nResult != NNTP_ERROR)
{
    // Lock the global memory handle, returning a pointer to the
    // article text
    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 Vista, Windows XP or Windows 2000 Professional.
Server: Requires Windows Server 2008, Windows Server 2003 or Windows 2000 Server.
Header: Include cstools6.h.
Library: Use csnwsav6.lib.
Unicode: Implemented as Unicode and ANSI versions.

See Also

NntpCreateArticle, NntpEnableEvents, NntpGetArticleHeaders, NntpGetTransferStatus, NntpRegisterEvent

Copyright © 2008 Catalyst Development Corporation. All rights reserved.