ListUsers Method

Objects

ListUsers Method

Description

Lists users on the server.

Syntax

object.ListUsers UserQueryItems

Part Description

object Required. An object expression that evaluates to an MsChatPr control.
UserQueryItems Required. An object expression that evaluates to a ChatItems object. Restricts the user listing to a subset of users. The following table lists the item names that can be used to construct the ChatItems object.

IRC/IRCX IRCX

protocols protocol only

Channels IPAddress

Mask IPAddressOp

MaskOp

Nickname

NicknameOp

Remarks

The caller can set criteria on the user's nickname, IP address, or channel. Also, when using the Mask and optionally the MaskOp item names, the user can list the users for which the nickname, IP address, server name, real name, or channel name matches the mask given.
When using the Mask and optionally the MaskOp item names, the call maps to a WHO command; otherwise, it maps to a WHOIS command.
A successful ListUsers call results in a suite of events. First, an OnBeginEnumeration event is fired to mark the beginning of the user listing. Next, one OnUserProperty event occurs for each user listed, where UserItems exposes all the known user properties. Finally, an OnEndEnumeration event is fired to mark the end of the user listing.

Examples

1. List all users on the server:

Dim chatitemobj As ChatItems

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

(On an IRC server this call maps to a WHO command. On an IRCX server it maps to a WHOIS command.)

2. On an IRCX server, list all users with an IP address that finishes with ".edu":

Dim chatitemobj As ChatItems

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

3. On an IRCX server, list all users with an IP address that contains "microsoft":

Dim chatitemobj As ChatItems

Set chatitemobj = New ChatItems
chatitemobj.AssociatedType = "Query"
chatitemobj.Item("IPAddressOp") = "Contains"
chatitemobj.Item("IPAddress") = "microsoft"
MsChatPr1.ListUsers chatitemobj
Set chatitemobj = Nothing

4. On an IRCX server, list all users with a nickname that contains "joe":

Dim chatitemobj As ChatItems

Set chatitemobj = New ChatItems
chatitemobj.AssociatedType = "Query"
chatitemobj.Item("NicknameOp") = "Contains"
chatitemobj.Item("Nickname") = "joe"
MsChatPr1.ListUsers chatitemobj
Set chatitemobj = Nothing

5. On an IRCX server, list all users in the channel "#newbies":

Dim chatitemobj As ChatItems

Set chatitemobj = New ChatItems
chatitemobj.AssociatedType = "Query"
chatitemobj.Item("Channels") = "#newbies"
MsChatPr1.ListUsers chatitemobj
Set chatitemobj = Nothing

6. On an IRCX server, list all users for which the nickname, IP address, server name, or real name contains "nath":

Dim chatitemobj As ChatItems

Set chatitemobj = New ChatItems
chatitemobj.AssociatedType = "Query"
chatitemobj.Item("MaskOp") = "Contains"
chatitemobj.Item("Mask") = "nath"
MsChatPr1.ListUsers chatitemobj
Set chatitemobj = Nothing

7. On an IRCX server, list all users for which the nickname, IP address, server name, or real name starts with "R&#-23;":

Dim chatitemobj As ChatItems

Set chatitemobj = New ChatItems
chatitemobj.AssociatedType = "Query"
chatitemobj.Item("MaskOp") = "StartsWith"
chatitemobj.Item("Mask") = "R&#-23;"
MsChatPr1.ListUsers chatitemobj
Set chatitemobj = Nothing

Login Method

Description

Logs a user onto the chat server.

Syntax

object.Login ServerName, Nickname[, UserName][, RealName][, Password][, SecurityPackages]

Part Description

