Objects

ServerProperty Property

---

Description

Synchronously accesses a server property.

Syntax

value=object.ServerProperty(ServerPropertyName)

Part	Description
value	Required. An object expression that evaluates to a ChatItems object.
object	Required. An object expression that evaluates to an MsChatPr control.
ServerPropertyName	Required. A string that contains one of these valid server property name values: AnonymousAllowed ChannelCount IgnoredUsers Info MaxMessageLength Name NetInvisibleCount NetServerCount NetUserCount NodeServerCount NodeUserCount SecurityPackages SysopCount UnknownConnectionCount

Remarks

Access is read-only.

If the property could not be retrieved within the number of milliseconds specified by the PropertyAccessTimeOut property, a time-out error is thrown and an OnServerProperty event might be fired later with the requested property.

The connection state must be at least csConnected to access the following properties:

AnonymousAllowed

IgnoredUsers

MaxMessageLength

Name

SecurityPackages

The state must be at least csLogged to access all other server properties.

Example

Dim chatitemobj As ChatItems

Set chatitemobj = MsChatPr1.ServerProperty("AnonymousAllowed")
'...use chatitemobj 
Set chatitemobj = MsChatPr1.ServerProperty("NodeUserCount")
'...use chatitemobj 
Set chatitemobj = Nothing

See Also

PropertyAccessTimeOut

UserProperty Property

---

Description

Synchronously accesses a user property.

Syntax

value=object.UserProperty(UserPropertyName[, Nickname])

Part	Description
value	Required. An object expression that evaluates to a ChatItems object.
object	Required. An object expression that evaluates to an MsChatPr control.
UserPropertyName	Required. A string containing one of these valid user property name values: Away Channels HostInChannels Identity IdleTime IPAddress Modes Nickname OwnerOfChannels RealName ServerInfo ServerName SignOnTime UserName VoiceInChannel
Nickname	Optional. A variant parameter that can be omitted or empty, in which case the call concerns the control user. Otherwise the Nickname must be a current server user.

Remarks

Access is read-only.

If the property could not be retrieved within the number of milliseconds specified by the PropertyAccessTimeOut property, an OnUserProperty event is fired with the requested property.

Example

Dim chatitemobj As ChatItems

Set chatitemobj = MsChatPr1.UserProperty("Away", "Mila")
'. . . use chatitemobj			
Set chatitemobj = MsChatPr1.UserProperty("SignOnTime")
'. . . use chatitemobj 
Set chatitemobj = Nothing

See Also

OnUserProperty, PropertyAccessTimeOut

Methods

---

This section lists the methods supported by the MsChatPr object.

AboutBox Method

---

Description

Displays the About message dialog box.

Syntax

object.AboutBox

Part	Description
object	Required. An object expression that evaluates to an MsChatPr object.

BanUsers Method

---

Description

Bans users from the server and reinstates users to the server.

Syntax

object.BanUsers UserItems, Set[, Reason][, Duration]

Part	Description
object	Required. An object expression that evaluates to an MsChatPr control.
UserItems	Required. An object expression that evaluates to a ChatItems object. Defines which users are banned or reinstated. The item names that can be used to construct the ChatItems object are: Nickname NicknameOp UserName UserNameOp IPAddress IPAddressOp
Set	Required. A Boolean variable that determines whether the users are banned or reinstated.
Reason	Optional. A variant that is used if Set is TRUE to contain the reason for banishing users.
Duration	Optional. A variant that is used if Set is TRUE to indicate, in minutes, the length of time a user or users will be banned.

Remarks

This feature is reserved for administrators and system operators only. Banned users will not be able to log on to the server. Some IRC servers do not provide this feature and will return an error code.

Examples

These examples illustrate methods of using BanUsers to ban users from the server and to reinstate users to the server.

1. Ban a specific user:

Dim chatitemobj As ChatItems

Set chatitemobj = New ChatItems
chatitemobj.AssociatedType  = "Query"
chatitemobj.Item("UserName") = "RebeccaH"
chatitemobj.Item("IPAddressOp") = "EndsWith"
chatitemobj.Item("IPAddress") = ".microsoft.com"
MsChatPr1.BanUsers chatitemobj, True, "Abusive behavior"
Set chatitemobj = Nothing

2. Ban all the users with an IP address that ends with .edu, for the duration of one hour:

Dim chatitemobj As ChatItems

Set chatitemobj = New ChatItems
chatitemobj.AssociatedType  = "Query"
chatitemobj.Item("IPAddressOp") = "EndsWith"
chatitemobj.Item("IPAddress") = ".edu"
MsChatPr1.BanUsers chatitemobj, True, , 60
Set chatitemobj = Nothing

3. Stop banning the same group:

Dim chatitemobj As ChatItems

