NntpClient provides a member function Connect() to connect to an NNTP server and other member functions to send NNTP commands to the server. Each of these member functions returns 0 if the client received a response from the server, and -1 if it did not. In other words, a 0 return value indicates that the client and server communication succeeded; a -1 return value usually indicates that a network error occurred. It is important to remember, however, that these member functions return 0 even in the case that the server failed to execute the command -- that is, the server sent a 4xx or 5xx response. You should also call the member function ReplyCode() to get the server's reply code, which indicates if the server successfully executed the NNTP command.
To use NntpClient, first call the Connect() member function to connect to the NNTP server. If the Connect() member function succeeds, then you may call other member functions to send NNTP commands to the server. After you send a command, you should check the function's return value. A zero return value indicates that the server received the client's command, and that the client received the server's response. A non-zero value indicates that the communication between client and server failed. Next, you should call the ReplyCode() member function to learn if the command succeeded at the server. Reply codes are listed in the NNTP specification. For some commands, such as for the GROUP command, the server returns information in a single-line response. You may call the ReplyText() member function to get the server's single-line response. For other commands, such as for the ARTICLE command, the server returns information in a mulitple-line response. For these commands, the library passes each line of the server's response to a listener object you implement. Your listener object must be a subclass of ProtocolListener. You must call the SetListener() member function to install your listener object. After you have sent all the NNTP commands you need, you should call the Disconnect() member function to disconnect from the server.
You should examine the return values of the member functions to detect communication errors. If a member function returns -1, which indicates that an error occurred, you may call other member functions to get the details of the error. You may call ErrorCode() to get a platform-independent error code. You may call OsErrorCode() to get the error code that was reported by the operating system. You may call ErrorMessage() to get a text error message that you can write to a log file.
One advanced feature of NntpClient is the ability to cancel a network operation. For example, if you are developing an interactive application with a user interface, you may allow the user to cancel a network operation that has stalled or that is taking too much time. To provide this capability, NntpClient provides a Cancel() member function that you may call from your user interface thread, which is a different thread from the thread that is controlling the NNTP connection.
Although NNTP (according to the latest Internet Draft) allows streaming (pipelining) of most commands, the interface provided by NntpClient is synchronous -- that is, each member function that sends an NNTP command does not return until it receives a response from the server. The class does provide a way to send commands in a streaming mode using the advanced functions. For a news reader client, there is probably little added benefit in using streaming.
Public Member Functions | |
| NntpClient () | |
| Default constructor. | |
| virtual | ~NntpClient () |
| Destructor. | |
| void | SetTraceOutput (TraceOutput *out, bool takeOwnership) |
| Sets a Trace Output instance. | |
| void | SetTimeout (int secs) |
| Sets the timeout value for network send and receive operations. | |
| void | SetReceiveTimeout (int secs) |
| Sets the timeout value for network receive operations. | |
| void | SetSendTimeout (int secs) |
| Sets the timeout value for network send operations. | |
| void | SetListener (ProtocolListener *listener, bool del) |
| Sets the listener object to process multiple line responses. | |
| void | Cancel () |
| Cancels a currently executing command. | |
| int | Connect (const char *address, int port=119, bool wait=true) |
| Opens a connection to an NNTP server. | |
| int | ConnectTls (const char *serverHostName, bool wait=false) |
| Opens a TLS connection over an existing TCP connection. | |
| int | ConnectTlsOpenSSL (const char *serverHostName, void *ssl, bool wait=false) |
| Establishes a TLS connection over an existing TCP connection. | |
| void | Disconnect () |
| Disconnects from the server. | |
| int | ModeReader () |
| Sends the MODE READER command. | |
| int | ListExtensions () |
| Sends the LIST EXTENSIONS command. | |
| int | Group (const char *name) |
| Sends the GROUP command. | |
| int | Last () |
| Sends the LAST command. | |
| int | Next () |
| Sends the NEXT command. | |
| int | Article (const char *messageId) |
| Sends the ARTICLE command. | |
| int | Article (uint32_t articleNum=0) |
| Sends the ARTICLE command. | |
| int | Head (const char *messageId) |
| Sends the HEAD command. | |
| int | Head (uint32_t articleNum=0) |
| Sends the HEAD command. | |
| int | Body (const char *messageId) |
| Sends the BODY command. | |
| int | Body (uint32_t articleNum=0) |
| Sends the BODY command. | |
| int | Stat (const char *messageId) |
| Sends the STAT command. | |
| int | Stat (uint32_t articleNum=0) |
| Sends the STAT command. | |
| int | Post () |
| Sends the POST command. | |
| int | List () |
| Sends the LIST command. | |
| int | ListActive (const char *wildmat=0) |
| Sends the LIST ACTIVE command. | |
| int | ListOverviewFmt () |
| Sends the LIST OVERVIEW.FMT command. | |
| int | Over (const char *range=0) |
| Sends the OVER command. | |
| int | Xover (const char *range=0) |
| Sends the XOVER command. | |
| int | NewGroups (const char *date, const char *time, bool gmt) |
| Sends the NEWGROUPS command. | |
| int | AuthinfoUser (const char *username) |
| Sends the AUTHINFO USER command. | |
| int | AuthinfoPass (const char *password) |
| Sends the AUTHINFO PASS command. | |
| int | Quit () |
| Sends the QUIT command. | |
| int | SendLines (const char *bytes, int length, int options) |
| Sends content as text lines. | |
| int | ReplyCode () const |
| Gets the server's reply code. | |
| const char * | ReplyText () const |
| Gets the text of the server's reply. | |
| Error | ErrorCode () const |
| Gets the platform-independent error code for the last error. | |
| int | OsErrorCode () const |
| Gets the platform-specific error code for the last error. | |
| const char * | ErrorMessage () const |
| Gets the error message for the last error. | |
| int | SendCommand (const char *commandStr) |
| Sends the specified command. | |
| int | ReceiveSingleLineResponse () |
| Receives a single line response. | |
| int | ReceiveMultipleLineResponse () |
| Receives a multiple line response. | |
|
|
Default constructor. |
|
|
Destructor. The destructor performs all necessary clean-up, including closing the connection to the server if it is not already closed. |
|
|
Sends the ARTICLE command. The ARTICLE command gets the full text of an article from the server as a multiple line response. This version of the overloaded member function takes an article number as its optional argument. If you omit the argument, the server sends the article referenced by the current article pointer. If the return value indicates success, you should check the server's reply code, by calling the ReplyCode() member function. A 2xx reply code indicates success.
|
|
|
Sends the ARTICLE command. The ARTICLE command gets the full text of an article from the server as a multiple line response. This version of the overloaded member function takes a message ID as an argument. If the return value indicates success, you should check the server's reply code, by calling the ReplyCode() member function. A 2xx reply code indicates success.
|
|
|
Sends the AUTHINFO PASS command. The AUTHINFO PASS command sends the password to a server that requires clients to log in. The AUTHINFO PASS command follows the AUTHINFO USER command, which sends the user name. The AUTHINFO PASS command is not defined in RFC 977; it is defined in RFC 2980 as an extension. If the return value indicates success, you should check the server's reply code, by calling the ReplyCode() member function. A 2xx reply code indicates success.
|
|
|
Sends the AUTHINFO USER command. The AUTHINFO USER command sends the username to a server that requires clients to log in. The AUTHINFO PASS command follows the AUTHINFO USER command to send the password. The AUTHINFO USER command is not defined in RFC 977; it is defined in RFC 2980 as an extension. If the return value indicates success, you should check the server's reply code, by calling the ReplyCode() member function. A 2xx reply code indicates success.
|
|
|
Sends the BODY command. The BODY command gets the body of an article from the server as a multiple line response. This version of the overloaded member function takes an article number as its optional argument. If you omit the argument, the server sends the body of the article referenced by the current article pointer. If the return value indicates success, you should check the server's reply code, by calling the ReplyCode() member function. A 2xx reply code indicates success.
|
|
|
Sends the BODY command. The BODY command gets the body of an article from the server as a multiple line response. This version of the overloaded member function takes a message ID as an argument. If the return value indicates success, you should check the server's reply code, by calling the ReplyCode() member function. A 2xx reply code indicates success.
|
|
|
Cancels the currently executing command. Since it is possible for a network connection to stop responding, an interactive application must be able to cancel a command that is waiting on a network operation (connect, send, or receive). For this reason, the NntpClient class provides a Cancel() member function, which promptly terminates any currently executing client command. Cancel() is the only member function that is safe to call from another thread. In a typical situation, you have one thread that executes NNTP commands, and another thread that serves the user interface. A user action to cancel is serviced by the user interface thread, which calls Cancel() on the NntpClient object to cancel a command. The command function that the NNTP client thread was executing at the time may return an error. (It will return an error if the cancel operation occurred before the command was completed.) Because it is difficult to recover the client/server state after a cancel operation, the library closes the connection whenever you call the Cancel() member function. You must call Connect() again to reconnect to the NNTP server. Note: You should not call the Connect() function from the same thread thread that called Cancel().
|
|
||||||||||||||||
|
Opens a connection to an NNTP server. This member function opens a connection to the host at network address address and TCP port port. The address parameter may be a hostname ("imap4.example.com"), an IP address in dotted decimal form ("192.168.2.25"), or an IPv6 address in hexadecimal form ("2002:458c:68f7:0:203:baff:fe0b:74ba"). The default value for port is 119, the well-known TCP port number for NNTP. If the client connects to the server successfully, then Connect() returns 0. If the client fails to connect to the server -- for example, if the host is not found or some other network error occurs -- then Connect() returns -1. If Connect() returns 0, then you should call the ReplyCode() member function to check the server's reply code. The server sends a 2xx reply code if it is ready to process commands. You may call the Cancel() member function from another thread to cancel this operation. If the optional parameter wait is true, it causes the client to wait for the server's greeting. In the NNTP protocol, the server always begins the dialog with its initial greeting. However, if you need to establish a TLS connection to the server, you may set wait to false. Then, the function returns immediately after the TCP connection is established without waiting for the server's initial greeting.
|
|
||||||||||||
|
Opens a TLS connection over an existing TCP connection. Transport Layer Security (TLS) provides server authentication and private communication over a TCP connection. TLS is the successor to Secure Sockets Layer (SSL), and individuals often use the term SSL even if the actual protocol is TLS. TLS is a standards track protocol developed by the IETF and described in RFC 2246. Before you call ConnectTls(), you must have established a TCP connection to the server. You must also have configured the TlsConfig object. Normally, you configure the TlsConfig object when you initialize your application. ConnectTls() starts a dialog between client and server, called a TLS handshake, to negotiate security parameters for the secure connection and to authenticate the server. If the handshake succeeds, a secure TLS connection is established between client and server. During the TLS handshake, the server sends a certificate to the client, and the client examines the certificate to verify the identity of the server. The certificate must be valid, and it must contain the host name of the server. When you call ConnectTls(), you provide the server's host name in the serverHostName parameter. The library tries to match serverHostName with the host name in the certificate. If the match fails, but the handshake otherwise succeeds, then the function returns -1, and the error code is BAD_CERTIFICATE_NAME_ERROR. In many applications, a BAD_CERTIFICATE_NAME_ERROR is not automatically treated as a fatal error; rather, the application presents an alert to the user and allows the user the choice to abort the connection or to continue and ignore the failure. Therefore, BAD_CERTIFICATE_NAME_ERROR should be treated as a severe warning: the server authentication failed but the secure connection succeeded. You should treat any other error that occurs during the handshake as a fatal error and close the TCP connection. The function returns 0 on success and -1 on failure. To check the error code after a failure, call ErrorCode().
|
|
||||||||||||||||
|
Opens a TLS connection over an existing TCP connection, using a specified SSL struct. For simple use of TLS, you may use the ConnectTls() member function. For advanced use, you may use this member function, which allows you to create an SSL struct and pass it to the library to use. Examples of situations where you may choose to use the ConnectTlsOpenSSL() function include:
To use ConnectTlsOpenSSL(), you must call the OpenSSL function SSL_new(SSL_CTX*) to create an SSL struct. After you configure the SSL struct, you pass it as the ssl parameter to ConnectTlsOpenSSL(). The NntpClient destructor calls SSL_free(SSL*) to free the SSL struct. However, OpenSSL uses a reference counting mechanism, and you may use that mechanism to prevent the NntpClient destructor from freeing the SSL struct. To prevent the NntpClient's destructor from freeing the SSL struct, increment the reference count before you pass the struct to the NntpClient, like so:
CRYPTO_add(&ssl->references, 1, CRYPTO_LOCK_SSL);
|
|
|
Closes the connection to the NNTP server. The correct way to end an NNTP session is to send a QUIT command, which causes the server to perform any necessary closing operations and close the connection. Therefore you should almost always call Quit() immediately before you call Disconnect(). You may safely call this method even if the client is not connected.
|
|
|
Gets the platform-independent error code for the last error. The error codes are enumerated in the file mailpp/Error.h. Note that they are defined in the mailpp namespace. The ErrorMessage() member function returns a textual description of the platform-independent error. If the error code is SYSTEM_ERROR, you may call OsErrorCode() to get more detailed information about the error.
|
|
|
Gets the error message for the last error. This function returns a textual description of the platform-independent error code.
|
|
|
Sends the GROUP command. The GROUP command selects a newsgroup. You must select a newsgroup before you can retrieve the articles from that newsgroup. The single, required argument is the name of the newsgroup. If the return value indicates success, you should check the server's reply code, by calling the ReplyCode() member function. A 2xx reply code indicates success.
|
|
|
Sends the HEAD command. The HEAD command gets the headers of an article from the server as a multiple line response. This version of the overloaded member function takes an article number as its optional argument. If you omit the argument, the server sends the headers of the article referenced by the current article pointer. If the return value indicates success, you should check the server's reply code, by calling the ReplyCode() member function. A 2xx reply code indicates success.
|
|
|
Sends the HEAD command. The HEAD command gets the headers of an article from the server as a multiple line response. This version of the overloaded member function takes a message ID as an argument. If the return value indicates success, you should check the server's reply code, by calling the ReplyCode() member function. A 2xx reply code indicates success.
|
|
|
Sends the LAST command. The LAST command sets the current article pointer to the previous article in the newsgroup. If the return value indicates success, you should check the server's reply code, by calling the ReplyCode() member function. A 2xx reply code indicates success.
|
|
|
Sends the LIST command. The LIST command gets a list of available newsgroups from the server as a multiple line response. If the return value indicates success, you should check the server's reply code, by calling the ReplyCode() member function. A 2xx reply code indicates success.
|
|
|
Sends the LIST ACTIVE command. The LIST ACTIVE command gets a list of available (that is, "active") newsgroups from the server as a multiple line response. The LIST ACTIVE command takes a wildmat pattern as an optional argument. If you omit the argument, the LIST ACTIVE command acts exactly as the LIST command. Wildmat patterns are similar to the "globs" that are used by many command shells and are described in RFC 2980. For example, you can use the wildmat pattern "alt.binaries.*" to retrieve the list of newsgroups in the alt.binaries hierarchy. The LIST ACTIVE command is not defined in RFC 977; it is defined in the latest Internet Draft and in RFC 2980. It may not be supported by very old server implementations. If the return value indicates success, you should check the server's reply code, by calling the ReplyCode() member function. A 2xx reply code indicates success.
|
|
|
Sends the LIST EXTENSIONS command. The LIST EXTENSIONS command gets a list of NNTP extensions that the server supports. The LIST EXTENSIONS command is not defined in RFC 977; it is defined in the latest Internet Draft. It may not be supported by all servers. If the command succeeds, the server sends a 2xx reply code and a multiple line response, with one extension keyword per line.
|
|
|
Sends the LIST OVERVIEW.FMT command. The LIST OVERVIEW.FMT command gets a list of the fields in the overview database as a multiple line reponse. The server's overview database maintains summary information about each article, such as the subject, author, date, number of lines, and so on. A client sends the OVER (or XOVER) command to get information from the overview database. The first eight, and most important, fields in the overview database are standard among all implementations. Therefore, the LIST OVERVIEW.FMT command is not very useful. The LIST OVERVIEW.FMT command is not defined in RFC 977; it is defined in the latest Internet Draft and in RFC 2980. It may not be supported by very old server implementations. If the return value indicates success, you should check the server's reply code, by calling the ReplyCode() member function. A 2xx reply code indicates success.
|
|
|
Sends the MODE READER command. The MODE READER command tells the server that the client is acting as a news reader, rather than a peer server. If your client is acting as a news reader client, it is a good idea to send this command first. The MODE READER command is not defined in RFC 977; it is defined in the latest Internet Draft and in RFC 2980. It may not be supported by very old server implementations.
|
|
||||||||||||||||
|
Sends the NEWGROUPS command. The NEWGROUPS command gets a list of newsgroups from the server that have been added since a specified date and time. The server sends a multiple line response, with one newsgroup specified per line. The format of the date parameter is [YY]YYMMDD (a four digit year is optional). The format of the time parameter is HHMMSS. If the gmt parameter is true, then the date and time are interpreted according to the GMT time zone (preferred); otherwise, the date and time are interpreted in the server's local time. If the return value indicates success, you should check the server's reply code, by calling the ReplyCode() member function. A 2xx reply code indicates success.
|
|
|
Sends the NEXT command. The NEXT command sets the current article pointer to the next article in the newsgroup. If the return value indicates success, you should check the server's reply code, by calling the ReplyCode() member function. A 2xx reply code indicates success.
|
|
|
Gets the platform-specific error code for the last error. This function gets the error code reported by the operating system. The operating system's error code is necessarily platform-specific. This error code is probably not as useful as the platform-independent error code, but it might provide information helpful for debugging. The operating system's error code provides more specific information when the platform-independent error code is SYSTEM_ERROR. Not all errors have an operating system error code. Some errors, such as library usage errors, are detected in the Hunny Mail++ library itself.
|
|
|
Sends the OVER command. The OVER command gets summary information about articles from the server's overview database as a multiple line response. The overview database maintains summary information about each article, such as the subject, author, date, number of lines, and so on. The server's multiple line response contains one line for each article, with fields separated by TAB characters. The first eight fields of the overview information are standard among server implementations. These fields are the following:
The server sends overview information for articles specified by the range argument. The range can be a single article number, a first and last article number separated by a dash (for example, "85903-86045"), or a first article number with no last article number (for example, "85903-"). The OVER command is not defined in RFC 977; it is defined in the latest Internet Draft. It may not be supported by very old server implementations. Older server implementations may support the XOVER command, which is exactly the same as OVER. XOVER is defined in RFC 2980. If the return value indicates success, you should check the server's reply code, by calling the ReplyCode() member function. A 2xx reply code indicates success.
|
|
|
Sends the POST command. The POST command is used by a news reader client to post an article to one or more newsgroups. After you call the Post() member function, you should check for a 3xx reply code from the server, which indicates that the server is ready to receive the article. If you get a 3xx reply, you then call the SendLines() member function one or more times to send the article content to the server.
|
|
|
Sends the QUIT command. The QUIT command causes the server to perform any closing operations and to close the connection. The return value indicates if the communication between client and server was successful. The server always responds with a 250 reply to the QUIT command.
|
|
|
Receives a mutliple line response from the server. This is an advanced member function that can be used to extend the library. You call ReceiveMultipleLineResponse() to get a multiple line response after you have called SendCommand()
|
|
|
Receives a single line response from the server. This is an advanced member function that can be used to extend the library. You call ReceiveSingleLineResponse() to get a single line response after you have called SendCommand()
|
|
|
Gets the reply code of the server's response to the most recent command. Reply codes in NNTP are three-digit numbers. The first digit (the most significant digit) indicates success or failure; the second and third digits provide more detailed information about the error. Error codes are listed in RFC 977.
|
|
|
Gets the reply text of the server's response to the most recent command. The ReplyText() member function removes the initial reply code and the final CR LF from the server's response. For example, if the server's response is "211 1234 40004 40034 alt.test\r\\n", the reply text is "1234 40004 40034 alt.test". If the server sends a multiple line response, this member function returns only the text of the first line (the status line).
|
|
|
Sends an NNTP command. This is an advanced member function that can be used to extend the library. SendCommand() sends the argument as a command to the server. It does not receive a response from the server. To receive a response, you can use ReceiveSingleLineResponse() or ReceiveMultipleLineResponse().
|
|
||||||||||||||||
|
Sends article content to the server as lines of text. The article content follows the POST command, if the POST command was successful. In NNTP, article content is sent as a series of lines, where each line ends with the CR LF characters. The bytes provided to the SendLines() member function as an argument should be in the required format -- that is, the buffers should contain lines of text. To send the article content, call the SendLines() member function as many times as needed to send all the bytes of the article content. When you make the first call of SendLines() to send the first buffer, you should set the NntpClient::FIRST bit in the options argument. When you send the last buffer, you set the NntpClient::LAST bit in the options argument. SendLines() will perform the conversion to CR LF end-of-line characters if you specify NntpClient::CONVERT_EOL as one of the options. With the NntpClient::CONVERT_EOL option set, conversions are performed as follows: LF --> CR LF, and CR LF --> CR LF. Therefore, with the NntpClient::CONVERT_EOL option, you can safely submit text with LF end-of-line characters or with CR LF end-of-line characters. The NntpClient::LAST option is an indication to the library code to receive a response from the server. You can check the reply code of the server's response by calling the ReplyCode() member function. A response code of 2xx indicates success.
|
|
||||||||||||
|
Sets the listener object for this NntpClient object. The listener object receives the lines of a multiple-line response as the client receives them. The server sends a multiple-line response for these commands: ARTICLE, BODY, HEAD, LIST, LIST ACTIVE, LIST EXTENSIONS, LIST OVERVIEW.FMT, NEWGROUPS, OVER, XOVER. The final line, which contains a dot ('.') by itself, is not passed to the listener object. You may use one ProtocolListener object to receive the lines from many responses. Typically, you create an NntpClient object, create a listener object, and call SetListener() only once to install the listener object. Then you use the same listener object for the lifetime of the NntpClient object.
If del is true, the NntpClient object's destructor calls
|
|
|
Sets the timeout for network receive operations. The library supports separate timeout values for sending and receiving. This property affects the timeout for receive operations. The send timeout property affects the timeout for connect and send operations. If a network operation times out, the member function that was executing returns -1, and ErrorCode() returns TIMED_OUT_ERROR.
|
|
|
Sets the timeout for network send operations. The library supports separate timeout values for sending and receiving. This propery affects the timeout for connect and send operations. The receive timeout property affects the timeout for receive operations. If a network operation times out, the member function that was executing returns -1, and ErrorCode() returns TIMED_OUT_ERROR.
|
|
|
Sets the timeout value for network send and receive operations. The timeout applies to these network operations: connect, receive, and send. If a network operation times out, the member function that was executing returns -1, and ErrorCode() returns TIMED_OUT_ERROR. This member function is deprecated. Use SetReceiveTimeout() and SetSendTimeout() to set network timeouts.
|
|
||||||||||||
|
Sets a TraceOutput instance. When you set a TraceOutput instance, you enable trace output, which may be helpful for debugging. You may set a null value to disable trace output. The Hunny Mail++ library provides a StdTraceOutput class that prints all output to standard output. If you pass a true value for the takeOwnership parameter, then the NntpClient object has the responsibility to delete the trace output object. On the other hand, if you pass false, then your code must delete the trace output object when it is no longer needed.
|
|
|
Sends the STAT command. The STAT command gets the "status" of an article from the server as a single line response. This version of the overloaded member function takes an article number as its optional argument. If you omit the argument, the server sends the status of the article referenced by the current article pointer. If the return value indicates success, you should check the server's reply code, by calling the ReplyCode() member function. A 2xx reply code indicates success.
|
|
|
Sends the STAT command. The STAT command gets the "status" of an article from the server as a single line response. This version of the overloaded member function takes a message ID as an argument. If the return value indicates success, you should check the server's reply code, by calling the ReplyCode() member function. A 2xx reply code indicates success.
|
|
|
Sends the XOVER command. The XOVER command is identical to the OVER command. XOVER is older than OVER, and is probably supported by more server implementations. See the documentation for Over().
|
Copyright © 2001-2005 Hunny Software, Inc. All rights reserved.