Microsoft Chat Control 1.1 Visual Basic Overview


		Contents Index Topic Contents
	Previous Topic: Microsoft Chat Control 1.1 Next Topic: Microsoft Chat Control 1.1 Visual Basic Reference

Microsoft Chat Control 1.1 Visual Basic Overview

The Microsoft® Chat control, an ActiveX™-based control, exports most of the ChatSock API features. The control has an optional user interface (UI) that is very flexible. This UI can include a Send button, Whisper button, Participant list box, History text box, and Send text box. This overview covers the use of the Chat control with Visual Basic® Scripting Edition and with a Visual Basic application.
Introduction

The Chat Control

Dependencies

Licensing and Distribution

Using the Chat Control

Introduction

The Microsoft Chat control allows the user to participate in a chat, or conversation, that can communicate both text and data, including arrays, Booleans, errors, currencies, and dates, between two or more users connected to a chat server. Stand-alone Microsoft Visual Basic applications containing the Chat control or HTML pages that utilize the Chat control are referred to as chat clients. These chat clients communicate with a chat server through either the MIC (Microsoft Internet Chat) or IRC (Internet Relay Chat) protocols. Developers can design and implement their own user interface for a Chat control client, or use the customizable default user interface provided with the Chat control.
The Chat Control

The Chat control is an ActiveX™ control that can be hosted by a Microsoft Visual Basic application program to create a chat client. Web authors can also insert the Chat control into an HTML file with the <OBJECT> tag, and use Microsoft Visual Basic Scripting Edition (VBScript) to manipulate the control's properties, methods, and events. Both implementations enable conversations between multiple users on client computers accessing a common chat server over the Internet.
HTML-based chat pages require the user to view the page with a browser that supports the HTML <SCRIPT> tag and the VBScript scripting engine that is implemented in the Vbscript.dll file. Browser applications, such as Microsoft Internet Explorer, that use the scripting engine are called scripting hosts.
The architecture that supports conversations on the Web using the Chat control and Chat server is shown below.

This diagram shows three users browsing the Web. Two users (on Web Clients 1 and 2) have already found the Chat control on a Web page and have entered a chat room to have a conversation. The user on Web Client 3 has just encountered the Web page with the Chat control. The numbers on the diagram represent the direction of the data flow. Each step in the process is described by the following actions:
First-time user on Web Client 3 makes a request to join the conversation, using the Chat control's user interface that is displayed on a Web page.
The Web browser downloads the Chat control software to Web Client 3.
The user on Web Client 3 types the message "Hello." The Chat control sends the message to the chat room.
The chat room sends the message "Hello" to all participants in the chat. They see "Hello" on their Chat History text boxes.
Some server and channel information is transmitted from the Web page to the chat room.

User Interface Elements

The Chat control allows a variety of user interface options. You can configure the control's user interface with the UIOption property. The user interface includes a History text box for displaying previously sent messages. You can directly access the text that is displayed in the History text box with the History property. The text appearing in the History text box can be limited to the maximum number of characters specified in the MaxHistoryLength property. The ClearHistory method should be invoked to clear the History text box when the OnHistoryFull event is triggered, indicating the History text box is 90 percent full.
Another user-interface feature is a Participant list box that allows users to see the alias names of all chat room members. Information about a chat room member, such as alias name, identifier, and Windows® user name, can be obtained by using the ThisParticipantAlias, ThisParticipantID, and ThisParticipantName properties, respectively. Using the information obtained from these properties will also allow you to invite a member of another chat room into a different chat room by using the InviteParticipant method, which triggers the OnParticipantInvited event. You can also obtain a chat room member's real name with the GetParticipantRealName method. If the attempt to get the member's real name was successful, this method triggers the OnParticipantRealName event.
A Send text box is included in the user interface so that the user can type outgoing messages. A Send button for broadcasting messages to all chat room members, and a Whisper button for sending private messages to a specific chat room member, are located at the bottom of the Chat control.
The following picture shows the default user interface provided with the Microsoft Chat control.

In addition to the default user interface, you can create a custom user interface using the control's automation interface with the supported properties, methods, and events.
Chat Rooms

Users running chat client applications can enter or create chat rooms to communicate with other users. A chat room is entered or created using the EnterRoom method with the desired options. Using these options, you can modify existing chat rooms or create a number of different types of new ones. For example, auditorium rooms can be created to prevent chat room members from communicating with any other chat room member who is not a host. If the room type is changed, users can be notified through the OnRoomTypeChanged event. It is also possible to allow the user to cancel the request to enter a chat room with the CancelEntering method. This may be especially helpful if network problems arise, or if the response from the chat server is slower than the user can tolerate. In any chat client application or Web page, you should include a button that invokes the ExitRoom method to allow a chat room member to leave the chat room at any time. When creating a custom user interface, you should utilize the OnEnterParticipant and OnExitParticipant events to notify all chat room members when someone has joined or left the room. As a precaution, the user's State property should always be checked before entering, canceling, or exiting a chat room to make sure the desired method will be valid. The example included at the end of this chapter illustrates this concept.
There are several properties associated with chat rooms that you can use to control users' access to a room, or to let them decide which room they want to enter. The current number of members in a chat room can be checked with the MemberCount property, and the maximum number of members allowed in a chat room can be restricted with the MaxMembers property. Chat rooms are usually labeled with the topic being discussed by setting the RoomTopic property. The OnRoomTopicChanged event is triggered when the RoomTopic property has changed, and should be used to notify all chat room members of the new topic. In certain cases, it may also be desirable to use the Rating property to label chat rooms that contain potentially offensive subject matter. The ratings associated with a chat room must be based on the World Wide Web Consortium (W3C) standard for content ratings, known as PICS (http://www.w3.org/PICS/), or Platform for Internet Content Selection.
Chat Members