Set chatitemobj = New ChatItems
chatitemobj.AssociatedType  = "Query"
chatitemobj.Item("IPAddressOp") = "EndsWith"
chatitemobj.Item("IPAddress") = ".edu"
MsChatPr1.BanUsers chatitemobj, False
Set chatitemobj = Nothing

CancelConnectLogin Method

---

Description

Cancels a Connect or Login call.

Syntax

object.CancelConnectLogin

Part	Description
object	Required. An object expression that evaluates to an MsChatPr control.

Remarks

This method can be called when the connection state is csConnecting or csLogging.

Example

MsChatPr1.Connect "comicsrv1.microsoft.com"
    'OnConnectionState(csConnecting) event is fired 
MsChatPr1.CancelConnectLogin

MsChatPr1.Login "irc.mtv.com", "JB007", "JamesB", "James Bond"
    'OnConnectionState(csConnecting) event is fired 
MsChatPr1.CancelConnectLogin

MsChatPr1.Login "irc.univ-lyon1.fr", "Vette"
    'OnConnectionState(csConnecting) event is fired
    'OnConnectionState(csLogging) event is fired		
MsChatPr1.CancelConnectLogin

See Also

Connect, Login

ChangeNickname Method

---

Description

Asynchronously changes the user's Nickname.

Syntax

object.ChangeNickname NewNickname

Part	Description
object	Required. An object expression that evaluates to an MsChatPr control.
NewNickname	Required. A string expression containing the user's new nickname.

Remarks

A successful call to ChangeNickname results in an OnUserPropertyChanged event.

Example

MsChatPr1.ChangeNickname "NaomiH"

'This is a shortcut for:
MsChatPr1.ChangeUserProperty "Nickname", "NaomiH"

See Also

ChangeUserProperty

ChangeUserProperty Method

---

Description

Asynchronously modifies a user property.

Syntax

object.ChangeUserProperty UserPropertyName, NewUserProperty[, Nickname]

Part	Description
object	Required. An object expression that evaluates to an MsChatPr control.
UserPropertyName	Required. A string that must contain one of these two valid values: "Modes" or "Nickname".
NewUserProperty	Required. A variant, the type of which depends on the new user property.
Nickname	Optional. A variant. Can be omitted or empty, in which case the call concerns the control user. Otherwise, the Nickname must be a current server user.

Remarks

This method can be used to change nicknames, user Modes, or ignore/stop ignoring other users. Callers can change only their own nickname or user modes.

A successful call to ChangeUserProperty results in an OnUserPropertyChanged event.

You cannot ignore a server system operator or administrator.

Examples

1. Change the nickname:

MsChatPr1.ChangeUserProperty "Nickname", "ElisabethH", "Moi"
'or
MsChatPr1.ChangeUserProperty "Nickname", "ElisabethH"
    'This is equivalent to MsChatPr1.ChangeNickname "ElisabethH"

2. Become invisible:

MsChatPr1.ChangeUserProperty "Modes", umInvisible

3. Give up the system operator privileges and become visible:

MsChatPr1.ChangeUserProperty "Modes", umNotSysop + umNotInvisible

4. Ignore a user:

MsChatPr1.ChangeUserProperty "Modes", umClientIgnored, "Maja"

5. Stop ignoring a user:

MsChatPr1.ChangeUserProperty "Modes", umNotClientIgnored, "Maja"

See Also

ChangeNickname

Connect Method

---

Description

Creates a connection between the user's computer and the server.

Syntax

object.Connect ServerName

Part	Description
object	Required. An object expression that evaluates to an MsChatPr control.
ServerName	Required. A string expression that contains the ServerName. This parameter can include the socket port to be used. The port 6667 is used by default.

Remarks

A successful Connect call results in an OnConnectionState event for which the ConnectionState parameter is csConnecting. Next, an OnConnectionState event is fired for which the ConnectionState parameter is csConnected. The server properties accessible at the csConnected point are:

Name

MaxMessageLength

SecurityPackages

AnonymousAllowed

IgnoredUsers

All the other server properties can be accessed once the user is logged on.

Examples

'ServerName only, port 66667 by default
MsChatPr1.Connect "comicsrv1.microsoft.com" 

'ServerName and socket port
MsChatPr1.Connect "irc.eskimo.com:6668"      

See Also

Login

Disconnect Method

---

Description

Disconnects from the chat server.

Syntax

object.Disconnect

Part	Description
object	Required. An object expression that evaluates to an MsChatPr control.

Remarks

The Disconnect method can be called when the connection state is csConnected or csLogged.

A successful call results in an OnConnectionState event for which the connection state is csDisconnecting, and another OnConnectionState event for which the ConnectionState parameter is csDisconnected.

Examples

MsChatPr1.Connect "comicsrv1.microsoft.com"
    'OnConnectionState(csConnecting) event is fired
    'OnConnectionState(csConnected) event is fired