object Required. An object expression that evaluates to an MsChatPr control.
ServerName Required. A string expression that contains the server Name. Can optionally include the port number.
Nickname Required. A string expression containing the user Nickname. Must be a valid IRC/IRCX user Nickname.
UserName Optional. A string expression that contains the UserName. If empty or missing, the control uses the Microsoft® Windows® login name as the UserName.
RealName Optional. A string expression containing the user's RealName. Can be empty or missing, in which case the Username is used as the RealName.
Password Optional. A string expression containing the user's password. If empty or missing, no password is used to log in to the server.
SecurityPackages Optional. A string expression that contains the name of the security package.
If empty or missing, the first authentication package provided by the server is used. If the server doesn't provide an authentication package, an anonymous login is tried.
The SecurityPackages parameter is a list of authentication packages that are successively tried during login. The packages must be separated by a semicolon and can include the ANON (not case sensitive) keyword for anonymous logins.
IRC servers do not implement user authentication; all logins are anonymous.

Remarks

The Login method can be called at two different stages—when the control is in the csDisconnected state, or after calling the Connect method and the control is in the csConnected state.
In this last case the ServerName and optional port number given in Login have to be the same as in the Connect call. After reaching the csConnected state, the csLogging and csLogged states are achieved.

Examples

1. Use Connect and Login:

MsChatPr1.Connect "comicsrv1.microsoft.com"
MsChatPr1.Login "comicsrv1.microsoft.com", "JB",_
"JamesB", ,MsChatPr1.SecurityPackages

2. Use Login alone:

MsChatPr1.Login "irc.mtv.com", "JB007", "JamesB", "James Bond", ,"ANON"

MsChatPr1.Login "irc.univ-lyon1.fr", "Arthur"

MsChatPr1.Login "chat.msn.com", "Norbert", , , ,"DPA;NTLM;ANON"

QueryChannelProperty Method

Description

Asynchronously accesses a channel property.

Syntax

object.QueryChannelProperty ChannelPropertyName[, ChannelName]

Part Description

object Required. An object expression that evaluates to an MsChatPr control.
ChannelPropertyName Required. A string that contains one of the valid values shown in the following table.

IRCX IRC/IRCX

protocol only protocols

Account BannedList

ClientData Keyword

ClientGuid MaxMemberCount

CreationTime MemberCount

HostKey Modes

Lag Name

Language Topic

ObjectId

OnJoin

OnPart

OwnerKey

Rating

ServicePath

Subject

ChannelName Optional. A string that contains the channel Name. This parameter 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.

Remarks

A successful QueryChannelProperty call results in an OnChannelProperty event in which the ChannelItems parameter exposes all the known channel properties.

Example

'Specifies the name of an existing server channel
MsChatPr1.QueryChannelProperty "Rating", "#MyRoom" 

'There is exactly one channel open
MsChatPr1.QueryChannelProperty "Modes"

QueryServerProperty Method

Description

Asynchronously accesses a server property.

Syntax

object.QueryServerProperty ServerPropertyName

Part Description

object Required. An object expression that evaluates to an MsChatPr control.
ServerPropertyName Required. A string containing one of the following valid server property name values.

AnonymousAllowed
ChannelCount
IgnoredUsers
Info
MaxMessageLength
Name
NetInvisibleCount
NetServerCount
NetUserCount
NodeServerCount
NodeUserCount
SecurityPackages
SysopCount
UnknownConnectionCount

Remarks

A successful QueryServerProperty call results in an OnServerProperty event, in which ServerItems exposes the known server properties.
The connection state must be at least csConnected to access the AnonymousAllowed, IgnoredUsers, MaxMessageLength, Name, and SecurityPackages properties. The state must be at least csLogged to access all other server properties.

Example

MsChatPr1.QueryServerProperty "Info"
MsChatPr1.QueryServerProperty "SysopCount"

QueryUserProperty Method

Description

Asynchronously accesses a user property.

Syntax

object.QueryUserProperty UserPropertyName[, Nickname]

Part Description

object Required. An object expression that evaluates to an MsChatPr control.
UserPropertyName Required. A string expression. Must be one of the following valid user property name values.

