ch18.htm

Using Visual C++ 6.0 一本关于Visual C++ 6.0基本编程应用的书籍。

	<TR ALIGN="LEFT" VALIGN="TOP">
		<TD ALIGN="LEFT">OnOutOfBandData</TD>
		<TD ALIGN="LEFT">Handles the Windows message generated when a socket has urgent, out-of-band data
			ready to read.</TD>
	</TR>
	<TR ALIGN="LEFT" VALIGN="TOP">
		<TD ALIGN="LEFT">OnReceive</TD>
		<TD ALIGN="LEFT">Handles the Windows message generated when a socket has data that can be read with
			Receive() (often overridden by derived classes).</TD>
	</TR>
	<TR ALIGN="LEFT" VALIGN="TOP">
		<TD ALIGN="LEFT">OnSend</TD>
		<TD ALIGN="LEFT">Handles the Windows message generated when a socket is ready to accept data that
			can be sent with Send() (often overridden by derived classes).</TD>
	</TR>
	<TR ALIGN="LEFT" VALIGN="TOP">
		<TD ALIGN="LEFT">Receive</TD>
		<TD ALIGN="LEFT">Reads data from the remote socket to which this socket is connected.</TD>
	</TR>
	<TR ALIGN="LEFT" VALIGN="TOP">
		<TD ALIGN="LEFT">ReceiveFrom</TD>
		<TD ALIGN="LEFT">Reads a datagram from a connectionless remote socket.</TD>
	</TR>
	<TR ALIGN="LEFT" VALIGN="TOP">
		<TD ALIGN="LEFT">Send</TD>
		<TD ALIGN="LEFT">Sends data to the remote socket to which this socket is connected.</TD>
	</TR>
	<TR ALIGN="LEFT" VALIGN="TOP">
		<TD ALIGN="LEFT">SendTo</TD>
		<TD ALIGN="LEFT">Sends a datagram without a connection.</TD>
	</TR>
	<TR ALIGN="LEFT" VALIGN="TOP">
		<TD ALIGN="LEFT">SetSockOpt</TD>
		<TD ALIGN="LEFT">Sets socket options.</TD>
	</TR>
	<TR ALIGN="LEFT" VALIGN="TOP">
		<TD ALIGN="LEFT">ShutDown</TD>
		<TD ALIGN="LEFT">Keeps the socket open but prevents any further Send() or</TD>
	</TR>
	<TR ALIGN="LEFT" VALIGN="TOP">
		<TD ALIGN="LEFT">Receive() calls.</TD>
		<TD ALIGN="LEFT"></TD>
	</TR>
</TABLE>
</P>
<P>If you use the CAsyncSocket class, you'll have to fill the socket address structures
yourself, and many developers would rather delegate a lot of this work. In that case,
CSocket is a better socket class.</P>
<P><B><I>CSocket</I>&#160;&#160;</B>CSocket inherits from CAsyncSocket and has all
the functions listed for CAsyncSocket. Table 18.2 describes the new methods added
and the virtual methods overridden in the derived CSocket class.</P>
<P>
<H4>Table 18.2&#160;&#160;CSocket Methods</H4>
<P>
<TABLE BORDER="1">
	<TR ALIGN="LEFT" VALIGN="TOP">
		<TD ALIGN="LEFT"><B>Method Name</B></TD>
		<TD ALIGN="LEFT"><B>Description</B></TD>
	</TR>
	<TR ALIGN="LEFT" VALIGN="TOP">
		<TD ALIGN="LEFT">Attach</TD>
		<TD ALIGN="LEFT">Attaches a socket handle to a CAsyncSocket instance so that it can form a connection
			to another machine</TD>
	</TR>
	<TR ALIGN="LEFT" VALIGN="TOP">
		<TD ALIGN="LEFT">Create</TD>
		<TD ALIGN="LEFT">Completes the initialization after the constructor constructs a blank socket</TD>
	</TR>
	<TR ALIGN="LEFT" VALIGN="TOP">
		<TD ALIGN="LEFT">FromHandle</TD>
		<TD ALIGN="LEFT">Returns a pointer to the CSocket attached to the handle it was passed</TD>
	</TR>
	<TR ALIGN="LEFT" VALIGN="TOP">
		<TD ALIGN="LEFT">IsBlocking</TD>
		<TD ALIGN="LEFT">Returns TRUE if the socket is blocking at the moment, waiting for something to happen</TD>
	</TR>
	<TR ALIGN="LEFT" VALIGN="TOP">
		<TD ALIGN="LEFT">CancelBlockingCal</TD>
		<TD ALIGN="LEFT">Cancels whatever request had left the socket blocking</TD>
	</TR>
	<TR ALIGN="LEFT" VALIGN="TOP">
		<TD ALIGN="LEFT">OnMessagePending</TD>
		<TD ALIGN="LEFT">Handles the Windows messages generated for other parts of your application while
			the socket is blocking (often overridden by derived classes)</TD>
	</TR>