MsChatPr1.Disconnect


MsChatPr1.Login "irc.mtv.com", "JB007", "JamesB", "James Bond"
    'OnConnectionState(csConnecting) event is fired
    'OnConnectionState(csLogging) event is fired
    'OnConnectionState(csLogged) event is fired
MsChatPr1.Disconnect

See Also

Connect, Login, OnConnectionState

IgnoreUsers Method

---

Description

Allows the caller to ignore or stop ignoring users.

Syntax

object.IgnoreUsers UserItems, Set

Part	Description
object	Required. An object expression that evaluates to an MsChatPr control.
UserItems	Required. An object expression that evaluates to a ChatItems object. Allows the caller to set criteria on the user's Nickname, UserName, or IPAddress. The item names that can be used to construct the ChatItems object are: Nickname NicknameOp UserName UserNameOp IPAddress IPAddressOp
Set	Required. A Boolean value used to indicate if a user should be ignored. If set to TRUE, the user is ignored. If set to FALSE, the user is no longer ignored.

Remarks

Ignoring a user means that the caller will no longer receive private messages from the ignored user.

Administrators and system operators are never ignored, even if the caller ignores a group of users that includes an administrator or system operator.

The IgnoredUsers server property returns the list of ignored users in the form of an array of ChatItems objects and is updated each time the user calls the IgnoreUsers method.

Examples

1. Ignore one specific user:

Dim chatitemobj As ChatItems

Set chatitemobj = New ChatItems
chatitemobj.AssociatedType  = "Query"
chatitemobj.Item("Nickname") = "Justin"
chatitemobj.Item("UserName") = "ArthurB"
chatitemobj.Item("IPAddress") = "foo.microsoft.com"
MsChatPr1.IgnoreUsers chatitemobj, True
Set chatitemobj = Nothing

2. Ignore all the users with an IP address that ends with .edu:

Dim chatitemobj As ChatItems

Set chatitemobj = New ChatItems
chatitemobj.AssociatedType  = "Query"
chatitemobj.Item("IPAddressOp") = "EndsWith"
chatitemobj.Item("IPAddress") = ".edu"
MsChatPr1.IgnoreUsers chatitemobj, True
Set chatitemobj = Nothing

3. Stop ignoring the same group:

Dim chatitemobj As ChatItems

Set chatitemobj = New ChatItems
chatitemobj.AssociatedType  = "Query"
chatitemobj.Item("IPAddressOp") = "EndsWith"
chatitemobj.Item("IPAddress") = ".edu"
MsChatPr1.IgnoreUsers chatitemobj, False
Set chatitemobj = Nothing

4. Stop ignoring everybody:

Dim vIgnoredUsers As Variant
Dim chatitemobj As ChatItems
Dim iIndex As Integer

Set chatitemobj = MsChatPr1.ServerProperty("IgnoredUsers")

If (chatitemobj.ItemValid("IgnoredUsers")) Then
    vIgnoredUsers = chatitemobj.Item("IgnoredUsers")
    If (Not IsEmpty(vIgnoredUsers)) Then
        For iIndex = LBound(vIgnoredUsers) To UBound(vIgnoredUsers)
        MsChatPr1.IgnoreUsers vIgnoredUsers(iIndex), False
        Next iIndex
    End If
End If

Set chatitemobj = Nothing 

KickUser Method

---

Description

Disconnects a user from the server.

Syntax

object.KickUser Nickname[, Reason]

Part	Description
object	Required. An object expression that evaluates to an MsChatPr control.
Nickname	Required. A string expression that contains an existing user Nickname.
Reason	Optional. Can be an empty value or a string containing the reason for user disconnection.

Remarks

This feature is reserved for administrators and system operators only.

Examples

MsChatPr1.KickUser "Rousseau", "You talk too much!"

MsChatPr1.KickUser "Voltaire"

KillChannel Method

---

Description

Terminates a channel on the server.

Syntax

object.KillChannel ChannelName[, Reason]

Part	Description
object	Required. An object expression that evaluates to an MsChatPr control.
ChannelName	Required. A string expression that must be an existing channel Name.
Reason	Optional. Can be empty, missing, or a string containing the reason for channel termination.

Remarks

The caller must be an administrator or system operator to successfully perform this operation.

All channel members are kicked out of the channel and the channel is closed.

Examples

MsChatPr1.KillChannel "#TheirChannel"

MsChatPr1.KillChannel "#BadChannel", "Bad language is used in this channel."

ListChannels Method

---

Description

Lists channels on the chat server.

Syntax

object.ListChannels ChannelQueryItems

Part	Description
object	Required. An object expression that evaluates to an MsChatPr control.
ChannelQueryItems	Required. An object expression that evaluates to a ChatItems object.

Remarks

The ChannelQueryItems parameter can restrict the listing to a subset of channels.