Away
Channels
HostInChannels
Identity
IdleTime
IPAddress
Modes
Nickname
OwnerOfChannels
RealName
ServerInfo
ServerName
SignOnTime
UserName
VoiceInChannel

Nickname Optional. A string expression. Can be omitted or empty, in which case the call concerns the control user. If used, the Nickname must be a current server user.

Remarks

A successful QueryUserProperty call results in an OnUserProperty event where UserItems exposes all the known user properties.

Examples

'UserPropertyName and Nickname
MsChatPr1.QueryUserProperty "Away", "Mila" 

'UserPropertyName only
MsChatPr1.QueryUserProperty "SignOnTime"

SendInvitation Method

Description

Invites a user to a channel.

Syntax

object.SendInvitation Nickname[, ChannelName]

Part Description

object Required. An object expression that evaluates to an MsChatPr control.
Nickname Required. A string expression containing the Nickname of an existing user on the server.
ChannelName Optional. A variant that does not need to be an existing channel on the server. If the ChannelName parameter is not specified or is empty, there must be exactly one open channel in the collection, and the user is invited to that channel.

Remarks

The invited user will get an OnInvitation event as notification of the invitation.

Examples

'ChannelName is specified
MsChatPr1.SendInvitation "Momo", "#MyRoom"

'There is exactly one open channel in the collection
MsChatPr1.SendInvitation "Mila"

SendPrivateMessage Method

Description

Sends a private text or data message to one or several users.

Syntax

object.SendPrivateMessage PrivateMessageType, Message, RecipientNicknames[, DataMessageTag]

Part Description

object Required. An object expression that evaluates to an MsChatPr control.
PrivateMessageType Required. A long value that is a combination of some of the enumPrivateMessageType enumeration values. The values that can be used are:

pmtNormal &H0.
pmtNotice &H1.
pmtData &H2.
pmtDataRequest &H4.
pmtDataReply &H8.
pmtDataRaw &H10.
pmtVersion &H40.
pmtLagTime &H80.
pmtLocalTime &H100.
pmtAction &H200.
pmtSound &H400.
pmtCTCP &H800.

Except for pmtNormal, all the above values are mutually exclusive.
The valid PrivateMessageType values are:

pmtNormal
pmtNotice
pmtData
pmtDataRequest
pmtDataReply
pmtData + pmtDataRaw
pmtDataRequest + pmtDataRaw
pmtDataReply + pmtDataRaw
pmtVersion + pmtNormal
pmtLagTime + pmtNormal
pmtLocalTime + pmtNormal
pmtAction + pmtNormal
pmtSound + pmtNormal
pmtCTCP + pmtNormal
pmtVersion + pmtNotice
pmtLagTime + pmtNotice
pmtLocalTime + pmtNotice
pmtAction + pmtNotice
pmtSound + pmtNotice
pmtCTCP + pmtNotice

Message Required. A variant that can be a string, a number, an array of strings, an array of numbers, or an array of variants that can be strings and numbers. The variant types allowed for these numbers are:

VT_UI1
VT_I2
VT_I4
VT_R4
VT_R8
VT_BOOL
VT_ERROR
VT_CY
VT_DATE

Message is the actual message to send.
RecipientNicknames Required. A variant that can be a string, an array of strings, or an array of variants that are strings that represent the recipients' nicknames.
DataMessageTag Optional. This variant will be a non-empty string when sending data (that is, the pmtData, pmtDataRequest, or pmtDataReply flag is set). This parameter must be empty or missing in all other cases.

Remarks

When sending data and the pmtDataRaw flag is not set, the control packages the Message parameter into an array of bytes and uses an internal header to tell the recipients that the message comes from an MsChatPr control. However, when the pmtDataRaw flag is also set, the Message parameter can only be a postprocessed string, a byte, an array of bytes, or an array of variants that are bytes. A postprocessed string is a string that was modified using the regular conversion scheme.

Character Becomes string

'\0' "\0"

'\' "\\"

'\n' "\n"