</TABLE>
</P>
<P>In many cases, socket programming is no longer necessary because the WinInet classes,
ISAPI programming, and ActiveX controls for Web pages are bringing more and more
power to Internet programmers. If you would like to explore a sample socket program,
try Chatter and ChatSrvr, provided by Visual C++. Search either name in the online
help to find the files.</P>
<P>Each session of Chatter emulates a user server. The ChatSrvr program is the server,
acting as traffic manager among several clients. Each Chatter can send messages to
the ChatSrvr by typing in some text, and the ChatSrvr sends the message to everyone
logged on to the session. Several traffic channels are managed at once.</P>
<P>If you've worked with sockets before, this short overview may be all you need
to get started. If not, you may not need to learn them. If you plan to write a client/server
application that runs over the Internet and doesn't use the existing standard applications
like mail or the Web, then learning sockets is probably in your future. But, if you
want to use email, the Web, FTP, and other popular Internet information sources,
you don't have to do it by writing socket programs at all. You may be able to use
MAPI, the WinInet classes, or ISAPI to achieve the results you are looking for.</P>
<P>
<H2><A NAME="Heading3"></A>Using the Messaging API (MAPI)</H2>
<P>The most popular networking feature in most offices is electronic mail. You could
add code to your application to generate the right commands over a socket to transmit
a mail message, but it's simpler to build on the work of others.</P>
<P>
<H3><A NAME="Heading4"></A>What Is MAPI?</H3>
<P>MAPI is a way of pulling together applications that need to send and receive messages
(<I>messaging applications</I>) with applications that know how to send and receive
messages (<I>messaging services</I> and <I>service providers</I>), in order to decrease
the work load of all the developers involved. Figure 18.1 shows the scope of MAPI.
Note that the word <I>messaging</I> covers far more than just electronic mail: A
MAPI service can send a fax or voice-mail message instead of an electronic mail message.
If your application uses MAPI, the messaging services, such as email clients that
the user has installed, will carry out the work of sending the messages that your
application generates.</P>
<P>The extent to which an application uses messaging varies widely:</P>

<UL>
	<LI>Some applications can send a message, but sending messages isn't really what
	the application is about. For example, a word processor is fundamentally about entering
	and formatting text and then printing or saving that text. If the word processor
	can also send the text in a message, fine, but that's incidental. Applications like
	this are said to be <I>messaging-aware</I> and typically use just the tip of the
	MAPI functionality.
	<P>
	<LI>Some applications are useful without being able to send messages, but they are
	far more useful in an environment where messages can be sent. For example, a personal
	scheduler program can manage one person's To Do list whether messaging is enabled
	or not. If it is enabled, a number of work group and client-contact features--such
	as sending email to confirm an appointment--become available. Applications like this
	are said to be <I>messaging-enabled</I> and use some, but not all, of the MAPI features.
	<P>
	<LI>Finally, some applications are all about messaging. Without messaging, these
	applications are useless. They are said to be <I>messaging-based,</I> and they use
	all of MAPI's functionality.
</UL>

<P><A HREF="javascript:popUp('18uvc01.gif')"><B>FIG. 18.1</B></A><B> </B><I>The Messaging
API includes applications that need messaging and those that provide it.</I></P>
<H3><A NAME="Heading5"></A>Win95 Logo Requirements</H3>
<P>The number-one reason for a developer to make an application messaging aware is
to meet the requirements of the Windows 95 Logo program. To qualify for the logo,
an application must have a Send item on the File menu that uses MAPI to send the
document. (Exceptions are granted to applications without documents.)</P>
<P>To add this feature to your applications, it's best to think of it before you
create the empty shell with AppWizard. If you are planning ahead, here is a list
of all the work you have to do to meet this part of the logo requirement:</P>

<DL>
	<DT></DT>
	<DD><B>1. </B>In Step 4 of AppWizard, select the MAPI (Messaging API) check box.
	<P>
</DL>

