|
The Network News Transfer Protocol (NNTP) control enables
applications to access a news server, list the available newsgroups,
retrieve articles and post new articles. It is common for this control
to be used in conjunction with the Mail Message control to construct
the articles, since a news article uses the same general format as an
email message.
The following properties, methods and events are available for use
by your application:
Initialize
Initialize the control and validate the runtime license key for the
current process. This method is normally not used if the control is
placed on a form in languages such as Visual Basic. However, if the
control is being created dynamically using a function similar to
CreateObject, then the application must call this method to
initialize the component before setting any properties or calling any
other methods in the control.
Connect
Establish a connection to the NNTP server. Once the connection has
been established, the other methods in the control may be used to
access the newsgroups and/or post new articles to the server.
Authenticate
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.
Disconnect
Disconnect from the server and release any resources that have been
allocated for the client session. After this method is called, the
client session is no longer valid.
Uninitialize
Unload the Windows Sockets library and release any resources that
have been allocated for the current process. This is the last method
call that the application should make prior to terminating. This is
only necessary if the application has previously called the
Initialize method.
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
Active Template Library. The NNTP control provides the following
methods for accessing newsgroups on the server:
ListGroups
This method requests that the server return a list of all of the
newsgroups that are available. The application can also 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 method to
periodically update that list based on the date it was last modified.
If the method is successful, the application should call the
GetFirstGroup method to begin processing the group list.
OnNewsGroup
This event is generated for each newsgroup returned by the ListGroups
method. Information about the group is passed to the event handler as
arguments to the event, including the name of the group, the first
available article number and the last available article in the
group.
SelectGroup
This method is used to select a newsgroup as the current group. Once
selected, the application has access to the articles in that
newsgroup.
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 interface to parse
articles that you retrieve, as well as create new articles to post to
the server. The following methods are used to access and create news
articles:
ListArticles
This method 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.
OnNewsArticle
This event is generated for each article returned by the ListArticles
method. Information about the news article is passed to the event
handler as arguments to the event, including the article ID, size,
subject, author and date that the article was posted.
GetArticle
Retrieve an article from the server, storing the contents in a string
buffer or byte array. This can be used to process the contents of an
article without the overhead of storing it in a file on the local
system.
StoreArticle
Retrieve an article from the server and store it in a file on the
local system.
PostArticle
This method posts an article to one or more newsgroups on the server.
A newsgroup article is similar to an email message, and the MIME
interface 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 method 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 control 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 interface creates a multipart message even
when uuencoding is specified, the File Encoding control 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 control to create this kind of message. Note that not all
third-party newsreaders correctly handle multipart messages.
yEnc
An encoding method commonly used on USENET, it's similar to
uuencoded attachments where the file data is part of the body of the
message. The File Encoding control should be used to encode the data
and then it should be included in the main body of the message. More
information about yEnc encoding can be found at www.yenc.org
|