Hosts, participants, and spectators are the three different types of members in a chat room. When a user creates a chat room, that member becomes the host of that room by default. After the OnEndEnumeration event is triggered, indicating that the list of a chat room's members has been retrieved, those members with a host status can perform certain administrative tasks. For example, a host can prevent specific users from entering the chat room with the BanParticipant method or eject members currently in a chat room with the KickParticipant method. When kicking a chat member out of the chat room, the OnParticipantKicked event can be used as an opportunity to notify or warn other chat room members (with a SendMessage) about acceptable behaviors within the current chat room. You can implement the SetParticipantStatus method to allow hosts to change the status of another chat room member. The associated OnParticipantStatusChanged event is triggered when the chat room member's status changes, and can be used as a mechanism to notify other chat room members. This can be especially useful in moderated rooms where a host wants to select a new host before leaving the chat room.
Chat room members with a participant status can send and receive messages from other chat room members, including hosts. Chat room spectators can see broadcast messages, but they are not allowed to send any type of message to other members of the chat.
Messages

When a chat room host or participant sends a message, it is broadcast to all other members in the room. A chat room member can also whisper a message to a specific member of the chat with the SendMessage method. Hosts can disable whisper messages for a specific chat member or the entire chat room with the SetParticipantStatus and EnterRoom methods, respectively. Chat room members can use the SetParticipantStatus method to ignore messages from specific members other than a chat room host.
General Chat Control Rules

The following rules apply to the use of the Chat control:
A chat room member will not receive the OnMessage event if the message was sent by that user. However, if the internal user interface is used, the OnTextMessageSent event will be triggered.
If a critical error occurs while in a chat room, the chat room member will automatically be ejected from the chat room. For example, if the network a chat room member was using to access the chat server suddenly became unavailable during a chat session, that user would be dropped from the list of participants. For more information on errors, look at the section on error codes.
The BorderStyle and Appearance properties should be set only at startup time. They should not be changed in the middle of a conversation, because the content of the controls (text boxes and list boxes) would be lost.
Chat room members cannot ignore themselves or a chat room host.
Only a host can change a member into a spectator, participant, or host.
The host cannot change an ignored member into a host (the ignore status must be removed first).
Participants and spectators cannot change the no-whisper status of another chat room member.
Chat room members cannot change themselves into spectators, participants, or hosts.

Dependencies

The Chat control requires the presence of the Mschat.ocx and Chatsock.dll files on the user's computer. These files can be obtained by installing the Internet Client SDK. To implement Web pages that use the Chat control, the Web server must have access to a chat server. If the Chat control is implemented as a stand-alone client application, the computer running this application must have access to a chat server. The Chat control enables the connection from the user's computer to a chat channel, or chat room, on the chat server.
Licensing and Distribution

The Microsoft Chat control is an ActiveX control that can be hosted by any ActiveX control container. This control is available for installation and redistribution on all computers with validly licensed copies of Microsoft operating system products (for example, Windows NT®, Windows® 95, and so on). For further information on licensing issues, refer to the License.txt file distributed with the Internet Client SDK.
Using the Chat Control

Web pages can be created to automatically download the Chat control with the <OBJECT> tag and allow the browser client to join a chat room using the default user interface with scripting. The following image shows how a sample HTML page looks when it is loaded by the browser.

To use the chat control shown above, the user viewing this HTML page would simply type an alias name in the Nickname field and click the Join The Chat button. Once connected, the frame on the right side of the control would show all chat room members. To broadcast a message, the user clicks in the Send text box, types the text of the message, and clicks the Send button. To whisper to specific members of the chat room, a user can select the names of the members in the Participant list box, click in the Send text box, type the message, and click the Whisper button. Whenever a message is sent in the chat room, the History text box is updated with the message and the chat member who sent it.
To implement this control, create an HTML page similar to the following example that uses VBScript. Detailed explanations of the HTML tags and VBScript code are provided below.
<HTML>
<HEAD>
<TITLE>MSChat OCX Simple Demo Page</TITLE>
</HEAD>
<BODY TOPMARGIN=4 BGCOLOR=#003B00 LINK=#FFFFDD VLINK=33FFFF TEXT=#FFFFFF>
<PRE>
        - Microsoft Chat Control Demo Page -