'\r' "\r"

'\t' "\t"

' ' "\b"

',' "\c"

When sending raw data, the control simply converts the Message parameter into a postprocessed string without using an internal header. This way all clients can handle the data message.

Examples

1. Send a regular string to a user:

MsChatPr1.SendPrivateMessage pmtNormal, "Hi there!", "Mila"

2. Send a notice to a user:

MsChatPr1.SendPrivateMessage pmtNotice, "Bye now!", "Zorg"

3. Request version information:

MsChatPr1.SendPrivateMessage pmtVersion, " ", "Mila"

4. Send version information:

MsChatPr1.SendPrivateMessage pmtVersion,"MsChatPr ActiveX Control V2.0 
    used in VB 5.0 Application Chat-oh", "Mila"

5. Request lag time:

MsChatPr1.SendPrivateMessage pmtLagTime, CStr(Timer), "Mila"

6. Request local time:

MsChatPr1.SendPrivateMessage pmtLocalTime, " ", "Mila"

7. Send an action to a user (CTCP action):

MsChatPr1.SendPrivateMessage pmtAction, "is eating couscous....", "Kimmy"

8. Send a sound to a user (CTCP sound):

MsChatPr1.SendPrivateMessage pmtSound, "couscous.wav Isn't that cool?", "Kimmy"

9. Send a CTCP message to a user:

MsChatPr1.SendPrivateMessage pmtCTCP, "FINGER", "Mila"

10. Send text to several users:

Dim strRecipients(1 To 3) As String

strRecipients(1) = "Charlotte"
strRecipients(2) = "Zorg"
strRecipients(3) = "Arthur"
MsChatPr1.SendPrivateMessage pmtNormal, "I'm a cook too...", strRecipients	
'or
Dim vRecipients(1 To 3) As Variant

vRecipients(1) = "Charlotte"
vRecipients(2) = "Zorg"
vRecipients(3) = "Arthur"
MsChatPr1.SendPrivateMessage pmtNormal, "I'm a cook too...", vRecipients

11. Send a string as data to a user:

MsChatPr1.SendPrivateMessage pmtData, "And a painter as well.", "Mila", "_FOO_"

12. Send a number to a user:

MsChatPr1.SendPrivateMessage pmtData, 1156, "Charlotte", "X"

13. Send an array of numbers to users:

Dim iValues(1 To 4) As Integer

iValues(1) = 10
iValues(2) = -22
iValues(3) = 123
iValues(4) = 0

Dim strRecipients(1 To 3) As String

strRecipients(1) = "Charlotte"
strRecipients(2) = "Zorg"
strRecipients(3) = "Arthur"

MsChatPr1.SendPrivateMessage pmtData, iValues, strRecipients, "COORD"
'or 
Dim vValues(1 To 4) As Variant

vValues(1) = 10
vValues(2) = -22
vValues(3) = 123
vValues(4) = 0

Dim vRecipients(1 To 3) As Variant

vRecipients(1) = "Charlotte"
vRecipients(2) = "Zorg"
vRecipients(3) = "Arthur"

MsChatPr1.SendPrivateMessage pmtData, vValues, vRecipients, "COORD"

14. Send an array of strings to a user:

Dim strValues(1 To 4) As String

strValues(1) = "Blue"
strValues(2) = "Green"
strValues(3) = "Red"
strValues(4) = "White"

MsChatPr1.SendPrivateMessage pmtData, strValues, "Prout", "COLORS"
'or 
Dim vValues(1 To 4) As Variant

vValues(1) = "Blue"
vValues(2) = "Green"
vValues(3) = "Red"
vValues(4) = "White"

MsChatPr1.SendPrivateMessage pmtData, vValues, "Prout", "COLORS"

15. Send an array of variants to a user:

Dim vValues(5 To 10) As Variant

vVariant(5) = Now
vVariant(6) = "Your turn to play...."
vVariant(7) = -10
vVariant(8) = 5
vVariant(9) = -12.689
vVariant(10) = 9876582146

