The objects that comprise the Microsoft Chat Protocol Control 2.0 are:
MsChatPr is the top-level object in the Chat Protocol control object model. This section describes the methods, properties, and events supported by the MsChatPr object.
ChannelProperty, Channels, ConnectionState, ConnectionType, ConvertedString, MaxStringLength, NewChatItems, Nickname, OpeningChannels, ProcessProtocolMessages, PropertyAccessTimeOut, ServerName, ServerProperty, UserProperty
AboutBox, BanUsers, CancelConnectLogin, ChangeNickname, ChangeUserProperty, Connect, Disconnect, IgnoreUsers, KickUser, KillChannel, ListChannels, ListUsers, Login, QueryChannelProperty, QueryServerProperty, QueryUserProperty, SendInvitation, SendPrivateMessage, SendProtocolMessage, SetAway
OnAddMember, OnBeginEnumeration, OnChannelError, OnChannelProperty, OnChannelPropertyChanged, OnChannelState, OnConnectionError, OnConnectionState, OnDelMember, OnEndEnumeration, OnInvitation, OnKnock, OnMemberKicked, OnMemberProperty, OnMemberPropertyChanged, OnMessage, OnPrivateMessage, OnProtocolMessage, OnServerProperty, OnServerTextMessage, OnUserProperty, OnUserPropertyChanged
This section describes the properties associated with the MsChatPr object.
Synchronously accesses a channel property.
value=object.ChannelProperty(ChannelPropertyName[, ChannelName])
Part Description value Required. An object expression that evaluates to a ChatItems object. object Required. An object expression that evaluates to an MsChatPr control. ChannelPropertyName Required. A string that contains one of the valid channel property name values in the following table.
IRCX IRC/IRCX protocol only protocols Account BannedList ClientData Keyword ClientGuid MaxMemberCount CloneList MemberCount CreationTime Modes HostKey Name Lag Topic Language ObjectId OnJoin OnPart OwnerKey Rating ServicePath Subject ChannelName Optional. A string expression that can be omitted or empty if there is exactly one open channel in the collection. In this case, the call concerns that uniquely open channel. Otherwise ChannelName must be the Name of an existing channel on the server.
Access is read-only.
If the property could not be retrieved within the number of milliseconds specified in the PropertyAccessTimeOut property, an OnChannelProperty event is fired with the requested property.
Dim chatitemobj As ChatItems Set chatitemobj = MsChatPr1.ChannelProperty("Rating", "#MyRoom") Set chatitemobj = MsChatPr1.ChannelProperty("Modes") 'There is only one open channel Set chatitemobj = Nothing
Returns the Channels collection of the control.
value=object.Channels
Part Description value Required. An object expression that evaluates to a Channels object. object Required. An object expression that evaluates to an MsChatPr control.
Access is read-only.
Dim chancoll As Channels Set chancoll = MsChatPr1.Channels
Returns the current connection state of the control.
value=object.ConnectionState
Part Description value Required. A variable of enumConnectionState type. object Required. An object expression that evaluates to an MsChatPr control.
Access is read-only.
This property is always accessible. After successfully calling the Connect method, ConnectionState switches from csDisconnected to csConnecting to csConnected.
After successfully calling the Login method, ConnectionState switches from csConnected to csLogging to csLogged, or from csDisconnected to csConnecting to csLogging to csLogged.
When calling Disconnect, ConnectionState switches from csConnected to csDisconnecting to csDisconnected, or from csLogged to csDisconnecting to csDisconnected.
Dim cs As enumConnectionState cs = MsChatPr1.ConnectionState
Returns the type of connection (IRC or IRCX) established with the chat server.
value=object.ConnectionType
Part Description value A variable of enumConnectionType type. The enumConnectionType is made of the values ctIRC = 0 and ctIRCX = 1. object Required. An object expression that evaluates to an MsChatPr control.
Access is read-only.
If a server is an IRCX server, the control automatically switches to the IRCX mode at connection time.
The ConnectionType property is accessible as soon as the OnConnectionState event is fired after calling the Connect method, or as soon as the OnConnectionState event is fired after calling the Login method.
Dim ct As enumConnectionType ct = MsChatPr1.ConnectionType
Returns a converted version of the source string.
value=object.ConvertedString(ConversionType, ConversionSource, Source, PostProcess)
Part Description value Required. A string variable to contain the converted version of the source string. object Required. An object expression that evaluates to an MsChatPr control. ConversionType Required. A variable of enumConversionType type. When ConversionType is set to cvtToUTF8, the property returns the UTF8 version of the source string. The source string must be a regular Unicode BSTR. When ConversionType is set to cvtToUnicode, the property returns the Unicode version of the source string. The source string must be a UTF8 BSTR.
ConversionSource Required. A variable of enumConversionSource type. When ConversionSource is set to cvsNormal, the source parameter can represent any string. For example, an incoming or outgoing text message or a topic can be represented by the source parameter. When ConversionSource is set to cvsNickname, the source parameter represents a nickname.
When ConversionSource is set to cvsChannelName, the source parameter represents a channel Name.
Source Required. A string variable. Because the IRCX protocol uses UTF8 modified strings for extended nicknames and channel names, the control exposes a method to convert strings from Unicode to UTF8 and vice-versa. PostProcess Required. A Boolean value. When set to TRUE, the postprocessing mechanism shown in the following table is used when converting from Unicode to UTF8.
Character Becomes string '\0' "\0" '\' "\\" '\n' "\n" '\r' "\r" '\t' "\t" ' ' "\b" ',' "\c" When converting from UTF8 to Unicode, the postprocessing mechanism shown in the following table is used.
String Becomes Character "\0" '\0' "\\" '\' "\n" '\n' "\r" '\r' "\t" '\t' "\b" ' ' "\c" ','
Access is read-only.
Examples
MsChatPr1.ConvertedString(cvtToUTF8, cvsNormal, "Hi Régis, how are you?", FALSE) 'returns "Hi Régis, how are you?"MsChatPr1.ConvertedString(cvtToUnicode, cvsNormal, "Touché\c\bcoulé!", TRUE) 'returns "Touché, coulé!"MsChatPr1.ConvertedString(cvtToUTF8, cvsNickname, "The Säïnt", TRUE) 'returns "'The\bSäïnt"MsChatPr1.ConvertedString(cvtToUnicode, cvsNickname, "'La\bBellä\bXena", TRUE) 'returns "La Bellä Xena"MsChatPr1.ConvertedString(cvtToUTF8, cvsChannelName, "%#Les Français parlent aux Français", TRUE) 'returns "%#Les\bFrançais\bparlent\baux\bFrançais"MsChatPr1.ConvertedString(cvtToUnicode, cvsChannelName, "%&Zûlû", TRUE) 'returns "%&Zûlû"
Returns the maximum length of some string properties.
value=object.MaxStringLength(StringType)
Part Description value Required. A long integer that receives the maximum length of some string properties. object Required. An object expression that evaluates to an MsChatPr control. StringType Required. A variable of enumStringType type. If the StringType parameter is set to stServerMessage, MaxStringLength returns the maximum length, in bytes, of any message sent to the server. For regular IRC servers, this value is 512 bytes. This variable is customizable on IRCX servers and could, for example, be 2048 bytes. The following list itemizes the other values defined by the servers. These values might change in future server versions.
MaxStringLength(stChannelAccount) = 31 MaxStringLength(stChannelClientData) = 255 MaxStringLength(stChannelHostKey) = 31 MaxStringLength(stChannelKeyword) = 31 MaxStringLength(stChannelLanguage) = 31 MaxStringLength(stChannelName) = 200 MaxStringLength(stChannelOnJoin) = 255 MaxStringLength(stChannelOnPart) = 255 MaxStringLength(stChannelOwnerKey) = 31 MaxStringLength(stChannelRating) = 255 MaxStringLength(stChannelSubject) = 31 MaxStringLength(stChannelTopic) = 160
Access is read-only.
Dim lMaxMessageLen As Long lMaxMessageLen = MsChatPr1.MaxStringLength(stServerMessage)
Returns a newly allocated ChatItems object.
value=object.NewChatItems
Part Description value Required. An object expression that evaluates to a ChatItems object. object Required. An object expression that evaluates to an MsChatPr control.
Access is read-only.
This property exists for Visual Basic® Scripting Edition (VBScript) users. The following syntax does not work in VBScript.
Dim chatitemobj Set chatitemobj=New ChatItemsUsers must use the NewChatItems property instead, as in the following:
Dim chatitemobj Set chatitemobj=MsChatPr1.NewChatItems '...use chatitemobj Set chatitemobj=Nothing 'releases chatitemobjDynamic allocation of a ChatItems object is necessary in order to perform some server queries, such as ListChannels or BanMembers.
Dim mi Set mi = MsChatPr1.NewChatItems mi.AssociatedType = "Query" mi.Item("IPAddressOp") = "EndsWith" mi.Item("IPAddress") = ".com" MsChatPr1.Channels(1).BanMembers mi, True Set mi = Nothing
Returns the control user's Nickname for the current connection, or an empty string if there is no live connection.
value=object.Nickname
Part Description object Required. An object expression that evaluates to an MsChatPr control. value Required. A string expression to contain the control user's Nickname for the current connection, or an empty string if there is no live connection.
Access is read-only.
Dim strMyNickname As String strMyNickname=MsChatPr1.Nickname 'or Sub MsChatPr1_OnMemberKicked(Channel As Channel, KickedNickname As String, KickerNickname As String, Reason As String) If (KickedNickname = MsChatPr1.Nickname) Then MsgBox "You were kicked by " + KickerNickname + " because: " + Reason End If End Sub
Returns the number of opening channels in the Channels collection.
value=object.OpeningChannels
Part Description value Required. A long integer value that receives the number of opening channels in the Channels collection. object Required. An object expression that evaluates to an MsChatPr control.
Access is read-only.
Dim lOpeningChannels As Long MsChatPr1.Channels.Add MsChatPr1.Channels.JoinChannel "#Foo" lOpeningChannels = MsChatPr1.OpeningChannels 'returns 1
Determines whether the OnProtocolMessage event is fired for each incoming server message.
object.ProcessProtocolMessages=value
Part Description object Required. An object expression that evaluates to an MsChatPr control. value Required. A Boolean value.
Access is read/write.
When ProcessProtocolMessages is set to TRUE, the incoming server messages are immediately treated internally and exposed through some event. The OnProtocolMessage event is fired only when the incoming server message cannot be properly interpreted by the control.
However, when ProcessProtocolMessages is set to FALSE, the control first exposes the incoming server messages through the OnProtocolMessage event.
In the OnProtocolMessage event handler, the control user can set the EnableDefault parameter to TRUE or FALSE. The parameter is set to TRUE by default.
If set to TRUE, the control treats the incoming server message normally and fires the usual event. If set to FALSE, however, the control will not treat the message internally.
Tip Only experts should set the ProcessProtocolMessages property to FALSE. If the incoming messages are not treated internally by the control, the control might end up in an unstable state. This mode must be handled with extreme caution.
MsChatPr1.ProcessProtocolMessages = False
Reads or writes the time-out value when synchronously accessing a property.
object.PropertyAccessTimeOut=value
Part Description object Required. An object expression that evaluates to an MsChatPr control. value Required. A long integer value that contains the time-out expressed in milliseconds. This unique property is used for all the synchronous property accesses being performed in the control.
Access is read/write.
If a time-out condition occurs when trying to synchronously access a property, an error is returned. An OnChannelProperty, OnServerProperty, OnMemberProperty, or OnUserProperty event might be fired after a time-out error occurs. This event exposes the property that could not be accessed in time.
Dim chatitemobj As ChatItems MsChatPr1.PropertyAccessTimeOut = 10000 '10 seconds Set chatitemobj = MsChatPr1.ChannelProperty("MaxMemberCount", "#MyRoom") '... use chatitemobj Set chatitemobj = MsChatPr1.Channels(2).MemberProperty("Identity", "Mila") '... use chatitemobj Set chatitemobj = NothingIn the following example, a time-out condition has caused an error. An OnChannelProperty event is fired, in which the ChannelItems parameter exposes the MaxMemberCount property and all other known properties.
Dim chatitemobj As ChatItems MsChatPr1.PropertyAccessTimeOut = 10 '10 milliseconds Set chatitemobj = MsChatPr1.ChannelProperty("MaxMemberCount", "#MyRoom")
ChannelProperty, MemberProperty, OnChannelProperty, OnMemberProperty, OnUserProperty, OnServerProperty, ServerProperty
Returns the server name of the current connection, or an empty string if there is no live connection.
value=object.ServerName
Part Description object Required. An object expression that evaluates to an MsChatPr control. value Required. A string expression to contain an empty string or the name of the server if there is a live connection.
Access is read-only.
Dim strServerName As String strServerName = MsChatPr1.ServerName
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.