<P>That's it! The menu item is added, and message maps and functions are generated
to catch the menu item and call functions that use your Serialize() function to send
the document through MAPI. Figure 18.2 shows an application called MAPIDemo that
is just an AppWizard empty shell.</P>
<P>No additional code was added to this application, beyond the code generated by
AppWizard, and the Send item is on the File menu, as you can see. If you choose this
menu item, your MAPI mail client is launched to send the message. Figures 18.2 and
18.3 were captured on a machine with Microsoft Exchange installed as an Internet
mail client (Inbox), and so it is Microsoft Exchange that is launched, as shown in
Figure 18.3. The message contains the current document, and it is up to you to fill
in the recipient, the subject, and any text you want to send with the document.</P>

<P><A HREF="javascript:popUp('18uvc02.gif')"><B>FIG. 18.2</B></A><B> </B><I>AppWizard
adds the Send item to the File menu, as well as the code that handles the item.</I></P>

<P><A HREF="javascript:popUp('18uvc03.gif')"><B>FIG. 18.3</B></A><B> </B><I>Microsoft
Mail is launched so that the user can fill in the rest of the email message around
the document that is being sent.</I></P>
<P>


<BLOCKQUOTE>
	<P>
<HR>
<strong>TIP:</strong> If the Send item doesn't appear on your menu, make sure that you have
	a MAPI client installed. Microsoft Exchange is an easy-to-get MAPI client. The OnUpdateFileSendMail()
	function removes the menu item Send from the menu if no MAPI client is registered
	on your computer. 
<HR>


</BLOCKQUOTE>

<P>If you didn't request MAPI support from AppWizard when you built your application,
here are the steps to manually add the Send item:</P>

<DL>
	<DT></DT>
	<DD><B>1. </B>Add the Send item to the File menu. Use a resource ID of <B>ID_FILE_SEND_MAIL</B>.
	The prompt will be supplied for you.
	<P>
	<DT></DT>
	<DD><B>2. </B>Add these two lines to the document's message map, outside the //AFX
	comments:
	<P>
</DL>

<PRE>ON_COMMAND(ID_FILE_SEND_MAIL, OnFileSendMail)
ON_UPDATE_COMMAND_UI(ID_FILE_SEND_MAIL, OnUpdateFileSendMail)
</PRE>
<P>Adding the mail support to your application manually isn't much harder than asking
AppWizard to do it.</P>
<P>
<H3><A NAME="Heading6"></A>Advanced Use of MAPI</H3>
<P>If you want more from MAPI than just meeting the logo requirements, things do
become harder. There are four kinds of MAPI client interfaces:</P>

<UL>
	<LI><I>Simple MAPI,</I> an older API not recommended for use in new applications
	<P>
	<LI><I>Common Messaging Calls (CMC),</I> a simple API for messaging-aware and messaging-enabled
	applications
	<P>
	<LI><I>Extended MAPI,</I> a full-featured API for messaging-based applications
	<P>
	<LI><I>Active Messaging,</I> an API with somewhat fewer features than Extended MAPI
	but ideal for use with Visual C++
</UL>

<P><B>Common Messaging Calls&#160;&#160;</B>There are only ten functions in the CMC
API. That makes it easy to learn, yet they pack enough punch to get the job done:</P>

<UL>
	<LI>cmc_logon() connects to a mail server and identifies the user.
	<P>
	<LI>cmc_logoff() disconnects from a mail server.
	<P>
	<LI>cmc_send() sends a message.
	<P>
	<LI>cmc_send_documents() sends one or more files.
	<P>
	<LI>cmc_list() lists the messages in the user's mailbox.
	<P>
	<LI>cmc_read() reads a message from the user's mailbox.
	<P>
	<LI>cmc_act_on() saves or deletes a message.
	<P>
	<LI>cmc_look_up() resolves names and addresses.
	<P>
	<LI>cmc_query_configuration() reports what mail server is being used.
	<P>
	<LI>cmc_free() frees any memory allocated by other functions.
</UL>

<P>The header file XCMC.H declares a number of structures used to hold the information
passed to these functions. For example, recipient information is kept in this structure:</P>
<P>
<PRE>/*RECIPIENT*/
typedef struct {
    CMC_string              name;
    CMC_enum                name_type;
    CMC_string              address;
    CMC_enum                role;
    CMC_flags               recip_flags;
    CMC_extension FAR       *recip_extensions;
} CMC_recipient;
</PRE>
<P>You could fill this structure with the name and address of the recipient of a
mail message by using a standard dialog box or by hard-coding the entries, like this:</P>
<P>
<PRE>CMC_recipient recipient = {
    &quot;Kate Gregory&quot;,