MsChatPr1.SendPrivateMessage pmtData, vValues, "Zoulou", "TheHugeOne"

16. Send raw data to a user:

'A postprocessed string

MsChatPr1.SendPrivateMessage pmtData + pmtDataRaw, "dhe\rotk\\nsk\0k45v\0zxa\\v", 
    "Arthur", "ProcessedString"

'One byte

Dim byt As Byte
byt = 56
MsChatPr1.SendPrivateMessage pmtData + pmtDataRaw,byt, "Arthur", "OneByte"

'An array of bytes

Dim rgBytes(1 To 3) As Byte
rgBytes(1) = 15
rgBytes(2) = 98
rgBytes(3) = 2
MsChatPr1.SendPrivateMessage pmtData + pmtDataRaw,
    rgBytes, "Arthur", "ArrayOfBytes"

'An array of Variants that are bytes

Dim vByt(1 To 3) As Variant
vByt(1) = CByte(15)
vByt(2) = CByte(98)
vByt(3) = CByte(2)
MsChatPr1.SendPrivateMessage pmtData + pmtDataRaw, vByt, "Arthur", 
    "ArrayOfVariants"

SendProtocolMessage Method

Description

Sends a text message directly to the server.

Syntax

object.SendProtocolMessage TextMessage

Part Description

object Required. An object expression that evaluates to an MsChatPr control.
TextMessage Required. A string containing the text message.

Remarks

This method enables the user to use an IRC/IRCX command even if the command is not exposed by the MsChatPr control. The returned messages from the server might not be understood by the control and therefore be exposed to the user through the OnProtocolMessage event.

Examples

1. The user wants to become a system operator. This operation is not exposed by the protocol control:
MsChatPr1.SendProtocolMessage "OPER " + MsChatPr1.Nickname + " " + strPassword + vbCrLf
2. List servers linked to the server:
MsChatPr1.SendProtocolMessage "LINKS" + vbCrLf

SetAway Method

Description

Sets and resets the Away flag and away message.

Syntax

object.SetAway Away[, TextMessage]

Part Description

object Required. An object expression that evaluates to an MsChatPr control.
Away Required. A Boolean value used to indicate if the user is away. When a user is marked as being away, the away message is sent to any caller sending a private message to the away user. This automatic replay stops when the user resets the away flag.
TextMessage Optional. If the away flag is set to TRUE, this parameter is used to set the away text message. If the away flag is set to FALSE, this parameter is useless.

Examples

'Setting the Away flag
MsChatPr1.SetAway True, "Out with the dog, back at 4:00 p.m. local time."

'Resetting the Away flag
MsChatPr1.SetAway False

Part	Description
object	Required. An object expression that evaluates to an MsChatPr control.
ServerName	Required. A string expression that contains the server Name. Can optionally include the port number.
Nickname	Required. A string expression containing the user Nickname. Must be a valid IRC/IRCX user Nickname.
UserName	Optional. A string expression that contains the UserName. If empty or missing, the control uses the Microsoft® Windows® login name as the UserName.
RealName	Optional. A string expression containing the user's RealName. Can be empty or missing, in which case the Username is used as the RealName.
Password	Optional. A string expression containing the user's password. If empty or missing, no password is used to log in to the server.
SecurityPackages	Optional. A string expression that contains the name of the security package. If empty or missing, the first authentication package provided by the server is used. If the server doesn't provide an authentication package, an anonymous login is tried. The SecurityPackages parameter is a list of authentication packages that are successively tried during login. The packages must be separated by a semicolon and can include the ANON (not case sensitive) keyword for anonymous logins. IRC servers do not implement user authentication; all logins are anonymous.

Character	Becomes string
'\0'	"\0"
'\'	"\\"
'\n'	"\n"
'\r'	"\r"
'\t'	"\t"
' '	"\b"
','	"\c"

Objects