The IRC protocol is limited to listing all the server channels or only one specific channel. On an IRC server, the valid item name for ChannelQueryItems is "Name".

For an IRCX server, the valid item names are listed in the following table.

See Note for an explanation of the "Op" endings.

Item name		Type	Usage
Name		String	Sets listing criteria based on the name of the channel.
NameOp		String	Sets listing criteria based on the name of the channel.
Topic		String	Sets listing criteria based on the topic of the channel.
TopicOp		String	Sets listing criteria based on the topic of the channel.
Language		String	Sets listing criteria based on the language of the channel.
LanguageOp		String	Sets listing criteria based on the language of the channel.
Subject		String	Sets listing criteria based on the subject of the channel.
SubjectOp		String	Sets listing criteria based on the subject of the channel.
ChannelAgeMax		Long	Sets listing criteria based on the creation time of the channel.
ChannelAgeMin		Long	Sets listing criteria based on the creation time of the channel.
ListCount		Long	Limits the number of listed channels to a certain value.
MemberCount		Long	Sets listing criteria based on the member count of the channel.
MemberCountMax		Long	Sets listing criteria based on the member count of the channel.
MemberCountMin		Long	Sets listing criteria based on the member count of the channel.
TopicAgeMax		Long	Sets listing criteria based on the latest topic change of the channel.
TopicAgeMin		Long	Sets listing criteria based on the latest topic change of the channel.
Registered		Boolean	Limits the listed channels to registered channels only.

The channels are filtered depending on their PICS Rating and the user's ratings settings. For example, if the user cannot view unrated content, the ListChannels call fails on an IRC connection or shows only the rated channels on an IRCX connection. If the user has some specific PICS ratings settings, only the channels that are appropriately rated are exposed to the user.

A successful ListChannels call results in a succession of events. First, an OnBeginEnumeration event to mark the beginning of the channel listing is fired. Then, one OnChannelProperty( event for each channel listed transpires and the ChannelItems parameter exposes all the known channel properties. Finally, an OnEndEnumeration with the etChannels parameter event is fired to mark the end of the channel listing.

If a listing is stopped because of a limitation set by the ListCount item, an OnEndEnumeration with the etChannelsTruncated parameter event is fired instead.

The IRC protocol is limited to listing all the server channels or only one specific channel.

Examples

1. On an IRC/IRCX server:

'List all the channels:

Dim chatitemobj As ChatItems

Set chatitemobj = New ChatItems
chatitemobj.AssociatedType = "Query"
MsChatPr1.ListChannels chatitemobj
Set chatitemobj = Nothing

'List one specific channel:

Dim chatitemobj As ChatItems

Set chatitemobj = New ChatItems
chatitemobj.AssociatedType = "Query"
chatitemobj.Item("Name") = "#Comic_Chat"
MsChatPr1.ListChannels chatitemobj
Set chatitemobj = Nothing

2. On an IRCX server, list all the channels that have been created in the last hour, and limit the listing to 100 channels:

Dim chatitemobj As ChatItems

Set chatitemobj = New ChatItems
chatitemobj.AssociatedType = "Query"
chatitemobj.Item("ChannelAgeMax") = 60
chatitemobj.Item("ListCount") = 100
MsChatPr1.ListChannels chatitemobj
Set chatitemobj = Nothing

3. On an IRCX server, list all the channels that have between 10 and 50 members, in which the Topic includes the word "Corvette":

Dim chatitemobj As ChatItems

Set chatitemobj = New ChatItems
chatitemobj.AssociatedType = "Query"
chatitemobj.Item("MemberCountMin") = 10
chatitemobj.Item("MemberCountMax") = 50
chatitemobj.Item("TopicOp") = "Contains"
chatitemobj.Item("Topic") = "Corvette"
MsChatPr1.ListChannels chatitemobj
Set chatitemobj = Nothing

4. On an IRCX server, list all the registered channels that start with "#F" and have a Language property that contains "FR":

Dim chatitemobj As ChatItems

Set chatitemobj = New ChatItems
chatitemobj.AssociatedType = "Query"
chatitemobj.Item("Registered") = True
chatitemobj.Item("NameOp") = "StartsWith"
chatitemobj.Item("Name") = "#F"
chatitemobj.Item("LanguageOp") = "Contains"
chatitemobj.Item("Language") = "FR"
MsChatPr1.ListChannels chatitemobj
Set chatitemobj = Nothing

5. On an IRCX server, list all the channels that have "real estate" in their Subject property:

Dim chatitemobj As ChatItems

Set chatitemobj = New ChatItems
chatitemobj.AssociatedType = "Query"
chatitemobj.Item("SubjectOp") = "Contains"
chatitemobj.Item("Subject") = "real estate"
MsChatPr1.ListChannels chatitemobj
Set chatitemobj = Nothing

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