|
The Network News Transfer Protocol (NNTP) library enables
applications to access a news server, list the available
newsgroups, retrieve articles and post new articles. It is common
for this library to be used in conjunction with the Mail Message
library to construct the articles, since a news article uses the
same general format as an email message.
The first step that your application must take is to initialize
the library, then establish a connection to the server and
authenticate the client. The following functions are available for
use by your application:
NntpInitialize
Initialize the library and load the Windows Sockets library for the
current process. This must be the first function call that the
application makes before calling the other NNTP API functions.
NntpConnect
Establish a connection to the NNTP server. This function will
return a handle to a client session which is used in subsequent
calls to the NNTP API.
NntpAuthenticate
Provide a user name and password to authenticate the client
session. This should only be used if required by the server. Not
all news servers require authentication, and some only require
authentication when posting articles. If you attempt to perform a
function that requires authentication, an error will be returned
that indicates you should authenticate and then retry the
operation.
NntpDisconnect
Disconnect from the NNTP server and release any resources that have
been allocated for the client session. After this function is
called, the client handle is no longer valid.
NntpUninitialize
Unload the Windows Sockets library and release any resources that
have been allocated for the current process. This is the last
function call that the application should make prior to
terminating.
Newsgroups
News articles are posted in hierarchical groups, similar to how
files are stored in folders. Each level in the newsgroup hierarchy
is separated by a period, so newsgroup names look like
microsoft.public.vc. This is Microsoft's newsgroup for articles
about Visual C++ programming. Additional subgroups are used to
further narrow the topic; for example, there's the
microsoft.public.vc.3rdparty newsgroup for third party tools and
components for Visual C++, and the microsoft.public.vc.atl
newsgroup which discusses issues related to the ActiveX Template
Library. The NNTP API provides the following functions for
accessing newsgroups on the server:
NntpListGroups
This function requests that the server return a list of all of the
newsgroups that are available. If the function is successful, the
application should call the NntpGetFirstGroup function to begin
processing the group list.
NntpListNewGroups
This function is similar to the NntpListGroups function in
that it requests the server to return a list of available
newsgroups. However, the application can request that only groups
which were created since a specific date should be returned. This
allows the application to maintain a list of newsgroups on the
local system, and then use this function to periodically update
that list based on the date it was last modified.
NntpGetFirstGroup
This function is used in conjunction with the NntpListGroups
or NntpListNewGroups functions to enumerate the newsgroups
that are available on the server. Information about the newsgroup
is returned in a structure, including the name of the group, the
first available article number and the last available article in
the group.
NntpGetNextGroup
This function is used to return information about the next
newsgroup in the list. It should be called in a loop until it
returns zero (False).
NntpSelectGroup
This function is used to select a newsgroup as the current group.
Once selected, the application has access to the articles in that
newsgroup.
NntpGetGroupName
Return the name of the currently selected newsgroup.
NntpGetGroupTitle
Return a description of the currently selected newsgroup. Note that
not all newsgroups have associated descriptions, and some servers
may not support the extended command which is used to retrieve the
description.
News Articles
News articles are the messages posted to one or more newsgroups.
Articles are referenced by their article number, which is a value
assigned by the news server. These articles have a structure that
is the same as an email message, with some slightly different
headers. Because of this, you can use the Mail Message API to parse
articles that you retrieve, as well as create new articles to post
to the server. The following functions are used to access and
create news articles:
NntpListArticles
This function requests that the server return a list of articles
that are available in the current newsgroup. The application can
request that all articles be returned, or only those articles which
fall into a certain range of article numbers.
NntpGetFirstArticle
This is the first function that should be called after the
NntpListArticles function. It will return information about
the first article in the list. Article information is returned in a
structure which includes information such as the article ID, size,
subject, author and date that the article was posted.
NntpGetNextArticle
This function returns the information about the next article in the
list. It should be called in a loop until the function returns zero
(False).
NntpGetArticleRange
Return the range of articles that are available in the currently
selected newsgroup. These are the first and last valid article
numbers that can be used to retrieve an article from the server. It
is important to keep in mind that there is no requirement that
articles be stored contiguously with no gaps in between them. For
example, say the first available article number in the newsgroup is
101 and the last available article number is 120; it does not
necessarily mean that there are 20 available articles. Articles 112
and 118 may have been removed, in which case your application would
get an error when trying to access them. The inability to access an
article within the article range should not be considered a fatal
error; the program should simply move on to the next message.
NntpGetArticle
Retrieve an article from the server, storing the contents in
memory. This can be used to process the contents of an article
without the overhead of storing it in a file on the local
system.
NntpStoreArticle
Retrieve an article from the server and store it in a file on the
local system.
NntpPostArticle
This function posts an article to one or more newsgroups on the
server. A newsgroup article is similar to an email message, and the
MIME API may be used to create the article headers and body. One
important difference is that the message must contain a header
named "Newsgroups" with the value set to the newsgroup or
newsgroups that the article should be posted to; multiple
newsgroups should be separated by commas. If this header is not
defined, the posting will be rejected by the server and the
function will return an error. You should also be aware that some
servers limit the number of newsgroups that a message can be posted
to. When an article is posted to more than one newsgroup at a time,
this is called cross-posting. Current convention says that an
article should not be cross-posted to more than five newsgroups at
a time. Also keep in mind that multi-posting (posting the same
article to different newsgroups separately) is generally
discouraged and should never be done on USENET.
Attaching Files
It is possible to attach files to newsgroup articles; however it
should only be done if it is considered appropriate for the group.
Many newsgroups have their own acceptable use policies which
determine whether or not file attachments, particularly large
binary files, are acceptable. If the newsgroup accepts attachments,
you can use one of several methods for posting files. It is
recommended that you use the File
Encoding API to handle the actual encoding of the data.
Uuencode
A uuencoded file attachment is included directly in the body of the
message. Because the MIME API creates a multipart message even when
uuencoding is specified, the File Encoding API should be used to
encode the data and then it should be included in the main body of
the message.
Base64
A Base64 file attachment has the same structure as what is used by
email messages. This requires that a multipart message be created,
with the encoded data attached as a part of the message. You can
use the MIME API to create this kind of message. Note that not all
third-party newsreaders correctly handle multipart messages.
yEnc
A popular encoding method used on USENET is called yEnc. Similar to
uuencoded attachments, the file data is part of the body of the
message. The File Encoding API should be used to encode the data
and then it should be included in the main body of the message.
|