This section describes the methods associated with the Microsoft Chat control.
Displays the About message dialog box.
object.AboutBox
Part Description object Required. An object expression that evaluates to a Chat control.
Bans a member from or reinstates a member to a chat room.
object.BanParticipant Name, Set
Part Description object Required. An object expression that evaluates to a Chat control. Name Required. A BSTR value that contains the alias of the member to be banned or reinstated. Set Required. A Boolean value that determines whether the member is banned or reinstated. If the value is set to TRUE, the member is banned from the chat room and cannot rejoin it. If the value is set to FALSE, the member is reinstated and can join the chat at any time.
This method only prevents the member from rejoining or allows the member to rejoin the chat room after leaving or being kicked. It does not kick the member from the chat room. BanParticipant cannot be called before the OnEndEnumeration event has been triggered.
Cancels an EnterRoom operation
object.CancelEntering
Part Description object Required. An object expression that evaluates to a Chat control.
This method should be called only when the control's State property is equal to 2 (Connecting).
Empties the History text box.
object.ClearHistory
Part Description object Required. An object expression that evaluates to a Chat control.
This method has an effect only if the value of the UIOption property includes a History text box (value=8).
Allows the user to enter the specified chat room.
object.EnterRoom RoomPath, RoomPwd, ThisParticipantAlias, SecurityPackage, Flags, Type
Part Description object Required. An object expression that evaluates to a Chat control. RoomPath Required. A string value containing the location of the chat room. The format of the string should be: [prefix]://server-name[:port-number]/[[#]|[&]]room-name
The prefix is optional and can be either mic or irc. The server-name is the host name of the chat server computer. The optional number sign (#) indicates that the chat room can be a global IRC room. The optional ampersand (&) indicates that the room can be a local IRC or MIC room. The room-name is the name of the chat room.
RoomPwd Required. A string containing either the room password or the host key used when creating or joining a password-protected room. ThisParticipantAlias Required. A string containing the alias that the user will be known by in the chat room. SecurityPackage Required. A string containing a list of security packages that are separated by semicolons and ordered by preference. If SecurityPackage is set to an empty string, the control asks the server for a list of security packages it provides. If the server replies no packages at all, an anonymous connection is tried. If the server replies with a list of packages, the first package on the list is tried. If the string is set to "ALL", all the server's security packages are tried in an order defined by the server. The control will stop looping through the security packages as soon as one package succeeds or an error not related to the account information occurs. If all packages fail, the control will try to connect the user anonymously. The "ANON" string can be used to request anonymous connections. Flags Required. A combination of values used when creating or joining a room. These values characterize the room type and cannot change dynamically once the room is created. Set to zero to use no flags. Can be any combination of the following values.
Value Description 1 Join an existing chat room or create a chat room if one does not exist. If this flag is not set, the EnterRoom method will create a chat, but will not join an existing chat. 2 The chat room will not be exposed to other servers on the Internet. 4 The chat room is set up as read-only for news feeds, stock quotes, and so on. 8 The chat room will allow only MIC clients to join it. IRC users will not be able to join the chat room. 16 The server will accept only authenticated members in this chat room. 32 Only authenticated members can talk in the chat room. Type Required. A combination of values to set the type of chat room. Set to zero to use no flags. The chat room type can dynamically vary during its lifetime. The user is notified when the room type changes through the OnRoomTypeChanged event. Can be any combination of the following values.
Value Description 1 Allows any user into the chat room. 2 Allows only hosts to change the topic of the chat room. 4 Allows only users who logged on to this server to enter the chat room. 8 Disables whispering in the chat room. 16 Creates an auditorium room. The member list shows only the user and the hosts. Participants cannot whisper, but hosts can whisper to anybody, regardless of whether the no-whisper (Type=8) flag is set. Messages coming from participants are sent only to the hosts. 32 Creates a moderated room. Members join the chat room as spectators by default.
This method should be called only when the control's State property is equal to 1 (Disconnected).
Disconnects the user from the current chat room.
object.ExitRoom
Part Description object Required. An object expression that evaluates to a Chat control.
This method should be called only when the control's State property is equal to 3 (Connected).
Gets the real name of a participant by using the member's participant ID or alias (nickname).
object.GetParticipantRealName ParticipantID, Alias, Synchronous, RealName
Part Description object Required. An object expression that evaluates to a Chat control. ParticipantID Required. A long integer value that indicates which member's real name is being requested. If ParticipantID is set to -1, the method uses the selected member's participant ID in the Participant list box. If ParticipantID is not set to -1, the participant ID must have come from an OnEnterParticipant event. This value must be set to zero if the application is requesting the real name by using the member's alias. Alias Required. A BSTR value that contains the requested member's alias. This value must be set to an empty string if the application is requesting the real name by using the member's ParticipantID. Synchronous Required. A Boolean value that indicates whether this method is executed synchronously or asynchronously. If Synchronous is set to TRUE, the real name is put into the string that is pointed to by RealName for a Visual Basic or C/C++ application. If Synchronous is set to FALSE, the answer to the query comes back asynchronously. If the query is successful, the OnParticipantRealName event returns the information. If the query is not successful, the OnError event is triggered. VBScript does not support pointers, so Synchronous must be set to FALSE. RealName Required. An address of a string where the real name of the member will be stored if the method is executed synchronously.
When using ParticipantID, the scope of the search is limited to members currently in the chat room. When using Alias, the entire server is searched.
Invites a member to the user's current chat room.
object.InviteParticipant Alias
Part Description object Required. An object expression that evaluates to a Chat control. Alias Required. A string value that contains the alias of the member to invite.
The member must be on the same chat server as the user.
Kicks a member from the chat room.
object.KickParticipant ParticipantID, KickComment
Part Description object Required. An object expression that evaluates to a Chat control. ParticipantID Required. A long integer value that indicates which member will be kicked. If ParticipantID is set to -1, the method uses the participant ID of the member selected in the Participant list box. If ParticipantID is not set to -1, the participant ID must have come from an OnEnterParticipant event. KickComment Required. A BSTR value that contains a text message with the host's reason for kicking the member. If the kicked member uses the Chat control and has the value 128 (inform about member status changes) set in the UIOption property, the member will see a message box with this reason.
This method cannot be called before the OnEndEnumeration event has been triggered.
Changes the appearance of the cursor to a cross hair so the user can resize the control by using the arrow keys or the mouse.
object.MoveSplitBar
Part Description object Required. An object expression that evaluates to a Chat control.
Selects, deselects, or inverts the selection of members in the Participant list box.
object.SelectParticipants value
Part Description object Required. An object expression that evaluates to a Chat control. value Required. A short integer value that determines which members are selected. Can be set to one of the following values.
Value Description 0 Deselects any highlighted member. 1 Selects all the members. 2 Deselects the highlighted members and selects the members that were not highlighted.
This method has an effect only if the UIOption property includes a Participant list box (value=4).
Sends a message.
object.SendMessage DestinationList, Count, Message
Part Description object Required. An object expression that evaluates to a Chat control. DestinationList Required. A VARIANT value that indicates how this message should be distributed. The message can be broadcast to all members, whispered to one member, or whispered to a group of members:
- To broadcast the message to all members, the value must be set by an integer, a long integer, or an array of long integers (limited to one element) equal to -1.
- To whisper to one member (unicast), the value must be set by a long integer equal to the member's participant ID.
- To whisper to a group of members (multicast), the value must be set by an array of long integers corresponding to the member's participant ID.
Count Required. A short integer that determines the number of recipients that will receive the message. To broadcast a message to all members, set the value of Count to zero. Otherwise, set Count to the number of members that will receive the message. Message Required. A VARIANT value that contains the message being distributed:
- To distribute a text message to be displayed in the History text box of the selected members, the data type must be a BSTR value that contains the text to be displayed.
- To distribute a data message being sent to the selected members, the data can be an array of bytes, shorts, longs, floats, doubles, Booleans, errors, currencies, or dates that correspond to the following VARIANT types: VT_UI1, VT_I2, VT_I4, VT_R4, VT_R8, VT_BOOL, VT_ERROR, VT_CY, VT_DATE.
This method cannot be called before the OnEndEnumeration event has been triggered.
Changes the status of the member in a chat room.
object.SetParticipantStatus ParticipantID, Mask, Status
Part Description object Required. An object expression that evaluates to a Chat control. ParticipantID Required. If ParticipantID=-1, the member selected in the Participant list box will be affected. Only one member can be selected for this method to work. Otherwise, the value of ParticipantID has to come from an OnEnterParticipant event. Mask Required. A short integer indicating the types of status changes that the user wants to make. Set to zero if no masks are wanted. Can be set to one of the following values or a combination of 1 and one other value.
Value Description 1 Mask to set a member's privileges. Must be set if Status is 1, 2, or 4. 2 Mask to set the whisper status of the user. Must be set if Status is changed to 8 or zero (to allow whispers). 4 Mask to set the ignored status of a member. Must be set if Status is changed to 16 or zero (to allow the user to receive messages from the member again). Status Required. A short integer setting the participant's status changes. Set to zero if the user wants to allow the member to whisper to the user (if Mask includes 2) or allow the user to receive messages from the member (if Mask includes 4). Can be set to any combination of the following values.
Value Description 1 Changes the privileges of the member to a host. The value of Mask must include 1. 2 Changes the privileges of the member to a participant. The value of Mask must include 1. 4 Changes the privileges of the member to a spectator. The value of Mask must include 1. 8 Changes the status of the user to not allow whispers. The value of Mask must include 2. 16 Changes the status of the member to be ignored so the user will not receive any messages from that member. The value of Mask must include 4.
This method cannot be called before the OnEndEnumeration event. The following are the rules that apply to status changes:
- The user cannot ignore herself or himself or the hosts.
- The user can set the flag for no whispers (Status=8) only on herself or himself.
- Only a host can change another user's privileges.
- The user cannot set both the no-whisper and ignored values (or masks), since users cannot ignore themselves and the user cannot set the whisper value of another member.
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.