</PRE>
<P>
<OBJECT
    STANDBY="Dowloading the Microsoft MSChat ActiveX Control"
    CODETYPE="application/x-oleobject"
    CLASSID="clsid:D6526FE0-E651-11CF-99CB-00C04FD64497"
    CODEBASE="MSChatOCX.Cab#Version=4,71,413,0"
    WIDTH=600
    HEIGHT=350
    ID=Chat
    >
    <PARAM NAME="UIOption"   VALUE="2047">
    <PARAM NAME="Appearance" VALUE="3">
    <PARAM NAME="BackColor"  VALUE="255">
</OBJECT>
<FORM NAME = "WEBChat">
<PRE>
Room Path    <INPUT TYPE = "TEXT" NAME="Room" VALUE = "mic:\\ChatSvr\#Demo" SIZE = "40">
    Nickname    <INPUT TYPE = "TEXT" NAME="Alias" VALUE="" SIZE = "40">
<P>
    <INPUT TYPE = "BUTTON" NAME="FluxBtn" VALUE = "   Join the chat   " OnClick = "FluxBtn_OnClick">
</PRE>
</FORM>
<SCRIPT LANGUAGE="VBScript">
SUB FluxBtn_OnClick        'Event triggered when button is pressed
    Dim ChatForm
    Set ChatForm = Document.WEBChat
    If (Chat.State = 1) Then
        Chat.EnterRoom ChatForm.Room.Value, "", ChatForm.Alias.Value, "", 1, 1
    Else 
        If (Chat.State = 2) Then
            Chat.CancelEntering
            Chat.ClearHistory
        Else 
            If (Chat.State = 3) Then
                Chat.ExitRoom
                Chat.ClearHistory
            End If
        End If
    End If
END SUB
SUB Chat_OnStateChanged(ByVal NewState)    'Chat control event triggered when the chat's state is changed
    Dim ChatForm
    Set ChatForm = Document.WEBChat
    If (NewState = 1) Then
        ChatForm.FluxBtn.Value = "   Join the chat   "
        Chat.BackColor = 255    'UI Frame is red
    Else
        If (NewState = 2) Then
            ChatForm.FluxBtn.Value = "Cancel Entering"
            Chat.BackColor = 33023    'UI Frame is yellow
        Else
            If (NewState = 3) Then
                ChatForm.FluxBtn.Value = "Leave the chat"
                Chat.BackColor = 49152    'UI Frame is green
            End If
        End If
    End If
END SUB
</SCRIPT>
</BODY>
</HTML>
Note The version in the codebase line is subject to change and should be updated to the current version of the control that is available.
The <OBJECT> Tag

The <OBJECT> tag is required to download the Chat control that the unique CLASSID parameter value specifies. If the ActiveX control specified is not already on the computer, it will be downloaded from the URL value in the CODEBASE parameter. The ID parameter indicates the name of the MSChat object that the VBScript code will reference.
The <PARAM> tags are used within the <OBJECT> tag to specify default values for any property the object supports. In the previous example, the UIOption property bitmask is set to enable all options except History text box hyperlinked URLs (value 2048). The Appearance parameter causes the Chat control to appear as a 3-D object, and the BackColor parameter displays the user interface border in red. For information on other <OBJECT> parameters, see the HTML element reference for OBJECT.
The <FORM> Tag

The <FORM> tag is used to place objects such as buttons and text boxes on the HTML page. This is similar to using a Form in Microsoft Visual Basic or Microsoft Visual Basic for Applications. The example above creates a form with two text boxes and a button. The <INPUT TYPE = "TEXT"> tag is used to allow the user to specify a chat server room path and the user's nickname to be used in the chat room. The <INPUT TYPE = "BUTTON"> tag creates a button that can be clicked to join the chat, cancel entering the chat, and leave the chat.
The "TEXT" and "BUTTON" input types are included in the set of intrinsic HTML controls built into the Internet Explorer browser itself, and therefore do not require the use of the <OBJECT> tag to make them available. For further information on intrinsic HTML controls and their associated properties, methods, and events, refer to Inside Microsoft Visual Basic, Scripting Edition (Scot Hillier, Microsoft Press).
The <SCRIPT> Tag

The <SCRIPT> tag selects the scripting language to be used until the browser reaches the </SCRIPT> tag. In the previous example, VBScript code is used to execute when either of two events occur, including a button click (OnClick) event and a state change (OnStateChanged) event. The FluxBtn_OnClick subprocedure is executed whenever the button is clicked by the user. When this occurs, the procedure checks the current state of the user's HTML Chat client by retrieving the value of the State property. Based on the current Chat state, the procedure either connects to the specified Chat room with the EnterRoom method, cancels the request to join the Chat with the CancelEntering method, or disconnects from the Chat with the ExitRoom method. After responding to the button click, the Chat_OnStateChanged subprocedure is executed because the Chat control's state has been changed. This procedure simply checks the new state of the Chat control, and sets the appropriate button text with the Value property; the control's background color is changed with the BackColor property.
Note The Value property and OnClick event are associated with the set of intrinsic HTML controls mentioned previously.

Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.