Component Library

The documentation in this section contains overview and reference material for various ActiveX™ Controls.

ActiveMovie Control

Microsoft ActiveX Data Objects

Microsoft Agent

Microsoft Chat Controls

NetMeeting API

Microsoft NetShow

Microsoft Remote Data Service

Tabular Data Control (TDC)


ActiveMovie Control

This section explains how to use the Microsoft® ActiveMovie™ Control, both in HTML pages and in Visual Basic applications. It contains a description of the control properties, methods, events, property sheet, and shortcut keys.

Introduction to DirectShow

About the DirectShow ActiveMovie Control

Using the ActiveMovie Control in HTML Pages

Using the ActiveMovie Control in Visual Basic

Control Properties

Control Methods

Control Events

Control Property Sheet

Control Shortcut Keys

Introduction to DirectShow

Microsoft® DirectShow™ is an extensible media architecture that delivers high-quality audio and video playback from the Internet or an intranet. DirectShow supports the most popular media types, including MPEG audio and video, AVI video, WAV audio, MIDI audio, and Apple® QuickTime® video. You can access the DirectShow-supported media types quickly and easily by using the Microsoft ActiveMovie™ Control.

The DirectShow architecture defines how applications can control and process time-stamped multimedia data using modular components called filters connected in a configuration called a filter graph. A complete filter graph consists of a number of filters, assembled in a logical progression from the data source to the media renderer or renderers.

Applications assemble the filter graph and control how data moves through it by accessing the filter graph manager through programming interfaces, as shown in the following illustration.

Diagram of how information moves between DirectShow and an application

For example, the Microsoft MPEG filter graph uses the following filters.

  • A source filter to read the data off the disk
  • A splitter transform filter to separate the video and audio
  • A video transform filter to decompress the video data
  • A video rendering filter to display the data on the screen
  • An audio transform filter to decompress the audio data
  • An audio rendering filter to send the audio data to the sound card

Default filter graphs are configured for you when you install the DirectShow software on your computer. You can also install additional filters and create your own filter graphs. For more information about creating and managing filter graphs, see Filter Graph Manager and Filter Graphs in the DirectShow SDK documentation.

About the DirectShow ActiveMovie Control

You can use the DirectShow ActiveMovie Control to quickly add support for multimedia to your applications. DirectShow supports the many media types, including MPEG audio and video, AVI video, WAV audio, MIDI audio, and Apple® QuickTime® video. The DirectShow SDK provides samples and examples that illustrate how to write programs that use the control with either Microsoft® Visual Basic® or Microsoft Visual C++®.

The ActiveMovie Control represents an easy-to-use programming interface that lets you manage multimedia using the control's properties, methods, and events. The control handles all video and audio rendering for you, which simplifies your programming tasks and makes it easy to add support for multimedia to your application. In addition to the ActiveMovie Control, you can use the DirectShow Component Object Model (COM) interfaces. (See Summary of DirectShow COM Interfaces in the DirectShow SDK documentation.)

Using the ActiveMovie Control in HTML Pages

Files on a Web page are referenced using URL names and various protocols, such as HTTP, file, FTP, or Gopher. These names can be either explicit or relative.

Following are two examples of explicit references. The first example uses the HTTP protocol to access the file. The second uses a network path and file name.

"http://directshow/samples/web/RoadRun.avi"

"file://directshow/samples/web/RoadRun.avi"

Here is an example of a relative reference:

"/samples/web/RoadRun.avi"

In the examples in this article, you can assume that either relative or explicit file names will work and any protocol for accessing these file names will also work.

Contents of this article:

  • Invoking Playback on HTML Pages
  • Using the OBJECT Tag
  • Using the OBJECT Tag with the CODEBASE Attribute
  • Using the EMBED Tag
  • Using the IMG tag with the DYNSRC= Attribute
  • Using the A Tag with the HREF Attribute
  • How Progressive Downloading Works
  • Setting ActiveMovie Control Properties on a Web Page

Invoking Playback on HTML Pages

You can play files in one of two ways: either embedded in a Web page, or externally in a window displayed outside or on top of the page. There are four ways of playing back media using HTML tags. Three of these result in embedded playback:

  • OBJECT
  • EMBED
  • IMG DYNSRC=

The fourth means of implementing playback results in an external window:

  • A HREF

Although not restricted to playback, you can use an attribute of the OBJECT tag to automatically download a file that contains required components for playback.

  • OBJECT CODEBASE

The following examples show how you use these tags to reference the file, but do not show all possible properties and attributes (width, height, color, and so on) that could be specified as well. See Setting ActiveMovie Control Properties on a Web Page for more information.

Using the OBJECT Tag

When you use the OBJECT tag, you must explicitly specify the class identifier (CLSID) for the playback control, as shown in the following example.

<OBJECT CLASSID="CLSID:05589FA1-C356-11CE-BF01-00AA0055595A">
<PARAM NAME="FileName" VALUE="http://www.microsoft.com//directshow/samples/web/RoadRun.avi">
</OBJECT>

The preceding CLSID is that of the ActiveMovie Control. The application loads the control and passes it the file name. The control parses the file name and downloads and plays the file. If the protocol is "file," the control instantiates the File Source (async) filter to play back the file. If the protocol is "http," the control instantiates the File Source (URL) filter instead. See the DirectShow SDK documentation for more information on these filters.

Using this tag, you can play back certain media types using "progressive downloading," which allows the user to play back the downloaded portion of the file as the data is downloading. See How Progressive Downloading Works for more information.

Using this tag along with the CODEBASE attribute, you can download components required for playback. See Using the OBJECT Tag with the CODEBASE Attribute for more information.

Using the OBJECT Tag with the CODEBASE Attribute

As the author of a Web page, you might find that using components such as specialized DirectShow filters can enhance playback of your media files on the user's machine. However, if the necessary components aren't already installed on the user's computer, you need a method to install those components. Internet Explorer supports using the CODEBASE attribute of the OBJECT tag for automatic file download, and cabinet (.cab) files for automatic installation. See http://www.microsoft.com/workshop/prog/cab/default.htm for information about the Cabinet SDK and .cab files.

The CODEBASE attribute works in conjunction with the OBJECT tag. See Using the OBJECT Tag for another example that uses the OBJECT tag.

An example of filter download using the CODEBASE attribute and a .cab file follows:

<OBJECT ID=GargleFilter1
CLASSID="CLSID:d616f350-d622-11ce-aac5-0020af0b99a3"
CODEBASE="http://directshow/samples/gargle.cab">
</OBJECT>

The preceding class identifier (CLSID) is the ID of the Gargle filter, which applies a "gargle" sound effect to a sound file. Internet Explorer checks the target computer's registry for the specified CLSID. If the specified CLSID is not present (indicating the filter is not installed on the machine), the browser attempts to find the file (Gargle.cab) at the site specified by the CODEBASE attribute and download it. Once downloaded, the .cab file provides the information to automatically install the filter.

Note: The .cab file must have been properly constructed for automatic installation to work. The .cab must include the filter (Gargle.ax in this case) and an .inf file that contains installation information. The .inf file should handle copying each filter to a specific directory (such as the Windows® System directory) on the user's computer and properly registering each filter. See the Platform SDK for information about .inf files.

Using the EMBED Tag

Netscape introduced this tag for embedding source. The following example uses this tag.

<EMBED autostart="FALSE" loop="FALSE" SRC="http://directshow/samples/web/RoadRun.avi">

This tag works identically to the OBJECT tag, except that you don't need to specify the CLSID. Internally, DirectShow examines the HKCR/MIME/Database/Content Type registry entries, retrieves the appropriate CLSID (DirectShow automatically registers all compatible data types at install time), and launches the control with that media type.

Using the IMG tag with the DYNSRC= Attribute

Internet Explorer can use the DYNSRC= attribute to play back audio-video interleaved (AVI) files. You can use this playback mechanism, but it is preferable to use the OBJECT tag. The following example demonstrates this HTML tag.

<IMG start=1 loop=0 DYNSRC="http://directshow/samples/web/RoadRun.avi">

Using the A Tag with the HREF Attribute

To play back a movie in an external movie, use the A tag with the HREF attribute. An example of this follows:

<A HREF="http://directshow/samples/web/dwad.cinepack.avi">AVI_CINEPACK</A>

The parsing steps that Internet Explorer 3.0 (or later) goes through are similar to the "EMBED SRC tag" case, in that it gets the file extension, maps it to a content type and looks in the HKCR/MIME/Database/Content Type area of the registry to get a CLSID to invoke. However, in this case the control plays in an external window. The ActiveMovie Control is in control of downloading the file.

How Progressive Downloading Works

The following series of steps describes what happens during progressive downloading.

  1. As soon as possible after activation, the ActiveMovie Control displays the first frame in the file (for movies). The filter graph remains in a paused state.
  2. The control does not start to play until it determines that it has enough data to play uninterrupted while the remaining amount downloads. At this time, playback starts and downloading will continue.
  3. The user can click the Play button during this time. In this case, the control will play until the play cursor reaches the end of the current amount downloaded and will automatically transition from the running state to the paused state.
  4. The download of the file will not stop if the user clicks Stop. The user can stop the download by closing the control.
  5. For most AVI or QuickTime files, you can't start playback until DirectShow has read the entire file (because the indexes are at the end of the file). However, the download bar is displayed to show how much of the file has been downloaded. The Play control button remains unavailable until the control downloads the file completely.

Setting ActiveMovie Control Properties on a Web Page

You can set any ActiveMovie Control property by using the PARAM tag inside an OBJECT container. For Boolean values, –1 is TRUE and 0 is FALSE. All other values are set as they would be in the Microsoft® Visual Basic® design environment.

The following example demonstrates playing a movie with most controls shown. If you have a video file and you want to try this, you can copy and paste this code onto your Web page and modify the parameters as you want. If you do this, be sure to change the movie's file name, perhaps using a relative path and file protocol (for example, PARAM NAME="FileName" VALUE="file://c:\mymovie.mpg") to play the movie from your hard drive.

<HTML>
<HEAD>
<TITLE>ActiveMovie Embedded MPG Object Test Page</TITLE>
</HEAD>
<BODY>
Scene from Stargate (MPG File)
<OBJECT ID="ActiveMovie1" WIDTH=357 HEIGHT=322
CLASSID="CLSID:05589FA1-C356-11CE-BF01-00AA0055595A">
<PARAM NAME="Version" VALUE="1">
<PARAM NAME="EnableContextMenu" VALUE="-1">
<PARAM NAME="ShowDisplay" VALUE="-1">
<PARAM NAME="ShowControls" VALUE="-1">
<PARAM NAME="ShowPositionControls" VALUE="0">
<PARAM NAME="ShowSelectionControls" VALUE="0">
<PARAM NAME="EnablePositionControls" VALUE="-1">
<PARAM NAME="EnableSelectionControls" VALUE="-1">
<PARAM NAME="ShowTracker" VALUE="-1">
<PARAM NAME="EnableTracker" VALUE="-1">
<PARAM NAME="AllowHideDisplay" VALUE="-1">
<PARAM NAME="AllowHideControls" VALUE="-1">
<PARAM NAME="MovieWindowSize" VALUE="0">
<PARAM NAME="FullScreenMode" VALUE="0">
<PARAM NAME="MovieWindowWidth" VALUE="353">
<PARAM NAME="MovieWindowHeight" VALUE="318">
<PARAM NAME="AutoStart" VALUE="0">
<PARAM NAME="AutoRewind" VALUE="-1">
<PARAM NAME="PlayCount" VALUE="1">
<PARAM NAME="SelectionStart" VALUE="0">
<PARAM NAME="SelectionEnd" VALUE="48.5151388">
<PARAM NAME="Appearance" VALUE="1">
<PARAM NAME="BorderStyle" VALUE="1">
<PARAM NAME="FileName" VALUE="http://DirectShow/samples/web/stargate1.mpg">
<PARAM NAME="DisplayMode" VALUE="0">
<PARAM NAME="AllowChangeDisplayMode" VALUE="-1">
<PARAM NAME="DisplayForeColor" VALUE="16777215">
<PARAM NAME="DisplayBackColor" VALUE="0">
</OBJECT>
</BODY>

Using the ActiveMovie Control in Visual Basic

This article describes how Microsoft® Visual Basic® applications can use the ActiveMovie Control. The ActiveMovie Control is a high-level interface that meets the needs of most multimedia application developers. Additional lower-level interfaces are also available to Visual Basic programmers.

Contents of this article:

  • Quick Start: Insert and Use the ActiveMovie Control
  • The Visual Basic Ocxvb01 Sample
  • Opening and Running DirectShow Source Files
  • Managing the User Interface of the ActiveMovie Control
  • Monitoring ActiveMovie Control Events

Quick Start: Insert and Use the ActiveMovie Control

This section describes how to insert the ActiveMovie Control and use it in a Visual Basic application. It is a simple example to get you started, and implements only playing and stopping a movie.

Follow these steps to insert the ActiveMovie Control into a Visual Basic form and play a movie:

  1. Install Internet Explorer to install the ActiveMovie Control.
  2. Open a project or create a new project in Visual Basic.
  3. Choose Components from the Projects menu. Choose the Controls tab. If the ActiveMovie Control does not appear in the list of Controls, click the Browse button. In the Add ActiveX Control dialog box that appears, navigate to the directory containing the control (by default, the \Windows\System or \Winnt\System32 directory). Double-click the Amovie.ocx file to add the ActiveMovie Control to the Controls list.
  4. Add the ActiveMovie Control to the Visual Basic toolbox by selecting the check box next to Microsoft ActiveMovie Control in the Controls list.
  5. Add the ActiveMovie Control to your form and size the control to the screen size you want for your movie. (Click the control in the Toolbox, and then draw its size on the form.)
  6. In the Properties list for the ActiveMovie Control, initialize the FileName property to the movie file you want to play. The FileName property should contain the full path. For example:
    c:\movies\mymovie.avi
  7. Set the ShowControls and ShowDisplay properties to FALSE.
  8. Add code to start and stop the movie to two events the ActiveMovie Control supports. For example:
    Private Sub ActiveMovie1_Click()
    ActiveMovie1.Run
End Sub
Private Sub ActiveMovie1_KeyPress(KeyAscii As Integer)
     ActiveMovie1.Stop
End Sub
  9. Compile the application.
  10. Run the application. In this example, click anywhere on the movie screen to start the movie. Press any key to stop the movie.

Follow these steps to use the ActiveMovie Control to play a movie controlled by Visual Basic controls:

  1. Follow steps 1-6 as shown earlier in this section.
  2. Add Visual Basic controls (such as a CommandButton or ListBox) to your form to play and stop the movie.
  3. Add code to play and stop the movie. For example:
    Private Sub Command1_Click()
ActiveMovie1.Run
End Sub
Private Sub Command2_Click()
ActiveMovie1.Stop
End Sub
  4. Compile the application.
  5. Run the application. In this example, Click the Command1 button to start the movie. Click the Command2 button to stop the movie.

The Visual Basic Ocxvb01 Sample

This section describes some of the features of the DirectShow Visual Basic sample application called Ocxvb01 in the VB\OCX directory of the DirectShow samples. The ActiveMovie Control manages most of the details of the display and playback of DirectShow files, while giving the Visual Basic developer control over the image size, playback rate, volume, balance, and position. With the control, the developer can manage a variety of standard user interface controls, such as rewind and fast forward, and a trackbar control to set positions within the media file.

The Visual Basic sample application Ocxvb01 consists of two forms: the main control form frmMain (Ocxvb01.frm) and the display form frmViewer (Viewer.frm).

The frmMain form's menu commands call ActiveMovie Control methods to run, pause, and stop multimedia playback, set and retrieve the control's properties, and enable and disable different parts of the user interface.

The frmMain form contains two command buttons that change the CurrentPosition property of the IMediaPosition object; you can use these buttons to move forward or backward through the multimedia source file, if the multimedia source type supports this functionality. The frmMain form's trackbar control sets the Playback property; its valid range is 0.5 to 1.5. This value is used as a multiplier; 1.0 is the authored speed, so 0.5 is half the authored speed and 2.0 is twice the authored speed. You can set this property to values outside this range, but the audio portion tends to become incomprehensible.

The main control form also contains option buttons that set the display configuration to half size, full size (default), and double size. The main control form appears as shown in the following illustration.

Main control form

The display form, frmViewer, contains the ActiveMovie Control that is displayed when the DirectShow multimedia source file is active or when the source is playing. The application resizes the display form to correspond to the selected source. The display form, with all ActiveMovie Control user interface elements visible and enabled, appears as shown in the following illustration.

Display form with all ActiveMovie Control elements visible and enabled

The following sections describe how to use some of the properties, methods, and events.

Opening and Running DirectShow Source Files

To load and play a DirectShow file, set the ActiveMovie Control's FileName property. Depending on your application's requirements, you can play the file from your code by using methods like Run and Stop, or you can let the user interact with the user interface elements offered by the control.

The FileName property specifies the name of the multimedia source file. When you set the FileName property, several other properties are updated to indicate characteristics of that source file.

Once the FileName property contains a valid file name, you can call the control's Run method to play the multimedia file. Or, you can enable the control buttons on the display form and let the user play the file.

The sample application contains an Open command on the File menu that sets the value of the FileName property. It invokes the File Open common dialog box to obtain a file name:

   Private Sub mnu_File_Open_Click()

      CommonDialog1.Filter = "All files (*.*)|*.*|DirectShow files
(*.mpg;*.mpa;*.mpv;*.mov;*.mpeg;*.enc;*.m1v;*.mp2)|*.mpg;*.mpa;*.mpv;*.mov;*.mpeg;*.enc;*.m1v;*.
mp2|Audio files (.wav)|*.wav|Video for Windows files
(.avi)|*.avi"
      CommonDialog1.Flags = 4 'Hide read-only check box
      CommonDialog1.ShowOpen
      ' only set the property if the user selected a filename from the common dialog
      If CommonDialog1.filename <> "" Then
         frmViewer.ActiveMovie1.filename = CommonDialog1.filename
         g_FileOpened = True
         g_FileExtension = Right$(CommonDialog1.filename, Len(CommonDialog1.filename) -
InStr(CommonDialog1.filename, "."))
      Else
         GoTo err_FileOpen
      End If
      Call ResizeViewer
      ...

First, the subroutine prepares the common dialog box to display only movie files. After the common dialog box returns, the subroutine checks to determine if a file name was returned.

If a file name was returned, the subroutine sets the FileName property of the ActiveMovie Control, in addition to some other global variables: gFileOpened to determine whether or not a file has been opened, and gFileExtension to determine the type of the file.

Finally, the subroutine calls the ResizeViewer subroutine to make the dimensions of the viewer form match those of the DirectShow file. The dimensions of the Visual Basic form are expressed in twips, while the dimensions of the multimedia source are expressed in pixels. The ResizeViewer subroutine considers these differences to size the form by using the form's ScaleHeight and ScaleWidth properties:

' Resize form to dimensions of ActiveMovie Control + nonclient region.
    With frmViewer
        .Visible = False
        .Height = .ActiveMovie1.Height + (.Height - .ScaleHeight)
        .Width = .ActiveMovie1.Width + (.Width - .ScaleWidth)
        .Visible = True
    End With

After the file is loaded successfully, you can play it by clicking Play on the control, or by using the Run method. The sample application provides a Run command on its File menu that calls the Run method:

   Private Sub mnu_File_Run_Click()

      If g_FileOpened = True Then
         frmViewer.ActiveMovie1.Run
         frmViewer.ZOrder 0
      End If

Managing the User Interface of the ActiveMovie Control

The display form of the sample application (Viewer.frm) contains the ActiveMovie Control. The following illustration shows the control with the status bar visible and the control bar hidden.

ActiveMovie Control with status bar visible and control bar hidden

You can use the ActiveMovie Control properties to show or hide and enable or disable user interface elements of the ActiveMovie Control. The sample application includes selected menu commands that enable you to individually control each of the user interface elements. The commands on the View menu enable you to control whether the element is visible. The commands on the Enable menu enable you to control whether the element is enabled.

When the sample application loads a new file, it resets the ActiveMovie Control properties to default values and initializes the values of these selected menu commands. This fragment is from the mnu_File_Open_Click procedure:

   With frmViewer.ActiveMovie1
      .EnablePositionControls = False              'Disable/Enable controls.
      .EnableSelectionControls = False
      .EnableTracker = False
      .ShowPositionControls = False                'Show/don't show controls.
      .ShowSelectionControls = False
      .ShowTracker = True
      mnu_Enable_PositionControls.Checked = False  'Check/uncheck menus to match
      mnu_Enable_SelectionControls.Checked = False 'controls.
      mnu_Enable_Tracker.Checked = False
      mnu_View_Tracker.Checked = True
      mnu_View_PositionControls.Checked = False
      mnu_View_SelectionControls.Checked = False
      ...
   End With

Many of the control elements have two properties associated with them: one to enable them and another to make them visible. To use the position controls, set both the EnablePositionControls and ShowPositionControls properties. The following illustration shows the display controls and all position controls with all elements of the user interface both visible and enabled.

Display form with all ActiveMovie Control elements visible and enabled

Monitoring ActiveMovie Control Events

The ActiveMovie Control automatically monitors certain events and calls event procedures accordingly. To handle one of these events, you provide only the event handling code. For example, the StateChange event indicates a change in the state of the multimedia source, such as the change from running to stopped, or the change from paused to running. To take some action when this event occurs, the application provides code as part of the control's StateChange event.

To demonstrate these event handlers, the sample application provides trivial code that increments a variable. The variable represents a count of the number of times the event has occurred. The current values for these counter variables are displayed at the bottom of the main form. The following example shows the code for the StateChange event.

   Private Sub ActiveMovie1_StateChange(ByVal oldState As Long, ByVal newState As Long)

      g_cStateChange = g_cStateChange + 1
      UpdateStatusBar

Each event procedure passes some informational parameters too. For the StateChange event, you can determine the previous state, in addition to the control's current state, by examining the oldState and newState parameters.


Control Properties

The ActiveMovie Control supports the following properties.
AllowChangeDisplayMode | Indicates whether or not the end-user can change the display mode at run time between seconds and frames.
AllowHideControls | Indicates whether or not the end-user can hide the control panel at run time.
AllowHideDisplay | Indicates whether or not the end-user can hide the display panel at run time.
Appearance | Specifies the appearance of the display panel's border.
AutoRewind | Indicates whether or not the multimedia stream should automatically return to the selection's starting point when it reaches the end of the selection.
AutoStart | Indicates whether or not to automatically start playing the multimedia stream.
Balance | Specifies the stereo balance.
BorderStyle | Specifies the control's border style.
CurrentPosition | Specifies the current position within the playback file, in seconds.
CurrentState | Specifies the playback file's current state: stopped, paused, or running.
DisplayBackColor | Specifies the display panel's background color.
DisplayForeColor | Specifies the display panel's foreground color.
DisplayMode | Indicates whether or not the display panel shows the current position in seconds or frames.
EnableContextMenu | Indicates whether or not to enable the shortcut menu.
Enabled | Specifies whether or not the control is enabled.
EnablePositionControls | Indicates whether or not to show the position buttons in the controls panel.
EnableSelectionControls | Indicates whether or not to show the selection buttons in the controls panel.
EnableTracker | Indicates whether or not to show the trackbar control in the controls panel.
FileName | Specifies the name of the source data file.
FilterGraph | Contains the IUnknown interface pointer to the current filter graph object.
FilterGraphDispatch | Contains the IDispatch interface pointer to the current filter graph object.
FullScreenMode | Expands the area of the playback panel to fill the entire screen.
MovieWindowSize | Specifies the size of the playback panel.
PlayCount | Specifies the number of times to play the multimedia stream.
Rate | Specifies the playback rate for the stream.
ReadyState | Specifies the state of readiness for this ActiveMovie Control, based on how completely the source file has loaded.
SelectionEnd | Specifies the ending position in this multimedia stream, in seconds, relative to the stream's beginning.
SelectionStart | Specifies the starting position in this multimedia stream, in seconds, relative to the stream's beginning.
ShowControls | Indicates whether or not the controls panel is visible.
ShowDisplay | Indicates whether or not the display panel is visible.
ShowPositionControls | Indicates whether or not the position controls are visible.
ShowSelectionControls | Indicates whether or not the selection controls are visible.
ShowTracker | Indicates whether or not the trackbar is visible.
Volume | Specifies the volume, in hundredths of decibels.

The ActiveMovie Control supports the following properties that are common to other controls: Appearance, BorderStyle, Enabled, and hWnd. For information about these properties, see the documentation for Visual Basic.


AllowChangeDisplayMode Property

Indicates whether the end-user can change the display mode at run time between time and frames.

Syntax

[form.]object.AllowChangeDisplayMode [ = { True | False } ]

Settings

True | (Default) The end-user can change the type of display at run time.
False | The end-user cannot change the type of display at run time.

Data Type

Boolean

Remarks

This property controls run-time access to the DisplayMode property, which specifies whether to show the multimedia file's current position in time or frames. If you set this property to True, the end-user can change how the control displays the current position by right-clicking the control window and choosing Time or Frames from the shortcut menu.

Run-time access: read-only. Design-time access: read/write.


AllowHideControls Property

Indicates whether the end-user can control the visibility of the controls panel at run time.

Syntax

[form.]object.AllowHideControls [ = { True | False } ]

Settings

True | (Default) The end-user can hide or show the controls panel.
False | The end-user cannot hide or show the controls panel.

Data Type

Boolean

Remarks

This property controls run-time access to the ShowControls property, which hides and displays the controls panel. If you set this property to True, the end-user can show or hide the controls panel by right-clicking the control window and choosing Controls from the shortcut menu.

Run-time access: read-only. Design-time access: read/write.


AllowHideDisplay Property

Indicates whether the end-user can hide the display panel at run time.

Syntax

[form.]object.AllowHideDisplay [ = { True | False } ]

Settings

True | (Default) The end-user can hide or show the display panel.
False | The end-user cannot hide or show the display panel.

Data Type

Boolean

Remarks

This property controls run time access to the ShowDisplay property, which hides and displays the display panel. If you set this property to True, the end-user can show or hide the display panel by right-clicking the control window and choosing Display from the shortcut menu.

Run-time access: read-only. Design-time access: read/write.


Appearance Property

Specifies the appearance of the display panel's border.

Syntax

[form.]object.Appearance [ = long ]

Settings

1 | (Default) The display panel has an inset border, which gives the illusion of depth. This value is the same as 3D.
0 | The display panel has no border. This value is the same as Flat.

Data Type

Long

Remarks

This property is identical to the standard Visual Basic Appearance property.

Run-time access: read-only. Design-time access: read/write.


AutoRewind Property

Indicates whether the multimedia stream should automatically return to the selection's starting point when it reaches the end of the selection.

Syntax

[form.]object.AutoRewind  [ = { True  | False  } ]

Settings

True | (Default) Reposition the multimedia stream to the start of the selection after playback stops.
False | Do not reposition the multimedia stream to the start of the selection after playback stops.

Data Type

Boolean

Remarks

If you set this property to True, DirectShow sets CurrentPosition to the position specified by SelectionStart when it reaches the position specified by SelectionEnd.

To retain the current position within the multimedia stream, set AutoRewind to False or use the Pause method.

Run-time access: read/write. Design-time access: read/write.

See Also

AutoStart


AutoStart Property

Indicates whether to automatically start playing the multimedia stream.

Syntax

[form.]object.AutoStart  [ = { True  | False  } ]

Settings

True | Automatically start playing the multimedia stream.
False | (Default) Do not automatically start the multimedia stream.

Data Type

Boolean

Remarks

If you set this property to False, you must make an explicit call to the Run method to play the stream.

Run-time access: read-only. Design-time access: read/write.

See Also

PlayCount


Balance Property

Specifies the stereo balance.

Syntax

[form.]object.Balance [ = long ]

Settings

long Numeric expression that specifies the balance value. The number ranges from –10,000 to 10,000 and defaults to 0.

Data Type

Long

Remarks

The value 0 indicates that the sound is balanced equally between the left and right speakers. A value of –10,000 indicates that all sound is going to the left speaker and 10,000 that all sound is going to the right speaker.

Run-time access: read/write. Design-time access: read/write.

See Also

Volume Property


BorderStyle Property

Specifies the control's border style.

Syntax

[form.]object.BorderStyle [ = long ]

Settings

0 | No border.
1 | (Default) Fixed, single-line border.

Data Type

Integer (Enumerated)

Remarks

Run-time access: read-only. Design-time access: read/write.


CurrentPosition Property

Specifies the current position within the multimedia stream, in seconds.

Syntax

[form.]object.CurrentPosition [ = double ]

Settings

double New position within the stream, in seconds.

Data Type

double

Remarks

The new value must be within the range specified by the SelectionStart and SelectionEnd properties.

The current position value displayed by the control's user interface can represent either seconds or frames. The DisplayMode property determines the units shown.

Setting the CurrentPosition property at run time is similar to a seek operation and changes the position to the specified point in the multimedia stream.

Run-time access: read/write. Design-time access: not applicable.


CurrentState Property

Describes the playback file's current state.

Syntax

[form.]object.CurrentState

Settings

Setting | Value | Description
amvStopped | 0 | The player is stopped.
amvPaused | 1 | The player is paused.
amvRunning | 2 | The player is playing the multimedia file.

Data Type

Long

Remarks

You cannot assign a value to this property. You can change it by calling the Stop, Run, or Pause method, and DirectShow notifies the application of the change by sending the StateChange event.

The amv settings are available only to C/C++ programmers; scripters and other programmers should use the numerical values.

Run-time access: read-only. Design-time access: not applicable.


DisplayBackColor Property

Specifies the display panel's background color.

Syntax

[form.]object.DisplayBackColor [ = color ]

Settings

Normal RGB colors | Colors specified by using the color palette or by using the Visual Basic RGB or QBColor functions in code.
System default colors | Colors specified by system color constants listed in the Object Browser's object library. The Windows® operating environment substitutes the user's choices as specified in the Control Panel settings.

Remarks

At design time, the default setting is black (0x0).

The valid range for a normal RGB color is 0 to 16,777,215 (&HFFFFFF). The high byte of a number in this range equals 0; the lower 3 bytes, from least to most significant byte, determine the amount of red, green, and blue, respectively. The red, green, and blue components are each represented by a number between 0 and 255 (&HFF). If the high byte is not 0, Visual Basic uses the system colors, as defined in the user's Control Panel settings and by constants listed in the Object Browser's object library.

Run-time access: read/write. Design-time access: read/write.

See Also

DisplayForeColor


DisplayForeColor Property

Specifies the display panel's foreground color.

Syntax

[form.]object.DisplayForeColor [ = color ]

Settings

Normal RGB colors | Colors specified by using the color palette or by using the Visual Basic RGB or QBColor functions in code.
System default colors | Colors specified by system color constants listed in the Object Browser's object library. The Windows operating environment substitutes the user's choices as specified in the Control Panel settings.

Remarks

At design time, the default setting is white (&HFFFFFF).

The valid range for a normal RGB color is 0 to 16,777,215 (&HFFFFFF). The high byte of a number in this range equals 0; the lower 3 bytes, from least to most significant byte, determine the amount of red, green, and blue, respectively. The red, green, and blue components are each represented by a number between 0 and 255 (&HFF). If the high byte is not 0, Visual Basic uses the system colors, as defined in the user's Control Panel settings and by constants listed in the Object Browser's object library.

Run-time access: read/write. Design-time access: read/write.

See Also

DisplayBackColor


DisplayMode Property

Indicates whether the display panel shows the current position in seconds or frames.

Syntax

[form.]object.DisplayMode [ = setting ]

Settings

0 | (Default) Display the current position in seconds.
1 | Display the current position in frames.

Data Type

Integer (Enumerated)

Remarks

Run-time access: read/write. Design-time access: read/write.

See Also

AllowHideDisplay, ShowDisplay


EnableContextMenu Property

Indicates whether to enable the control's shortcut menu.

Syntax

[form.]object.EnableContextMenu  [ = { True | False } ]

Settings

True | (Default) The shortcut menu is enabled.
False | The shortcut menu is disabled.

Data Type

Boolean

Remarks

The shortcut menu appears when the end-user right-clicks anywhere on the control.

Run-time access: read/write. Design-time access: read/write.

See Also

ShowDisplay


Enabled Property

Specifies whether the control is enabled.

Syntax

[form.]object.Enabled [ = setting ]

Settings

-1 | (Default) The control is enabled.
0 | The control is disabled.

Data Type

Integer (Enumerated)

Remarks

This property is identical to the standard Visual Basic Enabled property.

A disabled control remains visible (if it already was) and will continue to play, if it was already playing. When a control is disabled, none of the commands or menus respond to user input.

Disabling a control at design time is useful if you want to control the media stream from an external source, such as a custom group of controls on a Web page, instead of from the built-in controls panel.

Run-time access: read/write. Design-time access: read/write.


EnablePositionControls Property

Indicates whether or not to show the position buttons in the controls panel.

Syntax

[form.]object.EnablePositionControls  [ = { True | False } ]

Settings

True | (Default) The position controls are visible.
False | The position controls are not visible.

Data Type

Boolean

Remarks

Run-time access: read/write. Design-time access: read/write.

See Also

ShowPositionControls


EnableSelectionControls Property

Indicates whether or not to show the selection controls in the controls panel.

Syntax

[form.]object.EnableSelectionControls  [ = { True  | False  } ]

Settings

True | (Default) The selection controls are visible.
False | The selection controls are not visible.

Data Type

Boolean

Remarks

Run-time access: read/write. Design-time access: read/write.

See Also

ShowSelectionControls


EnableTracker Property

Indicates whether or not to show the trackbar control.

Syntax

[form.]object.EnableTracker [ = { True | False } ]

Settings

True | (Default) The trackbar is visible.
False | The trackbar is not visible.

Data Type

Boolean

Remarks

Run-time access: read/write. Design-time access: read/write.

See Also

ShowTracker


FileName Property

Specifies the name of the source data file.

Syntax

[form.]object.FileName  [ = string ]

Settings

string Name of the file that contains the multimedia stream.

Data Type

String

Remarks

The ActiveMovie Control asynchronously opens the file specified by this property at run time. This means that an application must receive the ReadyStateChange event with an amvInteractive or amvComplete value before attempting to call the Run method.

When designing an application using Microsoft® Visual Basic® that uses the ActiveMovie Control, you can choose the media source file at design time. After you add a control to the application, fill in the full path to the media file as the value for the FileName property in Properties. You can also double-click the "..." value in the uninitialized FileName property and its property page will appear. If you click the Browse button, you can pick the desired source file from the Open dialog box.

Run-time access: read/write. Design-time access: read/write.


FilterGraph Property

Contains the IUnknown interface pointer to the current filter graph object.

Syntax

[form.]object.FilterGraph [ = punk ]

Settings

punk IUnknown pointer for the filter graph object.

Data Type

Integer (IUnknown*)

Remarks

The filter graph represents a specific configuration of source, transform, and rendering filters. The filter graph is the complete set of software components needed to process a given multimedia stream within the DirectShow architecture.

You can set this property to change the current filter graph.

The IDispatch interface pointer for the filter graph object is contained in the FilterGraphDispatch property.

Run-time access: read/write. Design-time access: read-only.

See Also

IFilterGraph Interface in the DirectShow SDK documentation.


FilterGraphDispatch Property

Contains an IDispatch interface pointer to the current filter graph object.

Syntax

[form.]object.FilterGraphDispatch [ = pdisp ]

Settings

pdisp IDispatch pointer to the current filter graph object.

Data Type

Integer (IDispatch*)

Remarks

The filter graph represents a specific configuration of source, transform, and rendering filters. The filter graph represents the complete set of software components needed to process a given multimedia stream within the DirectShow architecture.

Run-time access: read-only. Design-time access: read-only.

See Also

FilterGraph


FullScreenMode Property

Expands the area of the playback panel to fill the entire screen.

Syntax

[form.]object.FullScreenMode [ = { True | False } ]

Settings

True | Use full-screen mode.
False | Do not use full-screen mode.

Data Type

Boolean

Remarks

Run-time access: read-only. Design-time access: read/write.

See Also

MovieWindowSize


MovieWindowSize Property

Specifies the size of the playback panel.

Syntax

[form.]object.MovieWindowSize [ = setting ]

Settings

Setting | Value | Description
amvOriginalSize | 0 | (Default) Uses the authored size.
amvDoubleOriginalSize | 1 | Increases the image projection size to twice the authored size.
amvOneSixteenthScreen | 2 | Projects the images onto an area the size of one-sixteenth of the screen.
amvOneFourthScreen | 3 | Projects the images onto an area the size of one-quarter of the screen.
amvOneHalfScreen | 4 | Projects the images onto an area the size of half of the screen.

Data Type

Long

Remarks

The amv settings are available only to C/C++ programmers; scripters and other programmers should use the numerical values.

Run-time access: read/write. Design-time access: read/write.


PlayCount Property

Specifies the number of times to play the multimedia stream.

Syntax

[form.]object.PlayCount [ = long ]

Settings

long Numeric expression that specifies the number of times to play the multimedia stream.

Data Type

Long

Remarks

If you set this property to zero, the control will play the multimedia stream repeatedly, restarting as soon as it reaches the end.

Run-time access: read/write. Design-time access: read/write.

See Also

AutoStart


Rate Property

Specifies the playback rate for the multimedia stream.

Syntax

[form.]object.Rate [ = double ]

Settings

double Numeric expression that represents the playback rate; 1.0 corresponds to the authored rate and is the default value.

Data Type

double

Remarks

This property acts as a multiplier value that allows you to play the stream at a faster or slower rate. The value 1.0 indicates the authored speed. Note that the audio track becomes difficult to understand at rates lower than 0.5 and higher than 1.5.

Run-time access: read/write. Design-time access: read/write.


ReadyState Property

Specifies the control's state of readiness.

Syntax

[form.]object.ReadyState

Settings

Setting | Value | Description
amvUninitialized | 1 | The FileName property has not been initialized.
amvLoading | 0 | The ActiveMovie Control is asynchronously loading a file.
amvInteractive | 3 | The control loaded a file, and has downloaded enough data to play the file, but has not yet received all data.
amvComplete | 4 | All data has been downloaded.

Data Type

Long

Remarks

The ActiveMovie Control changes this property at run time, and its value is passed as a parameter to the ReadyStateChange event. The run method will only work on the control after the ReadyState property has reached the amvInteractive or amvComplete state.

Run-time access: read-only. Design-time access: read-only.


SelectionEnd Property

Specifies the ending position in this multimedia stream, in seconds, relative to the stream's beginning.

Syntax

[form.]object.SelectionEnd [ = double ]

Settings

double Numeric expression that specifies the position in the multimedia stream that represents the end of the playback sequence.

Data Type

double

Remarks

The default value for SelectionEnd is the length of the multimedia stream; this value is not accessible until the file is loaded completely. When DirectShow sends the ReadyStateChange event with a value of Complete, you can access the value of this property.

Run-time access: read/write. Design-time access: none.

See Also

SelectionStart


SelectionStart Property

Specifies the starting position in this multimedia stream, in seconds, relative to the stream's beginning.

Syntax

[form.]object.SelectionStart [ = double ]

Settings

double Numeric expression that specifies the position within the multimedia stream that represents the beginning of the playback sequence.

Data Type

double

Remarks

The default value for SelectionStart is zero; this value is not accessible until the file is loaded completely. When DirectShow sends the ReadyStateChange event with a value of Complete, you can access the value of this property.

Run-time access: read/write. Design-time access: none.

See Also

SelectionEnd


ShowControls Property

Indicates whether or not the controls panel is visible.

Syntax

[form.]object.ShowControls [ = { True | False } ]

Settings

True | (Default) The controls panel is visible.
False | The controls panel is not visible.

Data Type

Boolean

Remarks

Run-time access: read/write. Design-time access: read/write.

See Also

ShowDisplay


ShowDisplay Property

Indicates whether or not the display panel is visible.

Syntax

[form.]object.ShowDisplay [ = { True | False } ]

Settings

True | (Default) The display panel is visible.
False | The display panel is not visible.

Data Type

Boolean

Remarks

Run-time access: read/write. Design-time access: read/write.

See Also

ShowControls


ShowPositionControls Property

Indicates whether the position controls are visible.

Syntax

[form.]object.ShowPositionControls [ = { True  | False  } ]

Settings

True | The position controls are visible.
False | (Default) The position controls are not visible.

Data Type

Boolean

Remarks

The position controls consist of four buttons: Previous, Rewind, Forward, and Next. Rewind and Forward move the media position rapidly backward and forward. If the current media position is after the position specified in SelectionStart, Previous sets the media position to the value of SelectionStart. If not, Previous sets the media position to the start of the data stream. If the current media position is before the position specified in SelectionStart, Next sets the media position to the value of SelectionStart. If not, Next sets the media position to the end of the data stream.

Run-time access: read/write. Design-time access: read/write.

See Also

EnablePositionControls


ShowSelectionControls Property

Indicates whether the selection controls are visible.

Syntax

[form.]object.ShowSelectionControls  [ = { True  | False  } ]

Settings

True | The selection controls are visible.
False | (Default) The selection controls are not visible.

Data Type

Boolean

Remarks

There are two selection buttons—Start Selection and End Selection. Start Selection sets the SelectionStart property to the current media position and End Selection sets the SelectionEnd property to the current media position. If you choose an invalid selection, such as an end time that is earlier than the start time, DirectShow automatically sets SelectionStart to the start of the data stream and SelectionEnd to the end.

Run-time access: read/write. Design-time access: read/write.

See Also

EnableSelectionControls


ShowTracker Property

Indicates whether or not the trackbar is visible.

Syntax

[form.]object.ShowTracker  [ = { True | False } ]

Settings

True | (Default) The trackbar is visible.
False | The trackbar is not visible.

Data Type

Boolean

Remarks

Run-time access: read/write. Design-time access: read/write.

See Also

EnableTracker


Volume Property

Specifies the volume, in hundredths of decibels.

Syntax

[form.]object.Volume [ = long ]

Settings

long Numeric expression that specifies the audio volume, in hundredths of decibels. The default value is zero.

Data Type

Long

Remarks

The value ranges from –10,000 to 0. The value 0 is full volume and –10,000 is no volume. Not all devices support 10,000 discrete steps of volume.

Run-time access: read/write. Design-time access: read/write.

See Also

Balance Property


Control Methods

The ActiveMovie Control supports the following methods.
AboutBox | Displays version and copyright information about the ActiveMovie Control.
IsSoundCardEnabled | Determines whether the computer's sound card is enabled.
Pause | Suspends a play operation without changing the current position.
Run | Starts a multimedia stream from the specified starting position or continues playing a paused stream.
Stop | Stops playback and resets the position as indicated by the AutoRewind and SelectionStart properties.

The ActiveMovie Control also supports several methods that are common to other controls: Drag, Move, SetFocus, ShowWhatsThis, and ZOrder.

For information about these methods, see documentation for Visual Basic.


AboutBox Method AboutBox Method *
  * Previous Topic: Control Methods
  * Next Topic: IsSoundCardEnabled Method

AboutBox Method

Displays version and copyright information about the ActiveMovie Control.

Syntax

object.AboutBox


IsSoundCardEnabled Method

Determines whether the computer has one or more sound cards enabled.

Syntax

object.IsSoundCardEnabled [ = { True | False } ]

Settings

True | Sound card is enabled.
False | No sound cards are enabled.

Data Type

Boolean

Remarks

Run-time access: read. Design-time access: read.


Pause Method

Suspends a play operation without changing the current position.

Syntax

object.Pause

Remarks

The Pause method pauses the multimedia stream at the current position. To continue playing the multimedia stream, use the Run method.

To stop the multimedia stream, use the Stop method.


Run Method

Starts a multimedia stream from the specified starting position or continues playing a paused stream.

Syntax

object.Run

Remarks

The Run method starts the multimedia stream at the starting position specified by the SelectionStart property. In the absence of other user or application input, the Run method continues playing the stream to the position specified by the SelectionEnd property.

The Run method is also used to resume playing a paused multimedia stream.

To pause playing, call the Pause method. To stop playing, call the Stop method.


Stop Method

Stops playback and resets the position as indicated by the AutoRewind and SelectionStart properties.

Syntax

object.Stop

Remarks

The Stop method changes the CurrentState property.

When the Stop method halts a play operation, you can reset the current position to the starting point for the multimedia stream, as indicated by the SelectionStart property. The AutoRewind property determines whether the position is reset to this starting position.

To halt a play operation without changing the current position, use the Pause method.

See Also

Run Method


Control Events

The ActiveMovie Control supports the following events.
DisplayModeChange | Indicates changes to the DisplayMode property.
Error | Indicates that an error occurred.
OpenComplete | Specifies the state of readiness for this ActiveMovie Control, based on how completely the source file has loaded.
PositionChange | Indicates changes to the current media position, such as when the user selects (or seeks to) a new media position.
ReadyStateChange | Indicates changes to the control's state of readiness.
StateChange | Indicates player state changes.
Timer | Handles timer events.

The ActiveMovie Control also supports several events common to other controls: Click, DblClick, KeyDown, KeyPress, KeyUp, MouseDown, MouseMove, and MouseUp. For information about these events, see the event documentation for Visual Basic.


DisplayModeChange Event

Indicates changes to the DisplayMode property, such as from full-screen to half. The current display mode appears in the DisplayMode property. State flags are listed under DisplayMode property.

Syntax

Private Sub object_DisplayModeChange()


Error Event

Indicates that an error occurred.

The Error event is sent when DirectShow reports an error during playback. By default, the ActiveMovie Control displays a message box containing the description string. To avoid displaying this box, set the CancelDisplay parameter of the Error event to False.

Syntax

Private Sub object_Error(ByVal SCode As Integer, ByVal Description As String, ByVal Source As String, CancelDisplay As Boolean)

object | Object expression that evaluates to an ActiveMovie Control.
SCode | Error code.
Description | String describing the error that occurred.
Source | String containing the ActiveMovie Control's name.
CancelDisplay | Value that the client can set to cancel the default error messages.


OpenComplete Event

Indicates the control finished opening the media file and is ready for playback.

Syntax

Private Sub object_OpenComplete()

Parameters

object Object expression that evaluates to an ActiveMovie Control.

Remarks

This event is provided for backward compatibility; use the ReadyStateChange event instead.


PositionChange Event

Indicates changes to the current media position, such as when the user selects (or seeks to) a new media position.

Syntax

Private Sub object_PositionChange(ByVal oldPosition As Double, ByVal newPosition As Double)

Parameters

object | Object expression that evaluates to an ActiveMovie Control.
oldPosition | Position before it changed, in seconds.
newPosition | Current position, in seconds, after the position change occurred.

Remarks

Changes made directly to the CurrentPosition property do not trigger this event.


ReadyStateChange Event

Indicates changes to the control's state of readiness.

Syntax

Private Sub object_ReadyStateChange(ByVal ReadyState As Long)

Parameters

object | Object expression that evaluates to an ActiveMovie Control.
ReadyState | Current state of readiness, after the change occurred.

Settings

Following are possible settings for the ReadyState parameter.
Setting | Value | Description
amvUninitialized | 1 | The FileName property has not been initialized.
amvLoading | 0 | The ActiveMovie Control is asynchronously loading a file.
amvInteractive | 3 | The control loaded a file, and downloaded enough data to play the file, but has not yet received all data.
amvComplete | 4 | All data has been downloaded.

Remarks

When you change the FileName property, applications should check the control's state of readiness before attempting to call the Run method on the newly opened file. Applications should call the Run method only if the ReadyState parameter equals amvInteractive or amvComplete.


StateChange Event

Indicates that the player state changed, such as from running to stopped.

Syntax

Private Sub object_StateChange(ByVal oldState As Long, ByVal newState As Long)

Parameters

object | Object expression that evaluates to an ActiveMovie Control.
oldState | Previous state, before the change occurred.
newState | Current state, after the change occurred.

Settings

Following are possible settings for the oldState or newState parameters.
Setting | Value | Description
amvStopped | 0 | The player is stopped.
amvPaused | 1 | The player is paused.
amvRunning | 2 | The player is playing the multimedia file.

Remarks

The ActiveMovie Control raises the StateChange event when the player state changes, such as from stopped to running. The current player state appears in the CurrentState property. You can find the player state flags in the CurrentState property documentation.


Timer Event

Provides the rate at which DirectShow refreshes the control panel's display.

Syntax

Private Sub object_Timer( )

Parameters

object Object expression that evaluates to an ActiveMovie Control.

Remarks

The Timer event is raised at the intervals specified by the control's timer.


Control Property Sheet

A property sheet is a dialog box with tabbed pages that you can use to set properties on a control. You can access the ActiveMovie Control Properties property sheet at either design or run time.

To activate a property page at design time, select the control, press F4, then click Custom in the Properties page. To activate a property page at run time, right-click, and then click Properties on the shortcut menu that appears. The following is a list of the tabs in the ActiveMovie Control Properties property sheet.

  • Playback
  • Movie Size
  • Controls
  • Advanced

Playback Tab

Use the controls on the Playback tab at run time to set options such as volume, rate of play, and the number of times you want the current video to play.

The Playback tab
Property | Description
Volume | Adjusts the control's volume. For information about how to set this property in code, see Volume.
Balance | Adjusts balance for the control.
Start Time | Identifies the start time for the current file.
Stop Time | Identifies the stop time for the current file. For information about how to set this property in code, see the AllowChangeDisplayMode property.
Play Count | Specifies the number of times to play the current file consecutively. For information about how to set this property in code, see the PlayCount property.
Auto Repeat | Causes the ActiveMovie Control to play the current file repeatedly. For information about how to set this property in code, see the AutoStart property.
Auto Rewind | Indicates whether to rewind the multimedia stream automatically and reposition at the beginning after playing stops. For information about how to set this property in code, see the AutoRewind property.

Movie Size Tab

Use the controls on the Movie Size tab at run time to specify the size of the window in which you want to play video.

The Movie Size tab
Property | Description
Movie Size | Use this option list to specify the movie's size. For information about how to set this property in code, see the MovieWindowSize property.
Run Full Screen | Select this option to maximize the ActiveMovie Control so that it fills the entire screen. For information about how to set this property in code, see the FullScreenMode property.

Controls Tab

Use the controls on the Controls tab at run time to specify which ActiveMovie controls you want to be visible.

The Controls tab
Property | Description
Display Panel | Select this check box if you want the display panel to be visible at run time. For information about how to set this property in code, see the ShowDisplay property.
Control Panel | Select this check box if you want the control panel to be visible at run time. For more information about how to set this property in code, see the ShowControls property.
Position Controls | Select this check box if you want the video stream position to be displayed at run time. For information about how to set this property in code, see the DisplayMode property.
Selection Controls | Select this check box to make the selection controls visible. For information about how to set this property in code, see the SelectionStart property.
Show Trackbar | Select this check box to toggle the visibility of the trackbar. For information about how to set this property in code, see the ShowTracker property.
Foreground Color | Use this control to show and set the foreground color of the ActiveMovie Control. For information about how to set this property in code, see the DisplayForeColor property.
Background Color | Use this control to show and set the background color of the ActiveMovie Control. For information about how to set this property in code, see the DisplayBackColor property.

Advanced Tab

Use the Advanced tab to run a filter on the currently playing video.

The Advanced tab
Property | Description
Filter Properties | Selects the filter property page to display when the Properties button is clicked.
Properties | Displays the property page of the filter selected in the Filter Properties list. Property pages allow you to change parameters on individual filters in the DirectShow filter graph. For more information about properties of DirectShow filters, see Filters in the DirectShow SDK documentation.


Control Shortcut Keys

You can use the following key combinations to activate ActiveMovie Control commands.
Key(s) | Result
CTRL+D | Toggle display
CTRL+LEFT ARROW | Rewind
CTRL+P | Pause
CTRL+R | Run
CTRL+RIGHT ARROW | Forward
CTRL+S | Stop
CTRL+SHIFT+LEFT ARROW | Previous
CTRL+SHIFT+RIGHT ARROW | Next
CTRL+T | Toggle control panel
ALT+ENTER | Toggle between full-screen and windowed modes
SHIFT+window resize | Stretches video to fill the control window


ADO Overview

ActiveX™ Data Objects (ADO) enables you to write an application to access and manipulate data in a database server through an OLE DB provider. ADO’s primary benefits are high speed, ease of use, low memory overhead, and a small disk footprint.

ADO Features

ADO supports key features for building client/server and web-based applications, including the following:

  • Independently-created objects. Unlike Data Access Objects (DAO) or Remote Data Objects (RDO), you no longer have to navigate through a hierarchy to create objects because most ADO objects can be independently created. This allows you to create and track only the objects you need, and also results in fewer ADO objects and thus a smaller working set.

  • Batch updating helps improve performance by locally caching changes to data, then writing them all to the server in a single update.

  • Support for stored procedures with in/out parameters and return values.

  • Different cursor types, including the potential for support of back-end–specific cursors.

  • Support for limits on number of returned rows and other query goals for performance tuning.

  • Support for multiple recordsets returned from stored procedures or batch statements.

  • Free-threaded objects for efficient web server applications.

Note While ADO supports these features, the underlying providers and drivers called by ADO may not. Check the topic, Using OLE DB Providers with ADO as well as the documentation for the underlying providers and drivers to determine what functionality they support. Unless otherwise noted in the language reference topics, all of the ADO 1.5 Objects, Methods, and Properties described in this document are available when used with the Microsoft OLE DB Provider for ODBC and Microsoft SQL Server version 6.5.

Remote Data Service

ADO’s Remote Data Service (RDS) allows data remoting, by which you can move data from a server to a client application or Web page, manipulate the data on the client, and return updates to the server in a single round trip. Previously released as Advanced Data Connector 1.0, RDS has been combined with the ADO programming model to simplify client-side data remoting. For more information, see the Remote Data Service documentation.

Installing ADO

As part of the Microsoft Data Access Components, ADO and RDS are automatically installed and registered by a host product, such as Microsoft Internet Information Server. The host product setup program may require that you specifically request the Microsoft Data Access COmponents in order to have ADO and RDS installed.

Programming with ADO

ADO is a dual-interface COM type library. The filename is msado15.dll. The program ID (ProgID) is “ADODB.” In 2 and 3 tier database applications, ADO code that is to execute on the client uses the ProgID “ADOR” instead.

To use ADO with Microsoft Visual Basic or Microsoft Office, you also need to establish a reference to the ADO type library. Select References from the Project menu, check the box for “Microsoft ActiveX Data Objects 1.5 Library,” and then click “OK.” ADO objects, methods, and properties will then be accessible through the VBA Object Browser and the IDE Editor.

To use ADO with Microsoft Visual J++, you also need to create a set of class files using the Java Type Library Wizard. Select the Java Type Library Wizard from the Tools menu, check the box for “Microsoft ActiveX Data Objects 1.5 Library,” and then click “OK.” The wizard will then create the necessary Java class files for ADO.

For some programming languages, you also need to reference (using the #include statement) one or more additional files in your source code, as shown in the table below:
For C++ | For VBScript | For JScript
adoint.h | adovbs.inc | adojavas.inc
adoid.h

Threading

The ADO library is free-threaded, but listed in the Windows Registry as apartment model. The thread safety of ADO depends on the underlying provider and data source. For example, the Microsoft OLE DB Provider for ODBC is free-threaded, but not all ODBC drivers are. You should use ADO as apartment model unless you can verify that all of the underlying components can be used free-threaded.

ADO Objects

Although ADO objects are creatable outside the scope of a hierarchy, the objects exist within hierarchical relationships, as shown in the ADO Object Model.

There are 7 objects in the ADO object model:

Command - Maintains information about a command, such as a query string, parameter definitions, etc. You can execute a command string on a Connecton object or a query string as part of opening a Recordset object, without defining a Command object. The Command object is useful where you want to define query parameters, or execute a stored procedure that returns output parameters.

Connection - Maintains connection information with the data provider.

Error - Contains extended error information about an error condition raised by the provider. Since a single statement can generate two or more errors, the Errors collection can contain more than one Error object at a time, all of which result from the same incident.

Field - Contains information about a single column of data within a Recordset. The Recordset object features a Fields collection to contain all of its Field objects.

Parameter - A single parameter for a parameterized Command. The Command object features a Parameters collection to contain all of its Parameter objects.

Property - A provider-defined characteristic of an ADO object.

Recordset - A set of records returned from a query, and a cursor into those records. You can open a Recordset (i.e., execute a query) without explicitly opening a Connection object. However, if you do first create a Connection object, you can open multiple Recordset objects on the same connection.

Each of these objects features a set of properties and methods with which you can manipulate the object and its contents.

Dynamic Properties Collections

The Connection, Command, and Recordset objects each supports a Properties collection. The properties collection contains any dynamic (or “provider-specific”) properties exposed through ADO by the provider. You use the collection and the Item method to reference the property by it’s name or by it’s ordinal position in the collection, as shown:

Command.Properties.Item(0)
Command.Properties.Item(“Name”)

Since the Item method is a default method on an ADO collection, you can omit it:

Command.Properties(0)
Command.Properties(“Name”)

Further, the Properties collection itself is the default collection for the Connection, Command, andRecordset objects, so you can omit it as well:

Command(0)
Command(“Name”)

All of these syntax forms are identical. Which one you choose depends on your coding style preference.

Working with Data

In ADO, the Recordset object is the main interface to data. While the other objects are useful for managing connections, collecting error information, persisting queries, etc., most of your code’s interaction with ADO will involve one or more Recordset objects.

Here is the minimum code (using Microsoft® Visual Basic® Scripting Edition) needed to generate a Recordset from an ODBC data source:

set rstMain = CreateObject("ADODB.Recordset")
rstMain.Open "SELECT * FROM authors", _
    "DATABASE=pubs;UID=sa;PWD=;DSN=Publishers"

This generates a forward-only, read-only Recordset object. With a few modifications, you can obtain a more functional Recordset:

set rstMain = CreateObject("ADODB.Recordset")
rstMain.Open "SELECT * FROM authors", _
    "DATABASE=pubs;UID=sa;PWD=;DSN=Publishers",
    adOpenKeyset, adLockBatchOptimistic

This creates a fully scrollable and batch-updatable Recordset.

Note In order to reference ADO constants by name (instead of by value) when coding in a scripting language, as shown in these code examples, you must include the appropriate header file. For Microsoft Visual Basic Scripting Edition, include the file adovbs.inc in your code. For Microsoft JScript™, include the file adojavas.inc in your code. You should always refer to constants by name rather than by value since the values may change from one version to the next.

For the latest information on ADO, visit the Microsoft ADO web page.


Microsoft Agent

Microsoft Agent Microsoft Agent *

ActiveX™ Technology for Interactive Software Agents

Microsoft® Agent supports the presentation of software agents as interactive personalities within the Microsoft Windows® interface. Microsoft® Agent comes with a cast of three characters: Merlin, Genie, and Robby; shown above. Developers can use these characters as interactive assistants to introduce, guide, entertain, or otherwise enhance their Web pages or applications. Microsoft® Agent also includes tools for defining custom characters.

  • Component Installation
  • Documentation
  • Frequently Asked Questions
  • Character Data
  • Samples
  • Support
  • Licensing and Redistribution


Microsoft Chat Controls

Microsoft provides three reusable components that allow developers and content providers to add Internet functionality to their applications:

Microsoft Chat Control 1.1

Microsoft Chat Protocol Control 2.0

Microsoft Chat 1.0j Java Applet

The following list outlines the differences between these three components. It is provided to help developers and Web authors decide which component to use in their applications.

  • The Chat 1.1 control and Chat 1.0j applet offer customizable default user interfaces; the Chat Protocol Control 2.0 control requires the developer to design the user interface.
  • The Chat 1.1 control communicates with the server through either MIC or IRC protocols. The Chat 1.0j applet communicates with the server through the IRC protocol only. The Chat Protocol Control 2.0 communicates with the server through either IRC or IRCX protocols.
  • Since the Chat 1.0j applet is written in Java, it can be used in browsers that support Java. The Chat 1.1 and Chat Protocol Control 2.0 must be hosted by an ActiveX™ control container such as Internet Explorer or Visual Basic®.
  • The Chat Protocol Control 2.0 permits multiple concurrent conversations. The Chat 1.1 control and Chat 1.0j applet are limited to chatting in only one room at a time.
  • The Chat Protocol Control 2.0 exposes a much greater set of features than the Chat 1.1 control or Chat 1.0j.


Microsoft Chat Control 1.1

The Microsoft® Chat Control 1.1 is an ActiveX™ control that allows you to participate in a chat, or conversation using text and data between two or more users connected to a chat server. The Chat Control 1.1 communicates with the chat server through either the MIC or IRC protocols.

Microsoft Chat Control 1.1 Visual Basic Overview

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.

Microsoft Chat control data flow diagram

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:

  1. 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.
  2. The Web browser downloads the Chat control software to Web Client 3.
  3. The user on Web Client 3 types the message "Hello." The Chat control sends the message to the chat room.
  4. The chat room sends the message "Hello" to all participants in the chat. They see "Hello" on their Chat History text boxes.
  5. 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.

Microsoft Chat control user interface

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/ External link), 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.

Microsoft Chat control in an HTML page

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.


Microsoft Chat Control 1.1 Visual Basic Reference

The Microsoft® Chat control is an ActiveX™-based control that can be used with any OLE container. This control provides users with the capability to create a chat, or conversation, that communicates text and/or data with other users connected through the Internet or an intranet. This reference describes the properties, methods, events, and error codes associated with the Chat control.

  • Properties
  • Methods
  • Events
  • Error Codes

MSChat Object

Properties

Appearance, BackColor, BorderStyle, Height, History, LastMessageReceived, LastMessageSent, MaxHistoryLength, MaxMembers, MaxMessageLength, MemberCount, Rating, RoomPath, RoomTopic, State, ThisParticipantAlias, ThisParticipantID, ThisParticipantName, UIOption, Width

Methods

AboutBox, BanParticipant, CancelEntering, ClearHistory, EnterRoom, ExitRoom, GetParticipantRealName, InviteParticipant, KickParticipant, MoveSplitBar, SelectParticipants, SendMessage, SetParticipantStatus

Events

OnBeginEnumeration, OnEndEnumeration, OnEnterParticipant, OnError, OnExitParticipant, OnHistoryFull, OnMessage, OnParticipantAliasChanged, OnParticipantInvited, OnParticipantKicked, OnParticipantRealName, OnParticipantStatusChanged, OnRoomTopicChanged, OnRoomTypeChanged, OnStateChanged, OnTextMessageSent


Properties

This section describes the properties associated with the Microsoft Chat control.

Appearance Property
BackColor Property
BorderStyle Property
Height Property
History Property
LastMessageReceived Property
LastMessageSent Property
MaxHistoryLength Property
MaxMembers Property
MaxMessageLength Property
MemberCount Property
Rating Property
RoomPath Property
RoomTopic Property
State Property
ThisParticipantAlias Property
ThisParticipantID Property
ThisParticipantName Property
UIOption Property
Width Property


Appearance Property

Retrieves or sets the appearance of the Chat control. This property is persistent and is read-only when connected to a chat room. This property has meaning only if the internal user interface is displayed.

Syntax

object.Appearance[=value]

Parameters

object | Required. An object expression that evaluates to a Chat control.
value | Optional. A short integer expression that determines the appearance of the Chat control. Can be set to one of the return values listed below.

Return Value

Returns a short integer value that indicates the current appearance of the Chat control. Can be one of the following values.
0 | All flat
1 | 3-D children only
2 | 3-D control frame only
3 | All 3-D

See Also

BorderStyle, UIOption


BackColor Property

Retrieves or sets the color of the background behind the text panes and the toolbar. This property is persistent and has meaning only if the internal user interface is displayed.

Syntax

object.BackColor[=value]

Parameters

object | Required. An object expression that evaluates to a Chat control.
value | Optional. An OLE_COLOR expression that determines the background color. The default value is the system's default window background color.

Return Value

Returns the OLE_COLOR value of the current background behind the text panes and toolbar.

See Also

UIOption


BorderStyle Property

Retrieves or sets the appearance of the border. This property is read-only when connected to a chat room and has meaning only if the internal user interface is displayed. This property is persistent.

Syntax

object.BorderStyle[=value]

Parameters

object | Required. An object expression that evaluates to a Chat control.
value | Optional. A short integer expression that determines the border appearance. Can be set to one of the return values listed below.

Return Value

Returns the current border style. Can be one of the following values.
0 | None
1 | Single fixed for children only
2 | Single fixed for control frame only
3 | All single fixed

See Also

Appearance, UIOption


Height Property

Retrieves or sets the height of the control in HiMetrics. Each HiMetrics unit corresponds to 0.01 millimeters. This property is persistent.

Syntax

object.Height[=value]

Parameters

object | Required. An object expression that evaluates to a Chat control.
value | Optional. A HiMetrics value that indicates the height of the Chat control.

Return Value

Returns the current height of the Chat control in HiMetrics units.

See Also

Width


History Property

Retrieves the current content of the History text box. This property is read-only and has meaning only if the internal user interface is displayed.

Syntax

object.History

Parameters

object Required. An object expression that evaluates to a Chat control.

Return Value

Returns a BSTR value that contains the current contents of the History text box. If UIOption does not include the History text box (value=8), this property returns an empty string.

Remarks

The length of this string is limited by the MaxHistoryLength property.

See Also

ClearHistory


LastMessageReceived Property

Retrieves the last message the user received from the channel. This property is read-only.

Syntax

object.LastMessageReceived

Parameters

object Required. An object expression that evaluates to a Chat control.

Return Value

Returns a BSTR value that contains the last message received by the user.

Remarks

This property is updated whenever the user receives a text message.

See Also

LastMessageSent


LastMessageSent Property

Retrieves the last message sent by the user. This property is read-only.

Syntax

object.LastMessageSent

Parameters

object Required. An object expression that evaluates to a Chat control.

Return Value

Returns a BSTR value that contains the last text message sent by the user.

Remarks

This property is updated whenever the user sends a text message.

See Also

LastMessageReceived


MaxHistoryLength Property

Retrieves or sets the maximum number of characters allowed in the History text box. This property has meaning only if the internal user interface is displayed.

Syntax

object.MaxHistoryLength[=value]

Parameters

object | Required. An object expression that evaluates to a Chat control.
value | Optional. A long integer value that sets the maximum number of characters allowed in the History text box.

Return Value

Returns the maximum number of characters allowed in the History text box. If the UIOption property does not include the History text box (value=8), this property is equal to zero. The default value of MaxHistoryLength is 32K.

See Also

ClearHistory, History


MaxMembers Property

Retrieves or sets the maximum number of members in a chat room.

Syntax

object.MaxMembers[=value]

Parameters

object | Required. An object expression that evaluates to a Chat control.
value | Optional. A long integer expression that determines the maximum number of members allowed in the room. Only a host of the chat room can change this property.

Return Value

Returns zero if the limit is the server's default limit, or the maximum number of members otherwise.

See Also

MemberCount


MaxMessageLength Property

Retrieves or sets the maximum number of characters allowed in the Send text box.

Syntax

object.MaxMessageLength[=value]

Parameters

object | Required. An object expression that evaluates to a Chat control.
value | Optional. A long integer value that determines the maximum number of characters allowed in the Send text box. The default value is 2040 characters, which is the maximum message length on an MIC server.

Return Value

Returns the maximum number of characters allowed in the Send text box. If the UIOption property does not include the Send text box (value=16), this property is equal to zero.

See Also

SendMessage


MemberCount Property

Retrieves the number of members currently in the user's chat room. This property is read-only.

Syntax

object.MemberCount

Parameters

object Required. An object expression that evaluates to a Chat control.

Return Value

Returns zero if the user is not in a chat room, or the number of members in the chat room otherwise.

See Also

MaxMembers


Rating Property

Retrieves the rating of a chat room. This property is read-only.

Syntax

object.Rating

Parameters

object Required. An object expression that evaluates to a Chat control.

Return Value

Returns a BSTR value that contains the Platform for Internet Content Selection (PICS) rating if the chat room is on an MIC server. Otherwise, this property returns an empty string. For more information on PICS ratings, see Internet Ratings.


RoomPath Property

Retrieves the location of the chat room to which the user is currently connected. This property is read-only.

Syntax

object.RoomPath

Parameters

object Required. An object expression that evaluates to a Chat control.

Return Value

Returns a BSTR expression that evaluates to the server location of the chat room. If the user is not connected to a chat room, an empty string is returned.

Remarks

The format of the server location returned is:

prefix://server-name[:port-number]/[[#]|[&]]room-name

The prefix can be 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.

See Also

EnterRoom


RoomTopic Property

Retrieves or sets the chat room's topic. This property can be used to set the topic when creating a chat room, to change the topic when the user is in the room, or to get the current topic of the room that the user is in.

Syntax

object.RoomTopic[=value]

Parameters

object | Required. An object expression that evaluates to a Chat control.
value | Optional. A BSTR value that indicates the topic name to be set.

Return Value

Returns a BSTR value that contains the topic name of the chat room that the user is currently in.

Remarks

The user cannot set or modify the topic if the chat room was created with the value in the EnterRoom method set to (Type=2), which allows only the host to change the topic, and the user is not the host.

See Also

OnRoomTopicChanged


State Property

Retrieves whether the user is currently disconnected from, connected to, or in the process of connecting to a chat room. This property is read-only.

Syntax

object.State

Parameters

object Required. An object expression that evaluates to a Chat control.

Return Value

Returns the current user state. Can be one of the following values.
1 | Disconnected from any chat rooms
2 | Connecting to a chat room
3 | Connected to a chat room

See Also

CancelEntering, EnterRoom, ExitRoom, OnStateChanged


ThisParticipantAlias Property

Retrieves the user's alias. This property is read-only.

Syntax

object.ThisParticipantAlias

Parameters

object Required. An object expression that evaluates to a Chat control.

Return Value

Returns a BSTR value that contains the user's nickname used when the EnterRoom method was called, if the user is currently in a chat room. If the user is not in a chat room, an empty string is returned.

See Also

OnParticipantAliasChanged, ThisParticipantID, ThisParticipantName


ThisParticipantID Property

Retrieves the user's numeric identifier. This property is read-only.

Syntax

object.ThisParticipantID

Parameters

object Required. An object expression that evaluates to a Chat control.

Return Value

Returns a long integer value that contains the user's numeric identifier, if the user is currently in a chat room. If the user is not in a chat room, the value is zero.

See Also

ThisParticipantAlias, ThisParticipantName


ThisParticipantName Property

Returns the user's Microsoft Windows® user name. This property is read-only.

Syntax

object.ThisParticipantName

Parameters

object Required. An object expression that evaluates to a Chat control.

Return Value

Returns a BSTR value that contains the user's Windows user name, if the user is currently in a chat room. If the user is not in a chat room, an empty string is returned.

See Also

ThisParticipantAlias, ThisParticipantID


UIOption Property

Contains flags that control the appearance of the default user interface. This property is a bitmask.

Syntax

object.UIOption[=value]

Parameters

object Required. An object expression that evaluates to a Chat control.
value Optional. A short integer expression that equals the sum of the desired user interface option values. Can include the following option values.
1 | Set this value to display the Send button. Must set the Send text box (value=16) in order to set the Send button.
2 | Set this value to display the Whisper button. Must set the Send button (value=1) in order to set the Whisper button.
4 | Set this value to display the Participant list box.
8 | Set this value to display the History text box. This window displays all messages that have been received.
16 | Set this value to display the Send text box. The user composes messages in this text box before sending them.
32 | Set this value to notify members in the History text box when a new user joins the chat.
64 | Set this value to notify members in the History text box when a user leaves the chat.
128 | Set this value to allow the Chat control to display a dialog box that notifies the user when a member's status (host, participant, or spectator) changes, when a member's alias (nickname) changes, and when the user has been kicked by a host.
256 | Set this value to insert a blank line between messages in the History text box.
512 | Set this value to allow the Chat control to display error dialog boxes. When an OnError event is triggered, a dialog box containing the error message will appear.
1024 | Set this value to allow the user to resize the control.
2048 | Set this value to allow any URLs appearing in the History text box to be clickable.

Return Value

Returns the sum of the option values currently selected.

Remarks

To set a Chat control's user interface so that it includes a Send text box, Send button, Whisper button, History text box, and Participant list box, this property must be set to the sum of the option values. In this case, the sum would equal 31 (16 + 1 + 2 + 8 + 4 = 31). To set the control to have all options, the sum would equal 4095 (1 + 2 + 4 + 8 + 16 + 32 + 64 + 128 + 256 + 512 + 1024 + 2048 = 4095).

See Also

Appearance, BackColor, BorderStyle, History, MaxHistoryLength, MaxMessageLength


Width Property

Returns or sets the width of the control in HiMetrics. Each HiMetrics unit corresponds to 0.01 millimeters. This property is persistent.

Syntax

object.Width[=value]

Parameters

object | Required. An object expression that evaluates to a Chat control.
value | Optional. A HiMetrics value that indicates the width of the Chat control.

Return Value

Returns the current width of the Chat control in HiMetrics units.

See Also

Height


Methods

This section describes the methods associated with the Microsoft Chat control.

AboutBox Method
BanParticipant Method
CancelEntering Method
ClearHistory Method
EnterRoom Method
ExitRoom Method
GetParticipantRealName Method
InviteParticipant Method
KickParticipant Method
MoveSplitBar Method
SelectParticipants Method
SendMessage Method
SetParticipantStatus Method


AboutBox Method

Displays the About message dialog box.

Syntax

object.AboutBox

Parameters

object Required. An object expression that evaluates to a Chat control.


BanParticipant Method

Bans a member from or reinstates a member to a chat room.

Syntax

object.BanParticipant Name, Set

Parameters

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.

Remarks

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.

See Also

KickParticipant


CancelEntering Method

Cancels an EnterRoom operation

Syntax

object.CancelEntering

Parameters

object Required. An object expression that evaluates to a Chat control.

Remarks

This method should be called only when the control's State property is equal to 2 (Connecting).

See Also

EnterRoom


ClearHistory Method

Empties the History text box.

Syntax

object.ClearHistory

Parameters

object Required. An object expression that evaluates to a Chat control.

Remarks

This method has an effect only if the value of the UIOption property includes a History text box (value=8).

See Also

History, OnHistoryFull


EnterRoom Method

Allows the user to enter the specified chat room.

Syntax

object.EnterRoom RoomPath, RoomPwd, ThisParticipantAlias, SecurityPackage, Flags, Type

Parameters

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.
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.
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.

Remarks

This method should be called only when the control's State property is equal to 1 (Disconnected).

See Also

CancelEntering, ExitRoom, OnRoomTypeChanged, RoomPath


ExitRoom Method

Disconnects the user from the current chat room.

Syntax

object.ExitRoom

Parameters

object Required. An object expression that evaluates to a Chat control.

Remarks

This method should be called only when the control's State property is equal to 3 (Connected).

See Also

CancelEntering, EnterRoom


GetParticipantRealName Method

Gets the real name of a participant by using the member's participant ID or alias (nickname).

Syntax

object.GetParticipantRealName ParticipantID, Alias, Synchronous, RealName

Parameters

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.

Remarks

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.

See Also

ThisParticipantID, ThisParticipantAlias


InviteParticipant Method

Invites a member to the user's current chat room.

Syntax

object.InviteParticipant Alias

Parameters

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.

Remarks

The member must be on the same chat server as the user.

See Also

OnParticipantInvited, ThisParticipantAlias


KickParticipant Method

Kicks a member from the chat room.

Syntax

object.KickParticipant ParticipantID, KickComment

Parameters

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.

Remarks

This method cannot be called before the OnEndEnumeration event has been triggered.

See Also

BanParticipant, OnParticipantKicked, ThisParticipantID


MoveSplitBar Method

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.

Syntax

object.MoveSplitBar

Parameters

object Required. An object expression that evaluates to a Chat control.


SelectParticipants Method

Selects, deselects, or inverts the selection of members in the Participant list box.

Syntax

object.SelectParticipants value

Parameters

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.
0 | Deselects any highlighted member.
1 | Selects all the members.
2 | Deselects the highlighted members and selects the members that were not highlighted.

Remarks

This method has an effect only if the UIOption property includes a Participant list box (value=4).

See Also

SendMessage


SendMessage Method

Sends a message.

Syntax

object.SendMessage DestinationList, Count, Message

Parameters

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.

Remarks

This method cannot be called before the OnEndEnumeration event has been triggered.

See Also

History, OnMessage, SelectParticipants, ThisParticipantID


SetParticipantStatus Method

Changes the status of the member in a chat room.

Syntax

object.SetParticipantStatus ParticipantID, Mask, Status

Parameters

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.
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.
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.

Remarks

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.

See Also

OnParticipantStatusChanged, ThisParticipantID


Events

This section describes the events associated with the Microsoft Chat control.

OnBeginEnumeration Event
OnEndEnumeration Event
OnEnterParticipant Event
OnError Event
OnExitParticipant Event
OnHistoryFull Event
OnMessage Event
OnParticipantAliasChanged Event
OnParticipantInvited Event
OnParticipantKicked Event
OnParticipantRealName Event
OnParticipantStatusChanged Event
OnRoomTopicChanged Event
OnRoomTypeChanged Event
OnStateChanged Event
OnTextMessageSent Event


OnBeginEnumeration Event

Occurs when a user enters a chat room, before the list of members already in the conversation appears in the Participant list box.

Syntax

object_OnBeginEnumeration

Value | Description
object | Required. An object expression that evaluates to a Chat control.

See Also

EnterRoom, OnEndEnumeration, UIOption


OnEndEnumeration Event

Occurs after getting the initial list of members in the conversation, including the user.

Syntax

object_OnEndEnumeration

Value | Description
object | Required. An object expression that evaluates to a Chat control.

Remarks

The user can start to use the ThisParticipantID property or the SetParticipantStatus, KickParticipant, BanParticipant, and SendMessage methods once this event is triggered.


OnEnterParticipant Event

Occurs when either the list of members already in the conversation first appears when entering a chat room or when a new participant joins the conversation.

Syntax

object_OnEnterParticipant(ParticipantID, Name, Status)

Value | Description
object | Required. An object expression that evaluates to a Chat control.
ParticipantID | A long integer value that contains the participant ID of the member entering the chat room.
Name | A BSTR value that contains the alias of the member joining the chat room.
Status A short integer value indicating the status of the member entering the room. Can be one of the following values.
1 | Member is a host.
2 | Member is a participant.
4 | Member is a spectator.

See Also

EnterRoom


OnError Event

Occurs when there is an error in the control. If the display dialog boxes flag (value=512) is set in the UIOption property, the error message is displayed to the user.

Syntax

object_OnError(ErrorCode, Description)

Value | Description
object | Required. An object expression that evaluates to a Chat control.
ErrorCode | A short integer value that contains the numeric value of the error code.
Description | A BSTR value that contains the error message that is associated with the error code.


OnExitParticipant Event

Occurs when a member leaves the chat room.

Syntax

object_OnExitParticipant(ParticipantID)

Value | Description
object | Required. An object expression that evaluates to a Chat control.
ParticipantID | A long integer value that contains the participant ID of the member exiting the chat room.

See Also

ExitRoom


OnHistoryFull Event

Occurs each time a message is added to the History text box, when the total number of characters in the History text box is at least 90 percent of the MaxHistoryLength property (which is the maximum number of characters allowed in the History text box).

Syntax

object_OnHistoryFull(Percent)

Value | Description
object | Required. An object expression that evaluates to a Chat control.
Percent | The exact percentage of the History text box's maximum length that has been used.

Remarks

If the History text box gets too full to contain an incoming message, the top 20 percent of the text box's contents are removed. If this does not give enough space to fit the incoming message, more text is removed.

See Also

ClearHistory, History, UIOption


OnMessage Event

Occurs when a user gets a message from a member or the chat room.

Syntax

object_OnMessage(SenderID, Message, MessageType)

Value | Description
object | Required. An object expression that evaluates to a Chat control.
SenderID | A long integer that contains the participant ID of the member who sent the message, or zero if the message comes from the chat room.
Message | A VARIANT value that contains the message. The incoming message can be a text message (BSTR) or data (an array of bytes, shorts, longs, floats, doubles, Booleans, errors, currencies, or dates).
MessageType Can be a combination of the following values.
0 | A text or data message that is broadcast to all members.
1 | A text or data message that is whispered to one or more members.
2 | A ComicChat thought, which is text only.
4 | An action, which is text only.

See Also

SendMessage, OnTextMessageSent, ThisParticipantID


OnParticipantAliasChanged Event

Occurs when the member's alias is changed. Also, if the display notifications flag (value=128) is set in the UIOption property, a dialog box is displayed that says: "<OldAlias> is now known as <NewAlias>."

Syntax

object_OnParticipantAliasChanged(ParticipantID, OldAlias, NewAlias)

Value | Description
object | Required. An object expression that evaluates to a Chat control.
ParticipantID | A long integer value that contains the participant ID of the member whose alias is changing.
OldAlias | A BSTR value that contains the old alias.
NewAlias | A BSTR value that contains the new alias.

See Also

ThisParticipantAlias


OnParticipantInvited Event

Occurs when a member invites the user to the member's chat room.

Syntax

object_OnParticipantInvited(RoomName, Alias)

Value | Description
object | Required. An object expression that evaluates to a Chat control.
RoomName | A string value containing the name of the member's chat room.
Alias | A string value containing the name of the member who invited the user to the member's chat room.

See Also

InviteParticipant, ThisParticipantAlias


OnParticipantKicked Event

Occurs when the user is kicked from the chat room.

Syntax

object_OnParticipantKicked(ParticipantID, Reason)

Value | Description
object | Required. An object expression that evaluates to a Chat control.
ParticipantID | A long integer value that contains the participant ID of the host who kicked the user from the chat room.
Reason | A BSTR value that contains the reason given for kicking the user from the chat room. This value can be an empty string, if no reason was given.

See Also

KickParticipant, ThisParticipantID


OnParticipantRealName Event

Occurs when a successful call is made to GetParticipantRealName with the Synchronous parameter set to FALSE.

Syntax

object_OnParticipantRealName(Alias, RealName)

Value | Description
object | Required. An object expression that evaluates to a Chat control.
Alias | A BSTR value that contains the current alias of the member.
RealName | A BSTR value that contains the real name of the member.

See Also

ThisParticipantName


OnParticipantStatusChanged Event

Occurs when a member changes status.

Syntax

object_OnParticipantStatusChanged(ParticipantID, Status)

Value | Description
object | Required. An object expression that evaluates to a Chat control.
ParticipantID | A long integer value that contains the participant ID of the member whose status is changing.
Status A short integer value that indicates the new status of the member. The new status is a combination of the following values.
1 | Member has become a host.
2 | Member has become a participant.
4 | Member has become a spectator.
8 | Member does not allow whispers.
16 | Member is ignored, so all incoming messages from this member are discarded.

Remarks

Any member is either a host (Status=1), participant (Status=2), or spectator (Status=4), so a valid status must include one of these values.

See Also

SetParticipantStatus, ThisParticipantID


OnRoomTopicChanged Event

Occurs when the room topic property changes.

Syntax

object_OnRoomTopicChanged(NewRoomTopic)

Value | Description
object | Required. An object expression that evaluates to a Chat control.
NewRoomTopic | A BSTR value that contains the description of the new topic of conversation.

See Also

RoomTopic


OnRoomTypeChanged Event

Gives the value of the new room type.

Syntax

object_OnRoomTypeChanged(NewRoomType)

Value | Description
object | Required. An object expression that evaluates to a Chat control.
NewRoomType A short integer value that equals the sum of the room type settings. Can be a combination of the following values.
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 (NewRoomType=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.

Remarks

For example, if NewRoomType=10, it means that only hosts can change the room topic (NewRoomType=2), and no whispers are allowed in the room (NewRoomType=8).

See Also

EnterRoom


OnStateChanged Event

Occurs when the user's state changes.

Syntax

object_OnStateChanged(NewState)

Value | Description
object | Required. An object expression that evaluates to a Chat control.
NewState A short integer that indicates the user's new state. Can be one of the following values.
1 | Disconnected from any chat rooms.
2 | Connecting to a chat room.
3 | Connected to a chat room.

See Also

State


OnTextMessageSent Event

Occurs whenever the user sends a text message by using the internal Send button or Whisper button.

Syntax

object_OnTextMessageSent(TextMessage, MessageType)

Value | Description
object | Required. An object expression that evaluates to a Chat control.
TextMessage | A BSTR value that contains the text sent by the user.
MessageType A short integer value that indicates the type of message sent. Can be one of the following values.
0 | The user sent some text as a broadcast to all members.
1 | The user sent some text as a whisper to one or more members.

Remarks

This event is not triggered when using the SendMessage method.

See Also

UIOption


Error Codes

The following list contains the error codes and their associated error messages. These error messages are subject to change and may not be exactly as they appear below.
Error code | Error message
5 | Illegal function call.
6 | Overflow error.
7 | Out of memory.
70 | Permission is denied.
380 | Invalid property value.
382 | Property is read-only at run time.
383 | Property is read-only.
394 | Property is write-only.
1000 | An error occurred. Please leave the application and try again.
1001 | Could not load the RICHED32.DLL library.
1002 | The room could not be found.
1003 | You are already trying to enter a room.
1004 | You are not trying to enter a room.
1005 | You are already in a chat room.
1006 | The room is full. Please try again later.
1007 | You cannot create this room, it already exists.
1008 | Could not make the room unique.
1009 | Too many rooms are already open on this server.
1010 | This is a room for which you need an invitation.
1011 | This is a password protected room. The room password specified is invalid.
1012 | The operation is denied.
1013 | The chat room path specified is invalid.
1014 | Can't connect to the chat server.
1015 | User unknown. Please verify your entries.
1016 | The alias specified is already in use.
1017 | The name specified is too long.
1018 | The user password specified is too long.
1019 | The room password specified is too long.
1020 | The alias specified is too long.
1021 | The room name specified is too short. Please enter a longer name.
1022 | The room name specified is too long. Please enter a shorter name.
1023 | The server name specified is too long.
1024 | The chat room topic specified is too long. Please enter a shorter topic.
1025 | A string specified is too long.
1026 | The Flags parameter specified is invalid.
1027 | The Type parameter specified is invalid.
1028 | The room name specified contains illegal characters.
1029 | The alias specified contains illegal characters.
1030 | For MIC and IRC local rooms, the first character has to be &. For IRC global rooms, the first character has to be #.
1031 | This chat has a bad name. The server cannot create it.
1032 | This user is unknown. The authentication failed.
1033 | Select the name of the member you want to ignore, and try again. You cannot ignore yourself or a host.
1034 | The participant ID specified is invalid.
1035 | Please select exactly one member and try the operation again.
1036 | You cannot kick yourself!
1037 | You cannot ban or reinstate yourself!
1038 | The status specified is invalid.
1039 | The mask specified is invalid.
1040 | The status change was denied.
1041 | Only a host can complete this operation.
1042 | You can only complete this operation on yourself.
1043 | This operation cannot be attempted on a host.
1044 | This operation cannot be attempted on an ignored member.
1045 | You cannot whisper to yourself.
1046 | Could not send the message.
1047 | The Receive text box limitation is too small to display the message. You might want to increase this limitation.
1048 | The destination list specified is invalid.
1049 | The message type specified is invalid.
1050 | The message format is invalid.
1051 | You are trying to whisper to too many recipients.
1052 | The message is empty.
1053 | The message to send is too long and could not be sent.
1054 | Only a system operator can complete this operation.
1055 | You are currently not connected to a chat server.
1056 | The chat server specified could not be found.
1057 | You are currently not in a room.
1058 | The connection to the chat server was lost.
1059 | A host of this chat room closed the room. You are no longer in the room.
1060 | Property is read-only when you're in a chat room.
1061 | The authentication could not be performed.
1062 | The password provided is invalid.
1063 | You are not allowed to whisper in this chat room.
1064 | This member does not accept whispers.
1065 | All the recipients refuse whispers.
1066 | The member name specified is blank or invalid.
1067 | This server does not allow IRC clients.
1068 | You have been banned from this chat room.
1069 | This chat room only allows authenticated members.
1070 | This server is full and does not allow additional members. Please try again later.
1071 | The server does not recognize the security package specified.
1072 | The SecurityPackage parameter specified is too long.
1073 | An MIC operation was attempted on an IRC channel
1074 | The PICS rating of this channel doesn't allow you to complete this operation.
1075 | No member with the alias specified could be found.
1076 | Couldn't get the real name of the member.
1077 | An error occurred on the chat server.
1078 | You cannot put carriage returns in a message sent to an IRC room.
1079 | A security-related error occurred on the server.
1080 | This MSN account is unknown.
1081 | This NT account is unknown.
1082 | The authenticated login failed.
1083 | Could not log you in successfully.
1084 | This chat program cannot join this type of room. Please try another room.
1085 | The chat room could not be created.
1086 | The operation could not be performed successfully.
1087 | Only administrators can perform this operation.
1088 | The server and client protocols in use are not compatible.
1089 | A member is trying to flood you.
1090 | You are not allowed to talk in this room.
1091 | The member is already in this room.
1092 | The member you specified is currently unknown on this chat server.


Microsoft Chat Protocol 2.0

The Microsoft® Chat Protocol Control 2.0 is an ActiveX™ control that allows you to participate in a chat, or conversation using text and data between two or more users connected to a chat server. The Chat Protocol Control 2.0 communicates with the chat server through either the IRC or IRCX protocols.

Microsoft Chat Protocol Control 2.0 Visual Basic Overview (Beta1 Release)

Microsoft Chat Protocol Control 2.0 Visual Basic Reference (Beta1 Release)


Microsoft Chat Protocol Control 2.0 Visual Basic Overview (Beta1 Release)

The Microsoft® Chat Protocol Control 2.0 is an ActiveX™ control that allows the user to participate in a chat, or conversation, between two or more users connected to a chat server.

The Chat Protocol control allows the user to communicate both text and data, including arrays, Booleans, errors, currencies, and dates.

Stand-alone Microsoft Visual Basic® or Microsoft Visual C++® applications containing the Chat Protocol control or HTML pages that utilize the Chat Protocol control are referred to as chat clients. These chat clients communicate with a chat server through either the IRC (Internet Relay Chat) or IRCX (Extended Internet Relay Chat) protocols. The Chat Protocol control abstracts the IRC/IRCX protocols by the heavy use of objects and properties, thus insulating the developer from unnecessary knowledge of these protocols.

Because the Microsoft Chat Protocol Control 2.0 does not implement a user interface, developers are free to design and implement their own.

The Chat Protocol Control

Dependencies

Licensing and Distribution

Using the Chat Protocol Control

The Chat Protocol Control

The Chat Protocol control is an ActiveX control that can be hosted by Microsoft Visual Basic or Microsoft Visual C++ applications. Web authors can also insert the Chat Protocol 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. Web pages can be designed to query the user list, query the room lists, monitor the chat for specific events such as language type, notify when friends are online, and assign them specific privileges in a chat room.

Dependencies

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

Licensing and Distribution

The Chat Protocol 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 Protocol Control

To use the Chat Protocol control, you can either directly log on to the chat server, or connect to the server prior to logging on.

You can connect to the server first to determine what security packages are available on the server. The following method is used to do this.

object.Connect ServerName

The following method is used to log on to a chat server.

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

After logging on, you can add a Channel object to the Channels collection with the Add method. The Channels collection object is a standard Visual Basic collection object that uses the standard Add and Remove methods and the Item and Count properties.

Add method:

value=object.Add[(Index] [, Key)]

After the Channel object is created, you can join a channel with the JoinChannel or CreateChannel method. The CreateChannel method can be used only on an IRCX server.

JoinChannel method:

object.JoinChannel [ChannelName] [, ChannelKeyword]

CreateChannel method:

object.CreateChannel [ChannelName] [, ChannelKeyword] [, ChannelModes] [, MaxMemberCount]

Example

The following example adds Channel objects to the Channels collection with the Add method, and then joins the "Questions" Channel with the JoinChannel method:

Dim chan1, chan2 As Channel
Set chan1 = MsChatPr1.Channels.Add(1, "Questions")
Set chan2 = MsChatPr1.Channels.Add(2, "Answers")
MsChatPr1.Channels(1).JoinChannel "Questions"

All the channel methods and properties are available after the channel has been joined. For example, the SendMessage method sends text or data to the channel or a selective set of channel members.

object.SendMessage MessageType, Message [, RecipientNicknames] [, DataMessageTag]

Example

The following example sends a regular string to the channel.

MsChatPr1.Channels(1).SendMessage msgtNormal, "How are you?"

For incoming messages, the OnMessage event is fired. You can use this event to update the user interface of the chat client.

object_OnMessage(Channel, SenderNickname, MessageType, Message, RecipientNicknames, DataMessageTag)

To leave the channel, the LeaveChannel method closes the current channel.

object.LeaveChannel

The Remove method removes a Channel object from the Channels collection.

object.Remove Index

Querying the Server for Information

Information regarding the server, a channel, a user, or a member can be obtained asynchronously or synchronously.

The Chat Protocol control supports sophisticated querying by the use of the ChatItems object. These queries relate to the server, a channel, a user, or a member. Generally, the information provided by the server is exposed to you through a ChatItems object.

The following example shows how to construct a ChatItems object to query the server for all users whose nicknames start with the letter 'a'.

Dim UserQueryItems As ChatItems
Set UserQueryItems = New ChatItems
UserQueryItems.AssociatedType = "Query"
UserQueryItems.Item("Nickname") = "a"
UserQueryItems.Item("NicknameOp") = "StartsWith"
MsChatPr1.ListUsers UserQueryItems
Set UserQueryItems = Nothing

Note: Because VBScript does not have a New operator, you need to use the control's NewChatItems property to create a new ChatItems object. Therefore, in VBScript, the first two lines of the preceding example would be:

Dim UserQueryItems
Set UserQueryItems = MsChatPr1.NewChatItems

Information can also be queried synchronously using the object properties. However, the control will be blocked until the server returns the required information. If the server has not returned the required information within a customizable period, the control throws a time-out error and unblocks. If the server sends the information later, the information will be exposed to the user through an event. You can alter this time-out period through the PropertyAccessTimeOut property.

The OBJECT Tag for HTML Pages

The following example uses the OBJECT tag to implement the Chat Protocol control.

<OBJECT ID=MsChatPr1
STANDBY="Downloading the Microsoft Chat Protocol Control"
CODETYPE="application/x-oleobject"
CLASSID="CLSID:039397C0-46DF-11D0-99CB-00C04FD64497"
CODEBASE="MsChatPr.Cab">
</OBJECT>


Microsoft Chat Protocol Control 2.0 Visual Basic Reference (Beta1 Release)

This section provides a reference for the objects and the associated methods, properties, and events of the Microsoft® Chat Protocol Control 2.0.

Objects

MsChatPr Object

Channel Object

Channels Collection Object

ChatItems Object

Enumerations

Error Codes

Object Properties

Objects

The objects that comprise the Microsoft Chat Protocol Control 2.0 are:

  • MsChatPr
  • Channel
  • Channels
  • ChatItems


MsChatPr Object

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.

Properties of MsChatPr Object

ChannelProperty, Channels, ConnectionState, ConnectionType, ConvertedString, MaxStringLength, NewChatItems, Nickname, OpeningChannels, ProcessProtocolMessages, PropertyAccessTimeOut, ServerName, ServerProperty, UserProperty

Methods of MsChatPr Object

AboutBox, BanUsers, CancelConnectLogin, ChangeNickname, ChangeUserProperty, Connect, Disconnect, IgnoreUsers, KickUser, KillChannel, ListChannels, ListUsers, Login, QueryChannelProperty, QueryServerProperty, QueryUserProperty, SendInvitation, SendPrivateMessage, SendProtocolMessage, SetAway

Events of MsChatPr Object

OnAddMember, OnBeginEnumeration, OnChannelError, OnChannelProperty, OnChannelPropertyChanged, OnChannelState, OnConnectionError, OnConnectionState, OnDelMember, OnEndEnumeration, OnInvitation, OnKnock, OnMemberKicked, OnMemberProperty, OnMemberPropertyChanged, OnMessage, OnPrivateMessage, OnProtocolMessage, OnServerProperty, OnServerTextMessage, OnUserProperty, OnUserPropertyChanged


Properties

This section describes the properties associated with the MsChatPr object.

ChannelProperty Property

Channels Property

ConnectionState Property

ConnectionType Property

ConvertedString Property

MaxStringLength Property

NewChatItems Property

Nickname Property

OpeningChannels Property

ProcessProtocolMessages Property

PropertyAccessTimeOut Property

ServerName Property

ServerProperty Property

UserProperty Property


ChannelProperty Property

Synchronously accesses a channel property.

Syntax

value=object.ChannelProperty(ChannelPropertyName[, ChannelName])

Parameters

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.

Remarks

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.

Example

Dim chatitemobj As ChatItems
Set chatitemobj = MsChatPr1.ChannelProperty("Rating", "#MyRoom")
Set chatitemobj = MsChatPr1.ChannelProperty("Modes") 'There is only one open channel
Set chatitemobj = Nothing

See Also

OnUserProperty, PropertyAccessTimeOut, QueryChannelProperty


Channels Property

Returns the Channels collection of the control.

Syntax

value=object.Channels

Parameters

value | Required. An object expression that evaluates to a Channels object.
object | Required. An object expression that evaluates to an MsChatPr control.

Remarks

Access is read-only.

Example

Dim chancoll As Channels
Set chancoll = MsChatPr1.Channels


ConnectionState Property

Returns the current connection state of the control.

Syntax

value=object.ConnectionState

Parameters

value | Required. A variable of enumConnectionState type.
object | Required. An object expression that evaluates to an MsChatPr control.

Remarks

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.

Example

Dim cs As enumConnectionState
cs = MsChatPr1.ConnectionState

See Also

Connect, Disconnect, Login


ConnectionType Property

Returns the type of connection (IRC or IRCX) established with the chat server.

Syntax

value=object.ConnectionType

Parameters

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.

Remarks

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.

Example

Dim ct As enumConnectionType
ct = MsChatPr1.ConnectionType

See Also

Connect, Login, OnConnectionState


ConvertedString Property

Returns a converted version of the source string.

Syntax

value=object.ConvertedString(ConversionType, ConversionSource, Source, PostProcess)

Parameters

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" ','

Remarks

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û"


MaxStringLength Property

Returns the maximum length of some string properties.

Syntax

value=object.MaxStringLength(StringType)

Parameters

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

Remarks

Access is read-only.

Example

Dim lMaxMessageLen As Long
lMaxMessageLen = MsChatPr1.MaxStringLength(stServerMessage)


NewChatItems Property

Returns a newly allocated ChatItems object.

Syntax

value=object.NewChatItems

Parameters

value | Required. An object expression that evaluates to a ChatItems object.
object | Required. An object expression that evaluates to an MsChatPr control.

Remarks

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 ChatItems

Users must use the NewChatItems property instead, as in the following:

Dim chatitemobj
Set chatitemobj=MsChatPr1.NewChatItems
'...use chatitemobj
Set chatitemobj=Nothing  'releases chatitemobj

Dynamic allocation of a ChatItems object is necessary in order to perform some server queries, such as ListChannels or BanMembers.

Example

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


Nickname Property

Returns the control user's Nickname for the current connection, or an empty string if there is no live connection.

Syntax

value=object.Nickname

Parameters

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.

Remarks

Access is read-only.

Example

Dim strMyNickname As String
strMyNickname=MsChatPr1.Nickname
'or
Sub MsChatPr1_OnMemberKicked(Channel* Channel,
        BSTR KickedNickname,
        BSTR KickerNickname,
        BSTR Reason)
    If (KickedNickname = MsChatPr1.Nickname) Then
        MsgBox "You were kicked by " + KickerNickname + " because: " + Reason
    End If
End Sub


OpeningChannels Property

Returns the number of opening channels in the Channels collection.

Syntax

value=object.OpeningChannels

Parameters

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.

Remarks

Access is read-only.

Example

Dim lOpeningChannels As Long
MsChatPr1.Channels.Add
MsChatPr1.Channels.JoinChannel "#Foo"
lOpeningChannels = MsChatPr1.OpeningChannels	'returns 1


ProcessProtocolMessages Property

Determines whether the OnProtocolMessage event is fired for each incoming server message.

Syntax

object.ProcessProtocolMessages=value

Parameters

object | Required. An object expression that evaluates to an MsChatPr control.
value | Required. A Boolean value.

Remarks

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.

Example

MsChatPr1.ProcessProtocolMessages = False


PropertyAccessTimeOut Property

Reads or writes the time-out value when synchronously accessing a property.

Syntax

object.PropertyAccessTimeOut=value

Parameters

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.

Remarks

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.

Example

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 = Nothing

In 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")

See Also

ChannelProperty, MemberProperty, OnChannelProperty, OnMemberProperty, OnUserProperty, OnServerProperty, ServerProperty


ServerName Property

Returns the server name of the current connection, or an empty string if there is no live connection.

Syntax

value=object.ServerName

Parameters

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.

Remarks

Access is read-only.

Example

Dim strServerName As String
strServerName = MsChatPr1.ServerName


ServerProperty Property

Synchronously accesses a server property.

Syntax

value.object.ServerProperty(ServerPropertyName)

Parameters

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

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

Synchronously accesses a user property.

Syntax

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

Parameters

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

BanUsers Method

CancelConnectLogin Method

ChangeNickname Method

ChangeUserProperty Method

Connect Method

Disconnect Method

IgnoreUsers Method

KickUser Method

KillChannel Method

ListChannels Method

ListUsers Method

Login Method

QueryChannelProperty Method

QueryServerProperty Method

QueryUserProperty Method

SendInvitation Method

SendPrivateMessage Method

SendProtocolMessage Method

SetAway Method


AboutBox Method

Displays the About message dialog box.

Syntax

object.AboutBox

Parameters

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


BanUsers Method

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

Syntax

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

Parameters

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

Cancels a Connect or Login call.

Syntax

object.CancelConnectLogin

Parameters

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

Asynchronously changes the user's Nickname.

Syntax

object.ChangeNickname NewNickname

Parameters

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

Asynchronously modifies a user property.

Syntax

object.ChangeUserProperty UserPropertyName, NewUserProperty[, Nickname]

Parameters

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

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

Syntax

object.Connect ServerName

Parameters

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

Disconnects from the chat server.

Syntax

object.Disconnect

Parameters

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

Allows the caller to ignore or stop ignoring users.

Syntax

object.IgnoreUsers UserItems, Set

Parameters

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

Disconnects a user from the server.

Syntax

object.KickUser Nickname[, Reason]

Parameters

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

Terminates a channel on the server.

Syntax

object.KillChannel ChannelName[, Reason]

Parameters

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

Lists channels on the chat server.

Syntax

object.ListChannels ChannelQueryItems

Parameters

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


ListUsers Method

Lists users on the server.

Syntax

object.ListUsers UserQueryItems

Parameters

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 "Re":

Dim chatitemobj As ChatItems
Set chatitemobj = New ChatItems
chatitemobj.AssociatedType = "Query"
chatitemobj.Item("MaskOp") = "StartsWith"
chatitemobj.Item("Mask") = "Re"
MsChatPr1.ListUsers chatitemobj
Set chatitemobj = Nothing


Login Method

Logs a user on to the chat server.

Syntax

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

Parameters

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"

See Also

Connect, Disconnect


QueryChannelProperty Method

Asynchronously accesses a channel property.

Syntax

object.QueryChannelProperty ChannelPropertyName[, ChannelName]

Parameters

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

Asynchronously accesses a server property.

Syntax

object.QueryServerProperty ServerPropertyName

Parameters

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, and Name properties. The state must be at least csLogged to access all other server properties.

Example

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

See Also

ItemValid


QueryUserProperty Method

Asynchronously accesses a user property.

Syntax

object.QueryUserProperty UserPropertyName[, Nickname]

Parameters

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

Invites a user to a channel.

Syntax

object.SendInvitation Nickname[, ChannelName]

Parameters

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

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

Syntax

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

Parameters

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

Sends a text message directly to the server.

Syntax

object.SendProtocolMessage TextMessage

Parameters

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

Sets and resets the Away flag and away message.

Syntax

object.SetAway Away[, TextMessage]

Parameters

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


Events

This section describes the events associated with the MsChatPr object.

OnAddMember Event

OnBeginEnumeration Event

OnChannelError Event

OnChannelProperty Event

OnChannelPropertyChanged Event

OnChannelState Event

OnConnectionError Event

OnConnectionState Event

OnDelMember Event

OnEndEnumeration Event

OnInvitation Event

OnKnock Event

OnMemberKicked Event

OnMemberProperty Event

OnMemberPropertyChanged Event

OnMessage Event

OnPrivateMessage Event

OnProtocolMessage Event

OnServerProperty Event

OnServerTextMessage Event

OnUserProperty Event

OnUserPropertyChanged Event


OnAddMember Event

Fires when entering a channel or when a new member joins an open channel.

Syntax

object_OnAddMember(Channel, Nickname, MemberItems)

Parameters

object | Required. An object expression that evaluates to an MsChatPr control.
Channel | Required. An object expression that evaluates to a Channel object.
Nickname | Required. A string expression that contains the user's Nickname.
MemberItems | Required. An object expression that evaluates to a ChatItems object.

Remarks

When entering a channel, the control user receives the initial member list through OnAddMember events. One OnAddMember event also occurs for each incoming new member.


OnBeginEnumeration Event

Fires at the beginning of an enumeration, when entering a channel or listing users, members, or channels.

Syntax

object_OnBeginEnumeration(Channel, EnumType)

Parameters

object | Required. An object expression that evaluates to an MsChatPr control.
Channel | Required. An object expression that evaluates to a Channel object.
EnumType | Required. A variable of enumEnumType type.

See Also

CreateChannel, ListChannels, ListUsers


OnChannelError Event

Fires when an asynchronous error related to a channel occurs.

Syntax

object_OnChannelError(Channel, ErrorCode, Description)

Parameters

object | Required. An object expression that evaluates to an MsChatPr control.
Channel | Required. An object expression that evaluates to a Channel object.
ErrorCode | Required. A long integer value that indicates the channel error code.
Description | Required. A string expression that contains the description of the error.

See Also

CreateChannel


OnChannelProperty Event

Fires after a ListChannels or QueryChannelProperty call.

Syntax

object_OnChannelProperty(Channel, ChannelItems)

Parameters

object | Required. An object expression that evaluates to an MsChatPr control.
Channel | Required. An object expression that evaluates to a Channel object.
ChannelItems | Required. An object expression that evaluates to a ChatItems object.

Remarks

This event can also be fired after a time-out occurs while accessing a ChannelProperty property.


OnChannelPropertyChanged Event

Fires when a channel property changes, such as after calling ChangeChannelProperty.

Syntax

object_OnChannelPropertyChanged(Channel, ModifierNickname, ChannelPropertyName, OldChannelProperty, NewChannelProperty)

Parameters

object | Required. An object expression that evaluates to an MsChatPr control.
Channel | Required. An object expression that evaluates to a Channel object.
ModifierNickname | Required. A string expression containing the modifier nickname.
ChannelPropertyName | Required. A string expression containing the name of the channel property that changed.
OldChannelProperty | Required. A variant, the type of which depends on the old channel property.
NewChannelProperty | Required. A variant, the type of which depends on the new channel property.

See Also

ChangeChannelProperty


OnChannelState Event

Fires after a CreateChannel, JoinChannel, or LeaveChannel call or after an asynchronous event, such as being kicked out of the room or being disconnected.

Syntax

object_OnChannelState(Channel, NewChannelState)

Parameters

object | Required. An object expression that evaluates to an MsChatPr control.
Channel | Required. An object expression that evaluates to a Channel object.
NewChannelState | Required. A short integer of enumChannelState type.

See Also

CreateChannel, JoinChannel, LeaveChannel


OnConnectionError Event

Fires when an asynchronous error occurs.

Syntax

object_OnConnectionError(ErrorCode, Description, ChannelName)

Parameters

object | Required. An object expression that evaluates to an MsChatPr control.
ErrorCode | Required. A long integer containing the value of the error code.
Description | Required. A string expression containing the description of the error code.
ChannelName | Required. A variant, the type of which depends on the name of the channel.


OnConnectionState Event

Fires after Connect, Login, CancelConnectLogin, and Disconnect calls or when an asynchronous disconnection occurs.

Syntax

object_OnConnectionState(NewConnectionState)

Parameters

object | Required. An object expression that evaluates to an MsChatPr control.
NewConnectionState | Required. A variable of enumConnectionState type.

Example

Dim NewConnectionState As enumConnectionState
NewConnectionState = MsChatPr1.ConnectionState


OnDelMember Event

Fires when a member leaves an open channel or is kicked out of the channel.

Syntax

object_OnDelMember(Channel, Nickname)

Parameters

object | Required. An object expression that evaluates to an MsChatPr control.
Channel | Required. An object expression that evaluates to a Channel object.
Nickname | Required. A string expression that contains the Nickname of the user who is leaving the channel.

See Also

KickMember, OnMemberKicked


OnEndEnumeration Event

Fires at the end of an enumeration, when entering a channel or listing users, members, or channels.

Syntax

object_OnEndEnumeration(Channel, EnumType)

Parameters

object | Required. An object expression that evaluates to an MsChatPr control.
Channel | Required. An object expression that evaluates to a Channel object.
EnumType | Required. A variable of enumEnumType type.

See Also

CreateChannel, ListChannels, ListUsers


OnInvitation Event

Fires when the control user is invited to a channel.

Syntax

object_OnInvitation(ChannelName, InviterItems)

Parameters

object | Required. An object expression that evaluates to an MsChatPr control.
ChannelName | Required. A string expression that represents the channel to which the user is invited.
InviterItems | Required. An object expression that evaluates to a ChatItems object. Gives all the known information about the user who is performing the inviting.

See Also

SendInvitation


OnKnock Event

Fires when a user failed to enter a channel.

Syntax

object_OnKnock(Channel, KnockerItems, ErrorCode)

Parameters

object | Required. An object expression that evaluates to an MsChatPr control.
Channel | Required. An object expression that evaluates to a Channel object.
KnockerItems | Required. An object expression that evaluates to a ChatItems object.
ErrorCode | Required. A long integer value that indicates why the user could not join the channel. Examples are that the channel is full, the channel is invite-only, or a channel Keyword is set.

Remarks

Only the hosts of the channel receive this notification. Also, the notification occurs only if the cmKnock flag is set for that channel.


OnMemberKicked Event

Fires when a member is kicked out of the channel.

Syntax

object_OnMemberKicked(Channel, KickedNickname, KickerNickname, Reason)

Parameters

object | Required. An object expression that evaluates to an MsChatPr control.
Channel | Required. An object expression that evaluates to a Channel object.
KickedNickname | Required. A string expression containing the Nickname of the member who is being kicked.
KickerNickname | Required. A string expression containing the Nickname of the member who is doing the kicking.
Reason | Required. A string expression containing the reason the member is being kicked, or it can be empty.

Remarks

This event can result from a KickMember method call and is immediately followed by an OnDelMember event.


OnMemberProperty Event

Fires after a ListMembers or QueryMemberProperty call.

Syntax

object_OnMemberProperty(Channel, MemberItems)

Parameters

object | Required. An object expression that evaluates to an MsChatPr control.
Channel | Required. An object expression that evaluates to a Channel object.
MemberItems | Required. An object expression that evaluates to a ChatItems object.

Remarks

This event can also be fired after a time-out occurs while accessing the MemberProperty property.


OnMemberPropertyChanged Event

Fires when a member property changes, such as after a ChangeMemberProperty or ChangeNickname call.

Syntax

object_OnMemberPropertyChanged(Channel, ModifiedNickname, ModifierNickname, MemberPropertyName, OldMemberProperty, NewMemberProperty)

Parameters

object | Required. An object expression that evaluates to an MsChatPr control.
Channel | Required. An object expression that evaluates to a Channel object.
ModifiedNickname | Required. A string expression containing the Nickname of the member that is being modified.
ModifierNickname | Required. A string expression containing the Nickname of the modifier.
MemberPropertyName | Required. A string containing a valid member property name value. Can be Modes or Nickname.
OldMemberProperty | Required. A variant, the data type of which is dependent on the old member property.
NewMemberProperty | Required. A variant, the data type of which is dependent on the new member property.

See Also

MemberProperty, QueryMemberProperty


OnMessage Event

Fires when a member sends a message to the channel or members of the channel including the control user.

Syntax

object_OnMessage(Channel, SenderNickname, MessageType, Message, RecipientNicknames, DataMessageTag)

Parameters

object | Required. An object expression that evaluates to an MsChatPr control.
Channel | Required. An object expression that evaluates to a Channel object.
SenderNickname | Required. A string expression that contains the Nickname of the sender.
MessageType | Required. A long integer of enumMessageType type.
Message Required. A variant. When the data message is received and the msgtDataRaw flag is not set, the Message parameter can be a number, a string, an array of numbers, an array of strings, or an array of variants that are strings or numbers. This is exactly like the Message parameter used in the SendMessage method.

However, when the msgtDataRaw flag is set, the Message parameter is an array of these three variants:
Message[0] | The postprocessed string that represents the array of bytes received.
Message[1] | An array of bytes.
Message[2] | An array of variants that are bytes.

RecipientNicknames Required. An array of variants that are strings when the incoming message is a whisper (that is, that originates from the SendMessage call that uses the msgtWhisper type).

RecipientNicknames is a string containing the user's nickname when the message is a multicasted data message (that is, a data message that was sent to one or more channel members including the control user). This differentiates the data messages that were sent to the channel where RecipientNicknames is an empty variant and those that were sent to channel member(s). RecipientNicknames is an empty variant in all other cases.

DataMessageTag | Required. A variant. Empty when the Message parameter is a string, and must be a string expression when Message is data.


OnPrivateMessage Event

Fires when a user sends a private message to the control user.

Syntax

object_OnPrivateMessage(SenderNickname, PrivateMessageType, Message, DataMessageTag)

Parameters

object | Required. An object expression that evaluates to an MsChatPr control.
SenderNickname | Required. A string expression containing the Nickname of the sender.
PrivateMessageType | Required. A long integer.
Message Required. A variant. When a data message is received and the pmtDataRaw flag is not set, the Message parameter can be a number, a string, an array of numbers, an array of strings, or an array of variants that are strings or numbers. This is exactly like the Message parameter used in the SendPrivateMessage method.

However, when the pmtDataRaw flag is set, the Message parameter is an array of these three variants:
Message[0] | The postprocessed string that represents the array of bytes received.
Message[1] | An array of bytes.
Message[2] | An array of variants that are bytes.

DataMessageTag | Required. A variant. This parameter is empty when the Message parameter is a string, and is a string when Message is data.


OnProtocolMessage Event

Fires for any incoming server message when the ProcessProtocolMessages property is set to FALSE.

Syntax

object_OnProtocolMessage(MessagePrefix, MessageCommand, MessageParameters, EnableDefault)

Parameters

object | Required. An object expression that evaluates to an MsChatPr control.
MessagePrefix | Required. A string expression.
MessageCommand | Required. A string expression.
MessageParameters | Required. An array of string variants.
EnableDefault | Required. An OLE_ENABLEDEFAULTBOOL.

Remarks

If the ProcessProtocolMessages property is set to TRUE, this event is fired for incoming messages that are not internally treated by the control.


OnServerProperty Event

Fires after a QueryServerProperty call.

Syntax

object_OnServerProperty(ServerItems)

Parameters

object | Required. An object expression that evaluates to an MsChatPr control.
ServerItems | Required. An object expression that evaluates to a ChatItems object.

Remarks

This event can also be fired after a time-out occurs while accessing the ServerProperty property.

See Also

ItemValid


OnServerTextMessage Event

Fires for incoming server text messages.

Syntax

object_OnServerTextMessage(ServerMessageType, Text)

Parameters

object | Required. An object expression that evaluates to an MsChatPr control.
ServerMessageType | Required. A variable of enumServerMessageType type.
Text | Required. A string expression that contains the text message.


OnUserProperty Event

Fires after a ListUsers or QueryUserProperty call.

Syntax

object_OnUserProperty(UserItems)

Parameters

object | Required. An object expression that evaluates to an MsChatPr control.
UserItems | Required. An object expression that evaluates to a ChatItems object.

Remarks

This event can also be fired after a time-out occurs while accessing the UserProperty property.


OnUserPropertyChanged Event

Fires when a user property changes.

Syntax

object_OnUserPropertyChanged(ModifiedNickname, ModifierNickname, UserPropertyName, OldUserProperty, NewUserProperty)

Parameters

object | Required. An object expression that evaluates to an MsChatPr control.
ModifiedNickname | Required. A string expression that contains the Nickname being modified.
ModifierNickname | Required. A string expression that contains the Nickname of the modifier, or it can be empty.
UserPropertyName | Required. A variant, the type of which depends on the user property name.
OldUserProperty | Required. A variant, the type of which depends on the old user property.
NewUserProperty | Required. A variant, the type of which depends on the new user property.

Remarks

This event can occur after calling ChangeUserProperty or ChangeNickname, for example.


Channel Object

After logging in to a chat server, the Channel object is added to the Channels collection with the Add method.

This section lists the methods and properties supported by the Channel object.

Properties

ChannelName, ChannelProperty, ChannelState, ChannelTopic, Index, MemberCount, MemberIdentity, MemberModes, MemberProperty

Methods

BanMembers, ChangeChannelProperty, ChangeMemberProperty, CreateChannel, JoinChannel, KickMember, LeaveChannel, ListMembers, QueryChannelProperty, QueryMemberProperty, SendInvitation, SendMessage


Properties

This section describes the properties associated with the Channel object.

ChannelName Property

ChannelProperty Property

ChannelState Property

ChannelTopic Property

Index Property

MemberCount Property

MemberIdentity Property

MemberModes Property

MemberProperty Property


ChannelName Property

Synchronously reads or writes the Name of the channel.

Syntax

value=object.ChannelName

Parameters

value | Required. A string containing the Name of the channel.
object | Required. An object expression that evaluates to a Channel object.

Remarks

Access is read/write or read-only depending on the ChannelState value:

  • If the ChannelState is chsClosed, the property is read/write.
  • If the ChannelState is chsOpening or chsOpen, the property is read-only.
  • If the ChannelName property is set while the channel is closed, the CreateChannel and JoinChannel methods use its value if their ChannelName parameter is not specified.

After joining a channel, the ChannelName property is not necessarily the string you specified in CreateChannel, JoinChannel, or ChannelName because of the cloned channels.

For example, you could call:

MsChatPr1.Channels(1).JoinChannel "#Chat"

and, in fact, join "#Chat3", which will be the value returned by the ChannelName property.

The ChannelName property is not cleared when the user leaves the channel and the ChannelState becomes chsClosed.

The user can also synchronously get the channel Name using:

<channel>.ChannelProperty("Name")

But the ChannelName property is simpler and more efficient.

The asynchronous method of accessing the channel Name is:

<channel>.QueryChannelProperty "Name"

See Also

CreateChannel, ChannelProperty, JoinChannel, QueryChannelProperty


ChannelProperty Property

Synchronously accesses a channel property.

Syntax

value=object.ChannelProperty(ChannelPropertyName)

Parameters

value | Required. An object expression that evaluates to a ChatItems object.
object | Required. An object expression that evaluates to Channel object.
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
CloneList MemberCount
CreationTime Modes
HostKey Name
Lag Topic
Language
ObjectId
OnJoin
OnPart
OwnerKey
Rating
ServicePath
Subject

Remarks

Access is read-only.

When the client asks for this property, the server might return more information than was requested. Because of this, all answers are packaged into a ChatItems object and exposed to the caller.

Generally, all the information known by the client at the time of the ChannelProperty call is exposed to the caller in the ChatItems object.

The ChannelState must be chsOpen for the ChannelProperty property access to succeed.

Example

The following are asynchronous methods of accessing a channel property.

<channel>.QueryChannelProperty <ChannelPropertyName>
'and
<control>.QueryChannelProperty <ChannelPropertyName>, <ChannelName>

See Also

ChannelName, QueryChannelProperty


ChannelState Property

Returns the current channel state of the control.

Syntax

value=object.ChannelState

Parameters

value | Required. A variable of enumChannelState type.
object | Required. An object expression that evaluates to a Channel object.

Remarks

Access is read-only.

At creation, the state of a channel is chsClosed. When calling its JoinChannel or CreateChannel method, the state becomes asynchronously chsOpening and chsOpen. It becomes chsClosed again when the user leaves the channel or is kicked from the channel, or when a server disconnection occurs.

If the Channel object is removed from the collection, attempts to access any of its properties or methods will cause an occurrence of the Channels collection error 3172, "The channel is no more part of the collection."

The asynchronous channel state changes are exposed through the OnChannelState event.


ChannelTopic Property

Synchronously reads the Topic of the channel.

Syntax

value=object.ChannelTopic

Parameters

value | Required. A string expression that contains the Topic of the channel.
object | Required. An object expression that evaluates to a Channel object.

Remarks

Access is read-only.

The ChannelTopic property is not cleared when the user leaves the channel and the channel state becomes chsClosed.

The user can also synchronously get the Topic of the channel by using:

<channel>.ChannelProperty("Topic")
'or
<control>.ChannelProperty("Topic", <channelname>)

But the ChannelTopic property is simpler and more efficient.

The asynchronous methods to access the Topic of the channel are:

<channel>.QueryChannelProperty "Topic"
'and
<control>.QueryChannelProperty "Topic", <channelname>

See Also

ChannelProperty, QueryChannelProperty


Index Property

Uniquely identifies the Channel object in the Channels collection.

Syntax

value=object.Index

Parameters

value | Required. A long integer that will receive the index of the Channel object.
object | Required. An object expression that evaluates to a Channel object.

Remarks

Access is read-only.

The index of a channel is not fixed; it can vary during the lifetime of the object. If a channel with a smaller index is removed from the collection, the index is decremented. If a channel with a smaller or equal index is added to the collection, the index is incremented.

Example

Dim lIndex As Long
Set c=MsChatPr1.Channels.Add(1, "Key1")
lIndex=chanobj.Index    'lIndex now contains 1
MsChatPr1.Channels.Add 1, "Key2"
lIndex=chanobj.Index    'lIndex now contains 2

See Also

Add, Item, Remove


MemberCount Property

Synchronously returns the current number of members in the channel.

Syntax

value=object.MemberCount

Parameters

value | Required. A long integer that will receive the current number of members in the channel.
object | Required. An object expression that evaluates to a Channel object.

Remarks

Access is read-only.

If the Channel object is not open, attempts to access its MemberCount property will cause an occurrence of the Channel Error 3062, "The channel is not open."

Examples

The user can also synchronously obtain the member count of the channel by using:

ChannelProperty("MemberCount")

But the MemberCount property is simpler and more efficient.

The asynchronous methods of accessing the member count of the channel are:

&lt:channel>.QueryChannelProperty "MemberCount"
'and
&lt:control>.QueryChannelProperty "MemberCount", &lt:channelname>

See Also

ChannelProperty, QueryChannelProperty


MemberIdentity Property

Synchronously accesses the Identity of a channel member.

Syntax

value.object.MemberIdentity [MemberNickname]

Parameters

value | Required. A string expression containing the Identity of a member.
object | Required. An object expression that evaluates to a Channel object.
MemberNickname | Optional. A variant. When specified, the variant must be a string and represent the nickname of a channel member. If not specified, the Identity of the caller is returned.

Remarks

Access is read-only.

The member's Identity is composed of the member's UserName and IPAddress separated by the @ sign.

Examples

RegisB@REGISB1.dns.microsoft.com
RegisB@zorg.microsoft.com

The Identity of a member is fixed. The identity cannot vary, unlike a member's Nickname.

The user can also synchronously get a member's Identity by using:

<channel>.MemberProperty("Identity", <nickname>)

But the MemberIdentity call is simpler and more efficient.

The asynchronous method to access a member's identity is:

<channel>.QueryMemberProperty "Identity", <nickname>

See Also

MemberProperty, Nickname, QueryMemberProperty


MemberModes Property

Synchronously accesses a channel member's Modes.

Syntax

value=object.MemberModes[, MemberNickname]

Parameters

value | Required. A variable of enumMemberMode type.
object | Required. An object expression that evaluates to a Channel object.
MemberNickname | Optional. A variant. When specified, the variant must be a string and represent the nickname of a channel member. If not specified, the Modes of the caller are returned.

Remarks

Access is read-only.

The member modes expose eight Booleans, each Boolean taking two values that are mutually exclusive. For example, the mmClientIgnored and mmNotClientIgnored values are mutually exclusive.

If the MemberModes property returns 0x000AA41 = mmClientIgnored + mmAway + mmNotSysop + mmNotOwner + mmNotHost + mmNoVoice, the control is certain that this member is ignored by the caller, currently away, not a system operator, not a channel host, and has no voice.

However, in this example, because mmAuthMember and mmNotAuthMember are not part of the returned modes, the control is not aware of member authentication.

See Also

Nickname


MemberProperty Property

Synchronously accesses a channel member's property.

Syntax

value=object.MemberProperty MemberPropertyName[, MemberNickname]

Parameters

value | Required. An object expression that evaluates to a ChatItems object.
object | Required. An object expression that evaluates to a Channel object.
MemberPropertyName | Required. A string containing a valid member property name value.
MemberNickname | Optional. A variant. When specified, the variant must be a string and represent the nickname of a channel member. If not specified, the property of the caller is returned.

Remarks

Access is read-only.

See Also

Nickname


Methods

This section describes the methods associated with the Channel object.

BanMembers Method

ChangeChannelProperty Method

ChangeMemberProperty Method

CreateChannel Method

JoinChannel Method

KickMember Method

LeaveChannel Method

ListMembers Method

QueryChannelProperty Method

QueryMemberProperty Method

SendInvitation Method

SendMessage Method


BanMembers Method

Bans a member(s) and reinstates a member(s).

Syntax

object.BanMembers MemberItems, Set

Parameters

object | Required. An object expression that evaluates to a Channel object.
MemberItems Required. An object expression that evaluates to a ChatItems object. Specifies which members are to be banned or reinstated. The valid item names for constructing the MemberItems object are:
IPAddress
IPAddressOp
Nickname
NicknameOp
UserName
UserNameOp
Set | Required. A Boolean variable. This parameter must be TRUE to ban the member from the channel, or FALSE to reinstate the member to the channel.

Examples

1. Ban all the users with an IP address that ends with ".net":

Dim mi As ChatItems
Set mi = New ChatItems
mi.AssociatedType = "Query"
mi.Item("IPAddressOp") = "EndsWith"
mi.Item("IPAddress") = ".net"
chan.BanMembers mi, True
Set mi = Nothing

2. Ban all the users with the username "ProutZ":

Dim mi As ChatItems
Set mi = New ChatItems
mi.AssociatedType = "Query"
mi.Item("UserName") = "ProutZ"
chan.BanMembers mi, True
Set mi = Nothing

3. Reinstate all the users with a username that contains "regis" and an IP address that starts with "ms":

Dim mi As ChatItems
Set mi = New ChatItems
mi.AssociatedType = "Query"
mi.Item("UserNameOp") = "Contains"
mi.Item("UserName") = "regis"
mi.Item("IPAddressOp") = "StartsWith"
mi.Item("IPAddress") = "ms"
chan.BanMembers mi, False
Set mi = Nothing

See Also

NewChatItems


ChangeChannelProperty Method

Asynchronously modifies a channel property.

Syntax

object.ChangeChannelProperty ChannelPropertyName, NewChannelProperty

Parameters

object | Required. An object expression that evaluates to a Channel object.
ChannelPropertyName Required. A string expression. The following table shows the valid channel property names.
IRCX | IRC/IRCX
protocol only | protocols
Account Keyword
ClientData MaxMemberCount
ClientGuid Modes
HostKey Topic
Language
Lag
OnJoin
OnPart
OwnerKey
Rating
ServicePath
Subject
NewChannelProperty | Required. A variant, the type of which depends on the new channel property.

Remarks

A successful call results in an OnChannelPropertyChanged event.

Examples

chanobj.ChangeChannelProperty "HostKey", "SecretHost"
chanobj.ChangeChannelProperty "Lag", 2
chanobj.ChangeChannelProperty "Modes", cmPublic + cmKnock + cmTopicop

See Also

enumChannelMode, OnChannelPropertyChanged


ChangeMemberProperty Method

Asynchronously changes a member property.

Syntax

object.ChangeMemberProperty MemberPropertyName, NewMemberProperty[, MemberNickname]

Parameters

object | Required. An object expression that evaluates to a Channel object.
MemberPropertyName | Required. A string expression. The only valid member property name value is "Modes".
NewMemberProperty Required. A variant. This property must represent a valid member Modes value. A valid member modes value is a combination of these enumMemberMode values:
mmClientIgnored | = &H1.
mmNotClientIgnored | = &H2.
mmOwner | = &H100.
mmNotOwner | = &H200.
mmHost | = &H400.
mmNotHost | = &H800.
mmVoice | = &H1000.
mmNoVoice | = &H2000.
MemberNickname | Optional. If specified, it must be an empty variant or a valid channel member nickname. If omitted or empty, the nickname of the caller is used.

Remarks

A successful call results in an OnMemberPropertyChanged event.

Examples

1. Change your own modes (giving up your host privileges in the channel):

chan1.ChangeMemberProperty "Modes", mmNotHost

2. Change another user's member modes (turning a member into a host):

chan1.ChangeMemberProperty "Modes", mmHost, "JamesB"

3. Ignore a member:

chan1.ChangeMemberProperty "Modes", mmClientIgnored, "AustinP"

Note You cannot ignore a channel host or owner, or a server system operator or administrator.


CreateChannel Method

Creates a channel on IRCX servers only.

Syntax

object.CreateChannel [ChannelName][, ChannelKeyword][, ChannelModes][, MaxMemberCount]

Parameters

object | Required. An object expression that evaluates to a Channel object.
ChannelName | Optional. A variant. If specified, must be empty or contain a valid channel Name. If the parameter is empty or not specified, the current value of the ChannelName property is used instead.
ChannelKeyword | Optional. A variant. If specified, must be empty or a string. If the parameter is empty or not specified, the channel will be created with no Keyword set.
ChannelModes Optional. A variant. If specified, must be empty or a number (integer or long) that is a valid channel Modes value. A valid ChannelModes parameter is a combination of some of the values from the enumChannelMode enumeration. The valid components of a ChannelModes value are:
cmPublic | &H0.
cmPrivate | &H1.
cmHidden | &H2.
cmSecret | &H4.
cmModerated | &H8.
cmNoExtern | &H10.
cmTopicop | &H20.
cmInvite | &H40.
cmKnock | &H80.
cmNoWhisper | &H100.
cmService | &H400.
cmAuthOnly | &H800.
cmCloneable | &H1000.
cmAuditorium | &H4000.
cmNoFormat | &H8000.
cmCreateOnly | &H10000000.

The cmPrivate, cmHidden, and cmSecret values are mutually exclusive. If the cmCreateOnly flag is set, the CreateChannel call will fail if the channel already exists. If this flag is not set, the caller will join the channel if it already exists.

If the ChannelModes parameter is empty or not specified, the channel Modes value will be defined by the server's default settings.

MaxMemberCount | Optional. A variant. If specified, the MaxMemberCount parameter must be empty or a number (integer or long) that is a valid maximum member count. If the parameter is empty or not specified, the maximum member count of the channel will be defined by the server's default settings.

Remarks

The channel state must be chsClosed for the call to succeed, and the channel must belong to the collection for the call to be successful.

A successful CreateChannel calls results in an OnChannelState event in which the channel state is chsOpening, then an OnChannelState event is fired with the channel state chsClosed or the following suite of events.
Event | Parameters
OnChannelState | (Channel, chsOpening)
OnChannelState | (Channel, chsOpen)
OnBeginEnumeration | (Channel, etInitialMembers)
OnAddMember | (Channel, Nickname, MemberItems)
OnEndEnumeration | (Channel, etInitialMembers)
OnChannelProperty | (Channel, ChannelItems)

Examples

1. Specify all the parameters:

MsChatPr1.Channels(1).CreateChannel "#MyRoom", "SecretPassword", cmTopicop +  cmCreateOnly, 20

2. Omit the ChannelKeyword and MaxMemberCount parameters:

MsChatPr1.Channels(1).CreateChannel "#MyRoom", , cmCreateOnly

3. Use empty variants:

MsChatPr1.Channels(1).CreateChannel "#MyRoom", Empty,
cmCreateOnly, Empty

See Also

ChannelName, ChannelState, enumChannelMode, JoinChannel, OnChannelState


JoinChannel Method

Allows the user to join an existing channel or create a new channel.

Syntax

object.JoinChannel [ChannelName][, ChannelKeyword]

Parameters

object | Required. An object expression that evaluates to a Channel object.
ChannelName | Optional. A variant that contains the Name of the channel. If specified, the ChannelName variant must be empty or a string that is a valid channel Name. If the parameter is empty or not specified, the current value of the ChannelName property is used instead.
ChannelKeyword | Optional. A variant. If specified, this variant must be empty or a string. If the parameter is empty or not specified, the control tries to join the channel without using a Keyword.

Remarks

The channel state must be chsClosed for the call to succeed, and the channel must belong to the collection for the call to be successful.

A JoinChannel call results in the same kind of events as a CreateChannel call.

At creation time, the state of the created channel is chsClosed. Then, when calling its JoinChannel or CreateChannel method, the state becomes asynchronously chsOpening and chsOpen. It becomes chsClosed again when the user leaves the channel or is kicked from the channel, or when a server disconnection occurs.

Example

'Specifies the ChannelName and ChannelKeyword
MsChatPr1.Channels(lIndex).JoinChannel "#MyRoom", "SecretPassword"
'Specifies only the ChannelName
MsChatPr1.Channels(lIndex).JoinChannel "#MyRoom"

See Also

ChannelName, ChannelState, enumChannelState, OnChannelState, OpeningChannels


KickMember Method

Kicks a member from the channel.

Syntax

object.KickMember MemberNickname[, Reason]

Parameters

object | Required. An object expression that evaluates to a Channel object.
MemberNickname | Required. A string expression that must be a valid member nickname from the channel.
Reason | Optional. A string expression containing the reason for kicking the user from the channel.

Example

MsChatPr1.Channels(2).KickMember "WadeR", "Bad behavior!"
chan11.KickMember "WadeR"

See Also

Nickname, OnMemberKicked


LeaveChannel Method

Closes the current channel.

Syntax

object.LeaveChannel

Parameters

object Required. An object expression that evaluates to a Channel object.

Remarks

The channel state must be chsOpen for the call to be successful.

Leaving a channel does not remove it from the Channels collection. The user can reuse the same Channel object to join and leave several channels sequentially.

A successful LeaveChannel call results in an OnChannelState event.

Example

MsChatPr1.Channels(iIndex).LeaveChannel

See Also

JoinChannel


ListMembers Method

Lists the members of the channel.

Syntax

object.ListMembers MemberQueryItems

Parameters

object Required. An object expression that evaluates to a Channel object.
MemberQueryItems Required. An object expression that evaluates to a ChatItems object.

The MemberQueryItems parameter is currently unused. It is present for backward compatibility in the future.

Remarks

Future releases of the protocol might include some method of narrowing the member listing. In this case the MemberQueryItems parameter would come into use. Currently neither the IRC nor the IRCX protocols offer any member-listing criteria.

Example

Dim mqi As ChatItems
chan.ListMembers mqi

See Also

OnMemberProperty, QueryMemberProperty


QueryChannelProperty Method

Asynchronously accesses a channel property.

Syntax

object.QueryChannelProperty ChannelPropertyName

Parameters

object Required. An object expression that evaluates to a Channel object.
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
CloneList MemberCount
CreationTime Modes
HostKey Name
Lag Topic
Language
ObjectId
OnJoin
OnPart
OwnerKey
Rating
ServicePath
Subject

Remarks

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

Examples

chan.QueryChannelProperty "Account"
chan.QueryChannelProperty "MaxMemberCount"

See Also

ChannelName, ListChannels, MemberCount


QueryMemberProperty Method

Asynchronously requests a member property.

Syntax

object.QueryMemberProperty MemberPropertyName[, MemberNickname]

Parameters

object | Required. An object expression that evaluates to a Channel object.
MemberPropertyName Required. A string containing one of the following valid member property name values.
Identity
IPAddress
Modes
Nickname
ObjectId (IRCX protocol only)
UserName
MemberNickname | Optional. A string expression. If specified, this parameter must be an empty variant or a valid channel member nickname. If omitted or empty, the nickname of the caller is used.

Remarks

A successful call results in an OnMemberProperty event where the MemberItems parameter exposes all the known member properties.

Examples

MsChatPr1.Channels.Item(3).QueryMemberProperty "Identity", "DerrickL"
MsChatPr1.Channels.Item(3).QueryMemberProperty "Modes"

See Also

enumMemberMode, MemberIdentity, MemberProperty


SendInvitation Method

Invites a user to the channel.

Syntax

object.SendInvitation Nickname

Parameters

object | Required. An object expression that evaluates to a Channel object.
Nickname | Required. A string expression that contains the invited user's Nickname.

Remarks

The invited user gets an OnInvitation event.

Example

MsChatPr1.Channels(5).SendInvitation "EuniceM"

The previous example is equivalent to:

MsChatPr1.SendInvitation("EuniceM",MsChatPr1.Channels(5).ChannelName)


SendMessage Method

Sends text or data messages to the channel or members of the channel.

Syntax

object.SendMessage MessageType, Message[, RecipientNicknames][, DataMessageTag]

Parameters

object | Required. An object expression that evaluates to a Channel object.
MessageType Required. A long integer that is a combination of some of the enumMessageType enumeration values. The valid MessageType values are:
msgtNormal
msgtNotice
msgtData
msgtDataRequest
msgtDataReply
msgtWhisper
msgtData + msgtDataRaw
msgtDataRequest + msgtDataRaw
msgtAction + msgtNormal
msgtSound + msgtNormal
msgtCTCP + msgtNormal
msgtAction + msgtNotice
msgtSound + msgtNotice
msgtCTCP + msgtNotice
msgtAction + msgtWhisper
msgtSound + msgtWhisper
msgtCTCP + msgtWhisper

The msgtNotice, msgtData, msgtDataRequest, msgtDataReply, and msgtWhisper values are mutually exclusive.

The msgtData, msgtDataRequest, msgtDataReply, msgtAction, msgtSound, and msgtCTCP values are mutually exclusive.

The msgtDataRaw, msgtAction, msgtSound, and msgtCTCP values are mutually exclusive.

Message Required. A variant containing the actual message to send. It 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 those numbers are:
VT_UI1
VT_I2
VT_I4
VT_R4
VT_R8
VT_BOOL
VT_ERROR
VT_CY
VT_DATE

When sending data and the msgtDataRaw flag is not set, the control packages the Message variant into an array of bytes. An internal header is used to notify the recipient(s) that the message originates from an MsChatPr control.

When the msgtDataRaw flag is also set, the Message variant 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, as shown in the following table.
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.

RecipientNicknames Optional. A variant. Can be missing, an empty variant, or an empty string to send the message to the channel. Otherwise it can be a string, an array of strings, or an array of variants that are strings to send the message to designated channel members.

On IRC servers, there is no method to send a message to specific channel members, so the RecipientNicknames parameter must always be empty or missing.

On IRCX servers, the RecipientNicknames parameter can always specify one or more recipients, or it can be empty.

When msgtWhisper is used, the parameter must specify one or more recipients. The recipient list is exposed to the recipients only when using the msgtWhisper type.

DataMessageTag | Optional. A variant. For IRCX servers only. This parameter is used only when sending data (that is, the msgtData, msgtDataRequest, or msgtDataReply flag is set). If sending data, this parameter must be a non-empty string. In all other cases, this parameter must be empty or missing.

Examples

1. Send a regular string to the channel:

MsChatPr1.Channels(4).SendMessage msgtNormal, "Hi there!"

2. Send a notice to the channel:

chan3.SendMessage msgtNotice, "Bye now!"

3. Send an action to the channel (CTCP action):

chanobj.SendMessage msgtAction, "is eating couscous...."

4. Send a sound to the channel (CTCP sound):

MsChatPr1.Channels.Item(2).SendMessage msgtSound, "couscous.wav Isn't that cool?"

5. Send a CTCP message to the channel:

MsChatPr1.Channels(3).SendMessage msgtCTCP, "FINGER"

6. Send text to a channel member:

chanobj.SendMessage msgtNormal, "I'm an alien spy, and U?", "SharonL"

7. Send a notice to several channel members:

Dim strRecipients(1 To 3) As String
strRecipients(1) = "ColeenS"
strRecipients(2) = "DerrickL"
strRecipients(3) = "EuniceM"
chanobj.SendMessage msgtNotice, "I'm a spy, too...", strRecipients
'or
Dim vRecipients(1 To 3) As Variant
vRecipients(1) = "ColeenS"
vRecipients(2) = "DerrickL"
vRecipients(3) = "EuniceM"
chanobj.SendMessage msgtNotice, "I'm a spy, too...", vRecipients

8. Send an action to several channel members:

Dim strRecipients(1 To 3) As String
strRecipients(1) = "ColeenS"
strRecipients(2) = "DerrickL"
strRecipients(3) = "EuniceM"
chanobj.SendMessage msgtAction, "is eating macaroni and cheese....", strRecipients
'or
Dim vRecipients(1 To 3) As Variant
vRecipients(1) = "ColeenS"
vRecipients(2) = "DerrickL"
vRecipients(3) = "EuniceM"
chanobj.SendMessage msgtAction, "is eating macaroni and cheese....", vRecipients

9. Whisper text to a channel member:

chanobj.SendMessage msgtWhisper, "I'm an alien spy, and U?", "SharonL"

10. Whisper text to channel members:

Dim strRecipients(1 To 3) As String
strRecipients(1) = "SteveL"
strRecipients(2) = "WadeR"
strRecipients(3) = "Eldon"
chanobj.SendMessage msgtWhisper, "I'm a spy, too...", strRecipients
'or
Dim vRecipients(1 To 3) As Variant
vRecipients(1) = "Charlotte"
vRecipients(2) = "Zorg"
vRecipients(3) = "Arthur"
chanobj.SendMessage msgtWhisper, "I'm a cook, too...", vRecipients

11. Send a string as data to the channel:

chanobj.SendMessage msgtData, "And a painter as well.", , "_FOO_"

12. Send a number to channel members:

Dim vRecipients(1 To 3) As Variant
vRecipients(1) = "Charlotte"
vRecipients(2) = "Zorg"
vRecipients(3) = "Arthur"
chanobj.SendMessage msgtData, 1156, vRecipients, "X"

13. Send an array of numbers to the channel:

Dim iValues(1 To 4) As Integer
iValues(1) = 10
iValues(2) = -22
iValues(3) = 123
iValues(4) = 0
chanobj.SendMessage msgtData, iValues, , "COORD"
'or
Dim vValues(1 To 4) As Variant
vValues(1) = 10
vValues(2) = -22
vValues(3) = 123
vValues(4) = 0
chanobj.SendMessage msgtData, vValues, , "COORD"

14. Send an array of strings to a channel member:

Dim strValues(1 To 4) As String
strValues(1) = "Blue"
strValues(2) = "Green"
strValues(3) = "Red"
strValues(4) = "White"
chanobj.SendMessage msgtData, strValues, "Arthur", "COLORS"
'or
Dim vValues(1 To 4) As Variant
vValues(1) = "Blue"
vValues(2) = "Green"
vValues(3) = "Red"
vValues(4) = "White"
chanobj.SendMessage msgtData, vValues, "Arthur", "COLORS"

15. Send an array of variants to the channel:

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
chanobj.SendMessage msgtData, vValues, , "TheHugeOne"

16. Send raw data to the channel:

'A postprocessed string
chanobj.SendMessage msgtData+msgtDataRaw,_
      "dhe\rotk\\nsk\0k45v\0zxa\\v", , "ProcessedString"
'One byte
Dim byt As Byte
byt = 56
chanobj.SendMessage msgtData+msgtDataRaw, byt, , "OneByte"
'An array of bytes
Dim rgBytes(1 To 3) As Byte
rgBytes(1) = 15
rgBytes(2) = 98
rgBytes(3) = 2
chanobj.SendMessage msgtData+msgtDataRaw,_
    rgBytes, , "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)
chanobj.SendMessage msgtData+msgtDataRaw,_
      vByt, , "ArrayOfVariants"

See Also

enumMessageType, OnMessage


Channels Collection Object

The Chat Protocol control Channels collection object is a standard Visual Basic collection object and uses the standard Add and Remove methods and the Item and Count properties.

This section lists the methods and properties supported by the Channels collection object.

Methods

Add, Remove

Properties

Count, Item


Properties

This section describes the properties associated with the Channels collection object.

Count Property

Item Property


Count Property

Accesses the number of Channel objects in the Channels collection.

Syntax

value=object.Count

Parameters

value | Required. A long integer that contains the number of Channel objects in the Channels collection.
object | Required. An object expression that evaluates to a Channels collection object.

Remarks

Access is read-only.

Examples

Dim lChannelCount As Long
lChannelCount = MsChatPr1.Channels.Count
Dim coll As Channels
Set coll = MsChatPr1.Channels
lChannelCount = coll.Channels.Count

See Also

Item


Item Property

Accesses a channel in the collection. This is the default property of the Channels collection.

Syntax

value=object.Item[(Index)]

Parameters

value | Required. An object expression that evaluates to a Channel object.
object | Required. An object expression that evaluates to a Channels collection object.
Index Optional. A variant. The channel index is 1-based. If no Index parameter is specified or if it is an empty variant, the channel with the highest index is returned by the Item property.

The Index parameter can also be a string that represents the unique channel key specified at creation time in the Add method.

Remarks

Access is read-only.

Because Item is the default property of the Channels collection, the keyword "Item" can be omitted.

Examples

MsChatPr1.Channels.Add 1, "One"
MsChatPr1.Channels.Add 2, "Two"
MsChatPr1.Channels.Add 3, "Three"
MsChatPr1.Channels.Add 4, "Four"
Dim c As Channel
Set c = MsChatPr1.Channels.Items(4)
    'is equivalent to
Set c = MsChatPr1.Channels(4)
    'is equivalent to
Set c = MsChatPr1.Channels("Four")
    'is equivalent to
Set c = MsChatPr1.Channels.Item
Dim coll As Channels
Dim chan1, chan2 As Channel
Set coll = MsChatPr1.Channels
Set chan1 = coll.Add(1, "Foo")
Set chan2 = coll.Item(1)

See Also

Add


Methods

This section describes the methods associated with the Channels collection object.

Add Method

Remove Method


Add Method

Adds a Channel object to the Channels collection.

Syntax

value=object.Add[(Index][, Key)]

Parameters

value | Required. An object expression that evaluates to a Channel object. This will contain the newly added Channel object.
object | Required. An object expression that evaluates to a Channels collection object.
Index | Optional. A variant. If specified, it must be empty or a valid index that is a number between 1 and the current collection Count + 1.
Key | Optional. A variant. If specified, it must be empty or a unique string that will identify the new Channel object.

Examples

Dim chan1, chan2 As Channel
Set chan1 = MsChatPr1.Channels.Add(1, "Questions")
Set chan2 = MsChatPr1.Channels.Add(2, "Answers")
MsChatPr1.Channels.Add
MsChatPr1.Channels.Add , "Aud"
MsChatPr1.Channels.Add 5

See Also

Index


Remove Method

Removes a Channel object from the Channels collection.

Syntax

object.Remove Index

Parameters

object | Required. An object expression that evaluates to a Channels collection object.
Index | Required. A variant. Index can be a number between 1 and the current collection Count, or the unique channel key.

Examples

MsChatPr1.Channels.Remove 4
MsChatPr1.Channels.Remove "Aud"

See Also

Item


ChatItems Object

The Chat Protocol control supports sophisticated querying through the ChatItems object. These queries relate to the Server, Channel, a Member, or a User. Usually the information provided by the server is exposed to the developer through the ChatItems object.

This section lists the properties and method supported by the ChatItems object.

Properties

AssociatedType, Item, ItemValid, ValidItems

Method

InvalidateItem


Properties

This section describes the properties associated with the ChatItems object.

AssociatedType Property

Item Property

ItemValid Property

ValidItems Property


AssociatedType Property

Defines whether the object is used to describe a query, server, user, member, or channel.

Syntax

object.AssociatedType=value

Parameters

object Required. An object expression that evaluates to a ChatItems object.
value Required. A string containing one of these valid values:
Query
Server
User
Member
Channel

Remarks

Access is read/write.

See Also

Item


Item Property

Reads or writes an item in the object.

Syntax

object.Item(ItemName)=value

Parameters

object | Required. An object expression that evaluates to a ChatItems object.
ItemName | Required. A string expression.
value | Required. A variant that can be a string, number, or array of variants.

Remarks

Access is read/write.

The number of items set in a ChatItems object is unlimited. Items with a given name are unique in the object. An Item that was previously set can be overwritten by setting a new Item with the same ItemName.

Example

Dim chatitemobj as ChatItems
Set chatitemobj = New ChatItems
chatitemobj.AssociatedType = "Query"
chatitemobj.Item("Name") = "#Room"
chatitemobj.Item("Name") = "#Rhum"  'the last assignment is kept

See Also

AssociatedType


ItemValid Property

Determines if a specific ItemName is valid in the object.

Syntax

value=object.ItemValid(ItemName)

Parameters

value | Required. A Boolean variable that determines if an ItemName is valid.
object | Required. An object expression that evaluates to a ChatItems object.
ItemName | Required. A string expression.

Remarks

Access is read-only.

Examples

The OnServerProperty event has a ServerItems parameter that is a ChatItems object. This event occurs in the following example:

MsChatPr1.QueryServerProperty "Info"

To extract the data attached to the "Info" ItemName, the following example is valid, given that the "Info" property is an array of strings.

If(ServerItems.ItemValid("Info")) Then
    Dim vInfo As Variant
    Dim strInfo As String
    Dim iIndex As Integer
    vInfo = ServerItems.Item("Info")
    strInfo = " "
    If(Not IsEmpty(vInfo)) Then
        For iIndex = LBound(vInfo) To UBound(vInfo)
            strInfo = strInfo + "<" + CStr(vInfo(iIndex)) + ">"
        Next iIndex
    End If
End If

See Also

Item, ValidItems


ValidItems Property

Defines the valid item names of the object.

Syntax

object.ValidItems=value

Parameters

object | Required. An object expression that evaluates to a ChatItems object.
value | Required. A variant that is an array of variants that are strings. When the ChatItems object has no valid items set, the Empty keyword as a variant is valid. (The Empty keyword is used as a variant subtype. It indicates an uninitialized variable value.)

Remarks

Access is read-only.

See Also

Item


Method

This section describes the method associated with the ChatItems object.

InvalidateItem


InvalidateItem

Removes an item previously set in the object with the Item property.

Syntax

object.InvalidateItem(ItemName)

Parameters

object | Required. An object expression that evaluates to a ChatItems object.
ItemName | Required. A string expression.


Enumerations

This section describes the enumerations supported by the Chat Protocol Control 2.0.

enumChannelMode, enumChannelState, enumConnectionState, enumConnectionType, enumConversionSource, enumConversionType, enumEnumType, enumMemberMode, enumMessageType, enumPrivateMessageType, enumServerMessageType, enumStringType, enumUserMode

Note Microsoft Visual Basic 4.0 does not support the use of enumerations as variable types.


enumChannelMode Enumeration

Used in OnChannelProperty and OnChannelPropertyChanged events, CreateChannel, ChangeChannelProperty, and QueryChannelProperty methods, and ChannelProperty property to contain the channel mode.

Value | Description
cmNone | Value = &H0. No particular mode is set.
cmPublic | Value = &H0. The channel is public and all information about the channel (except for text messages) can be queried by nonmembers. The cmPublic mode is mutually exclusive with the cmPrivate, cmHidden, and cmSecret modes.
cmPrivate | Value = &H1. The channel is private and only the name, number of members, and PICS rating property can be queried by nonmembers. The cmPrivate mode is mutually exclusive with the cmPublic, cmHidden, and cmSecret modes.
cmHidden | Value = &H2. The channel is hidden and cannot be located through enumeration queries by nonmembers. The cmHidden mode is mutually exclusive with the cmPublic, cmPrivate, and cmSecret modes. The purpose of the new cmHidden channel mode is to permit the existence of channels that cannot be found using the standard LIST IRC command, but whose properties can be queried if the exact channel name is known. Thus a hidden channel is like a public channel except that it cannot be enumerated by using a ListChannels method call.
cmSecret | Value = &H4. The channel is secret and cannot be located by any query from nonmembers. The cmSecret mode is mutually exclusive with the cmPublic, cmPrivate, and cmHidden modes.
cmModerated | Value = &H8. Normally, new channel members may speak. In cmModerated mode, however, by default, new channel members may not speak. This is achieved by designating the no voice mode to all new members for that channel. Although the no voice mode usually has no effect, it does affect a moderated channel.
cmNoExtern | Value = &H10. Blocks messages from nonmembers to the channel. An administrator can still send a message to the channel.
cmTopicop | Value = &H20. Permits only channel owners and hosts to change the channel topic property.
cmInvite | Value = &H40. Permits only invited users to enter the channel. Only owners and hosts can issue an invitation when this mode is on.
cmKnock | Value = &H80. The cmKnock extended mode causes an OnKnock event to be fired for owners and hosts of the channel if a user attempts to join a channel and is denied entrance by the server.
cmNoWhisper | Value = &H100. Prevents whisper messages from being sent to the channel.
cmRegistered | Value = &H200. The channel is registered by the administrator of the chat network. The registration procedure is not defined here and is implementation-dependent. Only the server or administrator can set this mode.
cmService | Value = &H400. A service is monitoring/controlling the channel. This is an indication to the client that message traffic sent to the channel is being monitored by a chat service that does not appear as a member in the channel. The cmService flag can be set only by the chat server.
cmAuthOnly | Value = &H800. Permits channel access only to users who have been authenticated by the server. Note that an authenticated user is any user who was successfully authenticated by the Password parameter or SecurityPackages parameter during the Login method.
cmCloneable | Value = &H1000. Defines a channel that creates new clone channels if the parent channel is full. A clone channel is created with the same name as the parent cloneable channel with a numeric suffix starting at 1 and ranging to 99. It is not valid to set the cmCloneable channel mode of a parent channel that ends with a numeric character. The clone channel inherits modes and properties from the parent channel when it is set up. When a clone channel is created, any channel that has the same name is removed. This prevents channel takeover of a clone channel. It is advised that only administrators be allowed to set cmCloneable mode on a channel.
cmClone | Value = &H2000. Defines a channel that was created by the server when a parent cloneable channel becomes full. Users should usually join the parent channel, although a user can join a clone channel that is not full. Only the server can set up a clone channel and set this mode.
cmAuditorium | Value = &H4000. Restricts visibility and messaging within a channel. Members will only see themselves and the hosts/owners in the channel. Any message sent by a member will be received only by the hosts and owners. Hosts and owners will see all members in the channel. Messages from a host or owner are seen by all channel members. Ordinary members will not receive OnAddMember and OnDelMember events for other members. This mode is designed for channels with such a large membership that the members do not want to see each other.
cmNoFormat Value = &H8000. Indicates to the client application not to format text received from the channel. Normally, clients will prefix text messages with "x said y" or "x whispers to y and x". If the cmNoFormat mode is set, just the raw text is displayed, wrapping to the next line at the end of the message. The client should not echo text sent by the client. This is to permit custom applications to control the formatting to clients.

Because cmNoFormat is a channel mode and could be abused by the channel host, clients may want to inform users that messages can be spoofed or imitated with this mode. With MIC 2.0, only the administrator can enable this mode on persistent channels. This is the IRCX +f channel mode. The concept does not exist on other IRC servers. Clients can choose to ignore the flag.

cmCreateOnly | Value = &H10000000. Only used in a CreateChannel call. If set, the channel is opened only if it does not yet exist.


enumChannelState Enumeration

OnChannelState event and ChannelState property values.

Value | Description
chsClosed | Value = 0. The state of a channel when created. It becomes chsClosed again when the user leaves the channel or is kicked from the channel, or when a server disconnection occurs.
chsOpening | Value = 1. When calling its JoinChannel or CreateChannel method, the state becomes asynchronously chsOpening and chsOpen.
chsOpen | Value = 2. When calling its JoinChannel or CreateChannel method, the state becomes asynchronously chsOpening and chsOpen.


enumConnectionState Enumeration

OnConnectionState event and ConnectionState property values.

Value | Description
csDisconnected | Value = 0. Used to indicate that the connection state of the channel is currently disconnected.
csConnecting | Value = 1. Used to indicate that the connection state of the channel is currently in the process of connecting.
csConnected | Value = 2. Used to indicate that the connection state of the channel is currently connected.
csLogging | Value = 3. Used to indicate that the connection state of the channel is currently in the process of logging.
csLogged | Value = 4. Used to indicate that the connection state of the channel is currently logged.
csDisconnecting | Value = 5. Used to indicate that the connection state of the channel is currently in the process of disconnecting.


enumConnectionType Enumeration enumConnectionType Enumeration *
  * Previous Topic: enumConnectionState Enumeration
  * Next Topic: enumConversionSource Enumeration

enumConnectionType Enumeration

ConnectionType property value.

Value | Description
ctIRC | Value = 0. For IRC connections.
ctIRCX | Value = 0. For IRCX connections.


enumConversionSource Enumeration

ConvertedString property access.

Value | Description
cvsNormal | Value = 0. For regular text.
cvsNickname | Value = 1. For user nicknames.
cvsChannelName | Value = 2. For channel names.


enumConversionType Enumeration

ConvertedString property access.

Value | Description
cvtToUTF8 | Value = 0. Used to convert to UTF8 format.
cvtToUnicode | Value = 1. Used to convert to Unicode format.


enumEnumType Enumeration

OnBeginEnumeration and OnEndEnumeration events parameter.

Value | Description
etMessageOfTheDay | Value = 0. Used when exposing the message of the day at login.
etUsers | Value = 1. Used when listing users with the ListUsers method.
etChannels | Value = 2. Used when listing channels with the ListChannels method.
etChannelsTruncated | Value = 3. Used when channel listing is truncated during a ListChannels call.
etMembers | Value = 4. Used when listing members with the ListMembers method.
etInitialMembers | Value = 5. Used when initial channel members are exposed when joining a channel.


enumMemberMode Enumeration

Used in OnMemberProperty and OnMemberPropertyChanged events, QueryMemberProperty and ChangeMemberProperty methods, and MemberProperty and MemberModes properties.

Value | Description
mmNone | Value = &H0. No specific member mode is set.
mmClientIgnored | Value = &H1. At the client level, incoming messages from specific members will be ignored and not exposed by an OnMessage event. This is ignoring at the client level, not the server level.
mmNotClientIgnored | Value = &H2. At the client level, incoming messages from specific members will not be ignored and will be exposed by an OnMessage event.
mmAuthMember | Value = &H4. The member was authenticated by the server by the use of a password or authentication package.
mmNotAuthMember | Value = &H8. The member was not authenticated by the server.
mmAway | Value = &H10. The member has an away text message, and the away flag is set.
mmNotAway | Value = &H20. The member does not have an away text message, and the away flag is not set.
mmSysop | Value = &H40. The member is a system operator.
mmNotSysop | Value = &H80. The member is not a system operator.
mmOwner | Value = &H100. The member is an owner of the channel.
mmNotOwner | Value = &H200. The member is not an owner of the channel.
mmHost | Value = &H400. The member is a host of the channel.
mmNotHost | Value = &H800. The member is not a host of the channel.
mmVoice | Value = &H1000. The member is able to speak even if the channel is moderated.
mmNoVoice | Value = &H2000. The member cannot speak if the channel is moderated.


enumMessageType Enumeration

Used in OnMessage event and SendMessage method parameters.

Value | Description
msgtNormal | Value = &H0. Sends a regular text message to the channel.
msgtNotice | Value = &H1. Similar to msgtNormal, but the client does not expect an answer from the recipient(s).
msgtData | Value = &H2. IRCX servers only. Sends data instead of text.
msgtDataRequest | Value = &H4. IRCX servers only. Similar to msgtData except the sender expects a msgtDataReply response from the recipient(s).
msgtDataReply | Value = &H8. IRCX servers only. Similar to msgtData except the sender does not expect a reply.
msgtDataRaw | Value = &H10. IRCX servers only. Sends raw bytes to the server without using an internal message header. This flag must be combined with msgtData, msgtDataRequest, or msgtDataReply.
msgtWhisper | Value = &H20. Used to whisper to some channel members instead of sending out to the entire channel. The recipients receive the whole list of recipients.
msgtThought | Value = &H40. Incoming messages only. Indicates that the message is a thought.
msgtAction | Value = &H80. Sends an action CTCP.
msgtSound | Value = &H100. Sends a sound CTCP.
msgtCTCP | Value = &H200. Sends a regular CTCP.
msgtInfo | Value = &H400. Incoming messages from Microsoft Chat Control 1.1 only. Used to indicate what kind of visual character and what type of gesture to display.


enumPrivateMessageType Enumeration

Used in the OnPrivateMessage event and the SendPrivateMessage method parameters.

Value | Description
pmtNormal | Value = &H0. Used in the OnPrivateMessage event and the SendPrivateMessage method to send a regular text message.
pmtNotice | Value = &H1. Sends a regular text message to the users, like pmtNormal, but the client does not expect an answer from the recipients.
pmtData | Value = &H2. Can be used only on IRCX servers. Sends data instead of text.
pmtDataRequest | Value = &H4. Can be used only on IRCX servers. Sends data instead of text, like pmtData, but the sender expects a pmtDataReply reply from the recipient(s).
pmtDataReply | Value = &H8. Can be used only on IRCX servers. Similar to pmtData, but the sender does not want a reply from the recipient(s).
pmtDataRaw | Value = &H10. Can be used only on IRCX servers. Sends raw bytes to the server without using an internal message header. This flag must be combined with pmtData, pmtDataRequest, or pmtDataReply.
pmtAway | Value = &H20. For incoming away messages.
pmtVersion | Value = &H40. Requests or sends version information.
pmtLagTime | Value = &H80. Requests or gets the lag time with a user or users.
pmtLocalTime | Value = &H100. Requests or gets the local time of a user or users.
pmtAction | Value = &H200. Sends or receives an action CTCP (Client to Client Protocol) to a user or users.
pmtSound | Value = &H400. Sends or receives a sound CTCP to a user or users.
pmtCTCP | Value = &H800. Sends or receives a regular CTCP to a user or users.
pmtInfo | Value = &H1000. Same as msgtInfo, used to indicate what kind of avatar and what type of gesture to display.


enumServerMessageType Enumeration

OnServerTextMessage event parameter.

Value | Description
smtNormal | Value = &H0. Used for regular incoming server messages.
smtNotice | Value = &H1. Used for incoming NOTICE message from the server.
smtMessageOfTheDay | Value = &H2. Used for the message of the day incoming text at login time.
smtServerInfo | Value = &H3. Used for server information messages.
smtError | Value = &H4. Used for incoming server error messages.


enumStringType Enumeration

MaxStringLength property access.

Value | Description
stServerMessage | Value = 1. Used when querying the maximum length of the incoming and outgoing server messages.
stChannelAccount | Value = 2. Used when querying the maximum length of the incoming and outgoing channel Account properties.
stChannelClientData | Value = 3. Used when querying the maximum length of the incoming and outgoing channel ClientData properties.
stChannelHostKey | Value = 4. Used when querying the maximum length of the incoming and outgoing channel HostKey properties.
stChannelKeyword | Value = 5. Used when querying the maximum length of the incoming and outgoing channel Keyword properties.
stChannelLanguage | Value = 6. Used when querying the maximum length of the incoming and outgoing channel Language properties.
stChannelName | Value = 7. Used when querying the maximum length of the incoming and outgoing channel Name properties.
stChannelOnJoin | Value = 8. Used when querying the maximum length of the incoming and outgoing channel OnJoin properties.
stChannelOnPart | Value = 9. Used when querying the maximum length of the incoming and outgoing channel OnPart properties.
stChannelOwnerKey | Value = 10. Used when querying the maximum length of the incoming and outgoing channel OwnerKey properties.
stChannelRating | Value = 11. Used when querying the maximum length of the incoming and outgoing channel Rating properties.
stChannelSubject | Value = 12. Used when querying the maximum length of the incoming and outgoing channel Subject properties.
stChannelTopic | Value = 13. Used when querying the maximum length of the incoming and outgoing channel Topic properties.


enumUserMode Enumeration

Used in the OnUserProperty, OnUserPropertyChanged, OnInvitation, and OnKnock events, the QueryUserProperty and ChangeUserProperty methods, and the UserProperty property.

Value | Description
umNone | Value = &H0.
umClientIgnored | Value = &H1. The user is ignored by the caller.
umNotClientIgnored | Value = &H2. The user is not ignored by the caller.
umAuthUser | Value = &H4. The user is authenticated.
umNotAuthUser | Value = &H8. The user is not authenticated.
umAway | Value = &H10. The user is currently away.
umNotAway | Value = &H20. The user is not currently away.
umSysop | Value = &H40. The user is a system operator.
umNotSysop | Value = &H80. The user is not a system operator.
umAdmin | Value = &H100. The user is an administrator.
umNotAdmin | Value = &H200. The user is not an administrator.
umInvisible | Value = &H400. The user is invisible.
umNotInvisible | Value = &H800. The user is not invisible.
umNotices | Value = &H1000. The user accepts server notices.
umNoNotices | Value = &H2000. The user does not receive server notices.
umWallops | Value = &H4000. The user receives wallops. A wallops is an IRC feature that will send a message to all operators online that have +w set on their user mode. Different IRC servers have various restrictions on who can send and read wallops.
umNoWallops | Value = &H8000. The user does not receive wallops.


Error Codes

The following lists contain the error codes supported by Chat Protocol Control 2.0 and the associated error messages. These error messages are subject to change and may not be exactly as they appear here.

Access Rights-Related, Channel-Related, Channels Collection-Related, ChatItems-Related, Connection-Related, Generic, Login-Related, Member-Related, Property-Related, Protocol-Related, Sending-Related, User-Related

Access Rights-Related Errors

Value | Description
3140 | Only a system operator can perform this operation.
3141 | You are not an owner of the channel '<ChannelName>'.
3142 | You are not a host in the channel '<ChannelName>'.
3143 | You don't have the rights to view this content.
3144 | You are banned from this channel '<ChannelName>'.
3145 | You are banned from this server.
3146 | You will be banned.
3147 | You cannot ignore a system operator or your channel host, or owner.
3148 | You cannot join a MIC-only channel with IRCX client.
3149 | You cannot join this channel from a remote server.
3150 | You cannot join dynamic channels due to admin restriction.
3151 | You cannot create dynamic channels due to admin restriction.
3152 | Only authenticated users may join this channel '<ChannelName>'.
3153 | The listing is too large and is aborted.

Channel-Related Errors

Value | Description
3060 | The channel is already open.
3061 | The channel is already opening.
3062 | The channel is not open.
3063 | The channel is not closed.
3064 | There is not exactly one open channel.
3065 | The channel Name is invalid.
3066 | The channel Topic is invalid.
3067 | The Keyword is invalid for channel '<ChannelName>'.
3068 | The channel HostKey is invalid.
3069 | The channel OwnerKey is invalid.
3070 | The channel Modes parameter is invalid.
3071 | The channel MaxMemberCount parameter is invalid.
3072 | The channel '<ChannelName>' is full.
3073 | You cannot join channel '<ChannelName>' because too many channels are already open.
3074 | You are not in the channel '<ChannelName>'.
3075 | The member '<Nickname>' is already in the channel '<ChannelName>'.
3076 | The channel '<ChannelName>' does not exist.
3077 | You need an invitation to join this channel '<ChannelName>'.
3078 | The key for this channel '<ChannelName>' has already been set.

Channels Collection-Related Errors

Value | Description
3170 | The channel index specified is invalid.
3171 | The channel index specified is out of bounds.
3172 | The channel is no more part of the collection.
3173 | The channel key specified is invalid.
3174 | The channel key specified is not unique.

ChatItems-Related Errors

Value | Description
3160 | This property is not available.
3161 | This property cannot be used in this context.
3162 | The associated type is invalid.
3163 | This property name is invalid.
3164 | A property value is invalid.
3165 | Unknown query operator.
3166 | A time-out condition occurred.

Connection-Related Errors

Value | Description
3020 | You are already connecting to a server.
3021 | You are already connected to a server.
3022 | You are already disconnecting from the server.
3023 | There is no operation in progress to be canceled.
3024 | You must disconnect first before logging on to that server.
3025 | You are not connected to a server.
3026 | The server could not be found.
3027 | Could not connect to the server.
3028 | Could not connect to the server.
3029 | A connection error occurred.
3030 | The connection to the server was lost.
3031 | The connection to the server was lost.
3032 | The server network is down.
3033 | The server dropped the connection.

Generic Errors

Value | Description
5 | Illegal function call.
6 | Overflow error.
7 | Out of memory. Please close some applications and try again.
70 | You don't have the right privileges to perform this command.
380 | Invalid property value.
382 | Property is read-only at run time.
383 | Property is read-only.
394 | Property is write-only.
3000 | An error occurred. Please leave the application and try again.
3001 | You specified an invalid argument.

Login-Related Errors

Value | Description
3040 | You are already logging on to a server.
3041 | You are already logged on to the server.
3042 | You are not logged on to a server.
3043 | You are already registered on the server.
3044 | You are not registered on the server.
3045 | The SecurityPackages parameter is invalid.
3046 | The login failed.
3047 | The authentication failed.
3048 | The authentication is not available.
3049 | Only authenticated users can login.

Member-Related Errors

Value | Description
3090 | The member '<Nickname>' does not exist in channel '<ChannelName>'.
3091 | The member modes parameter is invalid.

Property-Related Errors

Value | Description
3080 | The property name you specified for the object '<ObjectName>' is invalid.
3081 | The property value you specified for the object '<ObjectName>' is invalid.
3082 | This property is not readable.
3083 | This property is read-only.
3084 | This property is not writeable.

Protocol-Related Errors

Value | Description
3130 | A server error occurred.
3131 | This operation can only be performed when connected to an IRCX server.
3132 | The mode specified is unknown.
3133 | The server could not open the MOTD file.
3134 | This feature is not implemented on this chat server.

Sending-Related Errors

Value | Description
3110 | The message you are trying to send is too large.
3111 | Couldn't send the message to the channel '<ChannelName>'.
3112 | The recipient list is invalid.
3113 | The reason parameter is invalid.
3114 | The Away message parameter is invalid.
3115 | You cannot send an empty message.
3116 | The message type is invalid.
3117 | You are not allowed to whisper in the channel '<ChannelName>'.
3118 | The data tag is invalid.

User-Related Errors

Value | Description
3100 | The nickname parameter is invalid.
3101 | The user name parameter is invalid.
3102 | The real name parameter is invalid.
3103 | The password parameter is invalid or wrong.
3104 | The nickname '<Nickname>' is already in use.
3105 | There was a nickname collision for '<Nickname>'.
3106 | There is no user with the nickname '<Nickname>'.
3107 | The user modes parameter is invalid.
3108 | You are trying to change your nickname too quickly.
3109 | Nickname changes are not permitted at this time, try again later.


Object Properties

This section describes the properties associated with the Microsoft Chat Protocol 2.0.

Server, Channel, User, Member


Server Properties

The following table contains the server properties supported by Chat Protocol Control 2.0.

Note RO: Read-only RW: Read/write QO: Query-only WO: Write-only

Name | Type | Access | Description
AnonymousAllowed | Boolean | RO | Are anonymous connections allowed?
ChannelCount | Long | RO | How many open channels on the server?
IgnoredUsers | Variant: array of variants that are ChatItems objects or empty | RO | List of ignored users.
Info | Variant: array of variants that are strings or empty | RO | Information strings about the server.
MaxMessageLength | Long | RO | Maximum server message length in bytes.
Name | String | RO | Server name.
NetInvisibleCount | Long | RO | Number of invisible users on the network.
NetServerCount | Long | RO | Number of nodes on the network.
NetUserCount | Long | RO | Number of users on the network.
NodeServerCount | Long | RO | Number of node connections to this node.
NodeUserCount | Long | RO | Number of user connections to this node.
SecurityPackages | String | RO | Security packages provided by this server.
SysopCount | Long | RO | Number of system operators on this server.
UnknownConnectionCount | Long | RO | Number of users logging on to the server.


Channel Properties

The following table contains the channel properties supported by Chat Protocol Control 2.0.

Note All the properties that have a name that ends in "Op" are used for querying only and can have one of only three values: "StartsWith", "EndsWith", and "Contains".

Note RO: Read-only RW: Read/write QO: Query-only WO: Write-only

Name | Type | IRCX only | Access | Description
Account | String | Y | RW or RO | Implementation-dependent string for attaching a security account.
BannedList | Variant | N | RO | List of banned members.
ChannelAgeMax | Long | Y | QO | Used when listing channels.
ChannelAgeMin | Long | Y | QO | Used when listing channels.
ClientData | String | Y | RW or RO | Client-defined information.
ClientGuid | String | Y | RW or RO | GUID that defines the client protocol to be used within the channel.
CloneList | Variant | Y | RO | List of clone channel names created after the user joined the original channel. (See Remarks)
CreationTime | Long | Y | RO | The time that the channel was created, in number of seconds elapsed since midnight, January 1, 1970.
HostKey | String | Y | WO | The host key that will provide host access when entering the channel.
Keyword | String | N | WO | The keyword required to enter the channel.
Lag | Long | Y | RW or RO | Numeric value between 0 and 2 seconds that will add an artificial lag to any message sent from the same member within the specified lag settings.
Language | String | Y | RW or RO | The preferred language type.
LanguageOp | String | Y | QO | Used when listing channels.
ListCount | Long | Y | QO | Used when listing channels.
MaxMemberCount | Long | N | RW or RO | Maximum number of members allowed in the channel.
MemberCount | Long | N | RO | Current number of members in the channel.
MemberCountMax | Long | Y | QO | Used when listing channels.
MemberCountMin | Long | Y | QO | Used when listing channels.
Modes | Long | N | RW or RO | The channel modes (cmAuditorium, cmPrivate, and so on.)
Name | String | N | RO | The channel name.
NameOp | String | N | QO | Used when listing channels.
ObjectId | Long | Y | RO | Internal object identifier for the channel. If set to "0", this feature is not supported on the server.
OnJoin | String | Y | RW or RO | A string to be sent as a private message to a user after the user joined the channel. (See Remarks)
OnPart | String | Y | RW or RO | A string to be sent as a private message to a user after the user leaves the channel. (See Remarks)
OwnerKey | String | Y | WO | The Owner keyword that will provide owner access when entering the channel.
Rating | String | Y | RW or RO | The current PICS rating of the channel.
Registered | Boolean | Y | QO | Used when listing channels.
ServicePath | String | Y | RW or RO | The path of a server side extension that is used to control the channel operation. Details are implementation-dependent.
Subject | String | Y | RW | String that can contain subject keywords.
SubjectOp | String | Y | QO | Used when listing channels.
Topic | String | N | RW or RO | The topic of the conversation in the channel.
TopicAgeMax | Long | Y | QO | Used when listing channels.
TopicAgeMin | Long | Y | QO | Used when listing channels.
TopicOp | String | Y | QO | Used when listing channels.

Remarks

CloneList: The latest clone created has the highest index in the array of clone names. When a clone is closed, the hosts of the original channel don't get notified. Later, when the clone is recreated, it is repositioned to the end of the array of clones.

OnJoin and OnPart: The sender of the message is the channel Name. Only the user joining the channel will see this message. Multiple lines can be generated by embedding a backslash followed by the lowercase letter 'n' (\n) at the point in the string where it wraps to the next line.

See Also

Note


User Properties

The following table contains the user properties supported by Chat Protocol Control 2.0.

Note RO: Read-only RW: Read/write QO: Query-only WO: Write-only

Name | Type | Access | Description
Away | String | RO | Away text message.
Channels | String or variant: array of variants that are strings | QO or RO | Used when listing users or yields the channels the user is currently in.
HostInChannels | Variant | RO | Lists the channels where the user is currently a host.
Identity | String | RO | Yields the user name and IP address.
IdleTime | Long | RO | Idle time of the user in seconds.
IPAddress | String | RO | IP address of the user. (Host name in IRC terminology.)
IPAddressOp | String | QO | Used when listing, banning, or ignoring users.
Mask | String | QO | Used when listing users.
MaskOp | String | QO | Used when listing users.
Modes | Long | RW or RO | The user modes (Invisible, Sysop, and so on).
Nickname | String | RW or RO | The user's nickname.
NicknameOp | String | QO | Used when listing, banning, or ignoring users.
OwnerOfChannels | Variant: array of Variants that are Strings | RO | Lists the channels for which the user is an owner.
RealName | String | RO | The user's real name.
ServerInfo | String | RO | Some server information.
ServerName | String | RO | The server that the user is connected to.
SignOnTime | Long | RO | The time the user logged on to the server.
UserName | String | RO | The user's user name.
UserNameOp | String | QO | Used when listing, banning, or ignoring users.
VoiceInChannel | Variant: array of Variants that are strings | RO | Lists the channels where the user has a voice.

See Also

Note


Member Properties

The following table contains the member properties supported by Chat Protocol Control 2.0.

Note RO: Read-only RW: Read/write QO: Query-only WO: Write-only

Name | Type | Access | Description
Identity | String | RO | Yields the user name and IP address of the member.
IPAddress | String | RO | IP address of the user. (Host name in IRC terminology.)
IPAddressOp | String | QO | Used when listing, banning, or ignoring members.
Modes | Long | RW or RO | The member modes (mmAway, mmNotClientIgnored, and so on).
Nickname | String | RO | The member's nickname.
NicknameOp | String | QO | Used when listing, banning, or ignoring members.
ObjectId | Long | RO | IRCX specific. Internal object identifier for the member. If set to "0", this feature is not supported on the server.
UserName | String | RO | The member's user name.
UserNameOp | String | QO | Used when listing, banning, or ignoring members.

See Also

Note


Microsoft Chat 1.0j

Microsoft® Chat 1.0j is a Java applet that provides the Web designer with a simple, customizable user interface and programmability for the applet. With this applet, the page can be coded to join or create an existing room on the chat server with a nickname selected by the user. Other options include the ability to customize or hide the toolbar, and hide the member list and/or input field. The applet provides the Web designer with a default user interface that includes dialog boxes to view the room list, create and join a room, change the nickname, change fonts, and connect to the server. The default user interface is customizable by the Web designer.

Microsoft Chat 1.0j does not provide event notification and does not display the user list on the chat server.

Setting Up Microsoft Chat 1.0j

Optional Parameters

Public Applet Methods

Setting Up Microsoft Chat 1.0j

The following steps show how to set up Microsoft Chat 1.0j to work with your chat server:

  1. Set up a Web server and IRC chat server on the same computer to use the Chat applet. Chat 1.0j should work with any IRC chat server but has been tested mainly with the IRC chat server available from http://backoffice.microsoft.com/product/chat/.

  2. After you set up the Web server and chat server, copy Mschat1j.exe in the \bin directory to your Web server. You can obtain Mschat1j.exe by installing the Component Library section of the Internet Client SDK.

  3. Unzip the self-extracting executable file by running Mschat1j.exe from the \bin directory of the Internet Client SDK.

  4. To use Microsoft Chat 1.0j, after running Mschat1j.exe, you will need to use all *.class, *.gif, *.cab, *.properties, and *.files files. You will also need an HTML file that points to the applet. You can use the sample HTML files or create your own.

Optional Parameters

The following is a list of optional parameters that can be applied to a Chat applet embedded on a Web page by using the <PARAM> tag.

Name | Value(s) | Default | Description
port | [number] | 6667 | Specifies the port on which the chat server is running, usually 6667.
nickname | [user nickname] | "Anonymous" | Specifies the default name, used for autoconnect.
room [roomname] - Specifies the default room to join.
toolbar | true | false | true | Determines if the toolbar should be visible.
memberlist | true | false | true | Determines if the member list should be visible.
observer | true | false | false | Determines if the user can participate in a conversation.
banner [imagename] - Specifies a welcome image that should be displayed when the applet loads.
autoconnect | true | false | false | Determines if the applet will automatically connect when loaded. If true, room and nickname must be specified.
autodisconnect | true | false | false | Determines if the applet will automatically disconnect when the page is exited.
motd | true | false | true | Determines if the applet will display the Message of the Day after connecting.
stats | true | false | true | Determines if the applet will display server statistics after connecting.
id | [unique string] | "null" | Indicates that unique identifiers must be supplied if multiple chat applets will be on the same page.
font | fontname, style, size | Helvetica, 0, 11 | Helvetica | Dialog | TimesRoman | Courier, 0(plain), 1(bold), 2(italic), 3(bold + italic), 8 - 20
bgcolor | ffffff | c0c0c0 | Specifies the color, using hexadecimal notation same as in the HTML body tag.

Example

The following example shows HTML code for embedding an applet in a page. The sample shows the main user interface for Chat 1.0j. The user can use the toolbar to choose a nickname, connect to the chat server, and join or create a chat room to chat in.

<applet code=MSChat archive=mschat.jar name=Chat width=500 height=400>
    <param name=cabbase value=mschat.cab>
    <param name=room value=#newbies>
    <param name=port value=6667>
</applet>

Public Applet Methods

The following methods are exposed by the Chat applet. They can be called from any script language supported by the client browser.

Method | Returns | Description
connect(string nickname) | void | Connects to the server with the specified nickname.
connect(string nickname, string room) | void | Connects to the server with the specified nickname and joins the specified room, overriding any present room parameter.
disconnect() | void | User leaves all rooms and closes the connection with the server.
getNick() | String | Returns the user nickname, or null if the user hasn't yet logged on.
getRoom() | String | Returns the name of the room the user is currently in, or null if the user hasn't yet logged on.
join(string room, string password) | void | Leaves any current room, joins a specified room. Password is ignored if null or "".
showRoomList() | void | Displays the room list window.
showEnterRoomDialog() | void | Displays the dialog box that prompts user to enter a chat room.
showFontDialog() | void | Displays the dialog box that prompts user to change the current font.
showConnectDialog() | void | Displays the dialog box that prompts user to connect to a server.
showAboutDialog() | void | Displays the Microsoft Chat dialog box.

Example

The following example calls the connect method.

<FORM NAME="form1">
<INPUT TYPE="button" VALUE="Connect" onClick="document.Chat.connect(document.form1.nickname.value, document.form1.room.value)">
</FORM>
<applet code=MSChat archive=mschat.jar
                name=Chat width=500 height=400>
    <param name=cabbase value=mschat.cab>
    <param name=room value=#newbies>
    <param name=port value=6667>
</applet>


Microsoft Remote Data Service

Microsoft Remote Data Service Microsoft Remote Data Service *

Welcome to Microsoft Remote Data Service

Remote Data Service is a high-performance Web-based technology that brings database connectivity and corporate data publishing capabilities to Internet and intranet applications.

This documentation contains the following sections:

What's New in Remote Data Service 1.5

Getting Started

Tutorials

Developer's Guide

API Reference

Remote Data Service Glossary


Tabular Data Control (TDC)

The Tabular Data Control lets you display data that is stored in a delimited text file. The data can optionally be filtered or sorted by the browser using the properties and method exposed by the control.

Microsoft Tabular Data Control

Microsoft Tabular Data Control Reference


Microsoft Tabular Data Control

The Tabular Data Control (TDC) is a Microsoft® ActiveX™ control that can be hosted by Microsoft® Internet Explorer 4.0 to display data stored in a delimited text file. Using the TDC, a Web author can display data either within tables or within controls found in a form. (Extensions in Internet Explorer 4.0 allow you to bind data to HTML elements on the page as well as to repeat the content of an HTML <TABLE> for each record of a data set. The latter can be thought of as using the table as a template for the data, where the template is repeated once for each record.)

One of the primary features of the TDC is that it brings filtering and sorting operations to the client side (there are no server-side operations).

The TDC exposes the OLE-DB simple provider interfaces. For more information about these interfaces, see OLE-DB Simple Provider: A Data Binding API for IE4/MSHTML.

Source Availability

Licensing and Distribution

Dependencies

Understanding the Tabular Data Control Object Model

Using the Tabular Data Control

Summary

Source Availability

To aid developers in creating their own data source objects, the Tabular Data Control is provided as a sample that ships with the Internet Client SDK. The source code can be found in \inetsdk\samples\tdc.

Licensing and Distribution

The Microsoft Tabular Data Control is automatically installed as part of the base installation of Microsoft Internet Explorer version 4.0.

Dependencies

The TDC is found in the file Tdc.ocx, which is automatically installed and registered with all versions of Internet Explorer 4.0.

Understanding the Tabular Data Control Object Model

The TDC supports properties and methods that can be divided into these categories:

  • Elements that describe the data file.
  • Elements that support data filtering.
  • Elements that support data sorting.

File Properties

Most of the properties supported by the TDC are data-file properties. These properties specify the location of the data file, the language used to create the data file, the character used to delimit fields, and so on. The following list describes each property:
Property | Description
CharSet | Identifies the character set used by the data file. The default character set is latin1.
DataURL | Specifies the location of the data file as a URL.
EscapeChar | Identifies the character to be used as an escape character in the data file. There is no default escape character.
FieldDelim | Identifies the character that is used to mark the end of a field in the data file. The default character is the comma (,).
Language | Specifies the language used to generate the data file (this specifier uses the HTML standard codes based on ISO 369). The default specifier is eng-us.
TextQualifier | Specifies the optional character that surrounds a field.
RowDelim | Identifies the character used to mark the end of each row of data. The default character is the newline (NL) character.
UseHeader | Specifies whether the first line of the data file contains header information. The default value is FALSE.

Filtering Properties

One TDC property and one method apply to data filtering.

Set the Filter property to an expression that includes the name of the column to be filtered, the criteria for filtering, and the value that will be compared against the specified column using the given value. The default value is an empty string ("").

Call the Reset method to apply the filter and refresh the contents of the HTML elements bound to the data supplied by the TDC.

Sorting Properties

One TDC property and a single TDC method apply to data sorting.

Set the Sort property to a semicolon-delimited list of column names by which the bound HTML elements should be sorted. Prefixing a column name with a plus (+) symbol indicates ascending order. The minus (-) symbol indicates descending order. The default sort order is ascending.

Call the Reset method to apply the new sort order and to refresh the contents of the HTML elements bound to the data supplied by the TDC.

Using the Tabular Data Control

This section demonstrates how you can incorporate the TDC into your Web pages.

Note The TDC examples in this section require Internet Explorer 4.0.

A Simple Before-and-After Example

This section contains a very simple example demonstrating how you can replace a static table in your HTML page with a dynamic table that is generated using the TDC. When this replacement occurs, you'll no longer need to modify your HTML source file each time your data changes; instead, you can simply modify the data file or regenerate it from a database.

Adding data to your Web page

The Tabular Data Control (TDC) has many uses, but perhaps the easiest way to get a feel for its capabilities is to see a short example. If you have a data file containing some of the elements of the periodic table, it might look like this:

Element,Symbol
Hydrogen,H
Helium,He
Lithium,Li
Beryllium,Be
Boron,B
Carbon,C
Nitrogen,N
Oxygen,O
Flourine,F
Neon,Ne

Each line contains the name of the element followed by a comma, then its scientific abbreviation. If you wanted to display this table in a Web page without using the TDC, you would add the table tags around each word, as shown in the following example:

<TABLE>
<THEAD><TR><TD>Element</TD><TD>Symbol</TD></TR></THEAD>
<TBODY>
<TR><TD>Hydrogen</TD> <TD>H</TD></TR>
<TR><TD>Helium</TD> <TD>He</TD></TR>
<TR><TD>Lithium</TD> <TD>Li</TD></TR>
<TR><TD>Beryllium</TD> <TD>Be</TD></TR>
<TR><TD>Boron</TD> <TD>B</TD></TR>
<TR><TD>Carbon</TD> <TD>C</TD></TR>
<TR><TD>Nitrogen</TD> <TD>N</TD></TR>
<TR><TD>Oxygen</TD> <TD>O</TD></TR>
<TR><TD>Flourine</TD> <TD>F</TD></TR>
<TR><TD>Neon</TD> <TD>Ne</TD></TR>
</TBODY>
</TABLE>

Click the Show Me button to see how the previous table appears when viewed in your browser.

A static table is not only tedious to create, but it also makes it inconvenient to edit or update the data. This especially applies if you want to use the raw data file in other applications. Using the TDC, you can instead tell the Web page where to find the text file, and it will read the data directly from the file (plus optionally sort it, filter it, and skip columns). The previous table coding is replaced with the following coding:

<TABLE datasrc=#elements>
<THEAD><TR><TD>Element</TD><TD>Symbol</TD></TR></THEAD>
<TBODY>
<TR><TD><DIV datafld="Element"></DIV></TD><TD><DIV datafld="Symbol"></DIV></TD></TR>
</TBODY>
</TABLE>

Click the Show Me button to see how databinding can be used to replace a static table in Internet Explorer 4.0.

If you look more closely at these changes, you will note that the first line uses the DATASRC attribute to identify the TDC. (This identifier corresponds to the ID attribute that was specified for the <OBJECT> tag that loaded the control.)

<TABLE datasrc=#elements>

The prepended # symbol is always required by the DATASRC attribute.

You can include multiple linked tables and objects in each Web page; each table should specify a DATASRC attribute that can be unique to that table or shared between tables or other elements on the page, such as forms.

The second line of the table definition is unchanged. As you can see, it provides the table heading.

<THEAD><TR><TD>Element</TD><TD>Symbol</TD></TR></THEAD>

The fourth line is the most interesting. Instead of providing the actual data, you specify the name of a column in the data file using the new DATAFLD attribute.

<TR><TD><DIV datafld="Element"></DIV></TD><TD><DIV datafld="Symbol"></DIV></TD></TR>

Because the original data file had a header that specified the name of each column, these column names can be used. If no header is provided in your data file, you should use the default names of Column1, Column2, and so on.

As part of the header that specifies column names, a type specifier can be included indicating the data type of the column. Since the TDC reads its data from a text file, this indicates the appropriate type conversion to do upon reading the data from the file. The TDC uses this to perform accurate sorting and filtering. Consider the case where you have integers in a column and you request the column to be sorted. Without the type specification, the sort would be done using string (lexicographic) ordering, which would give the wrong result. For more information on specifying data types for columns, see Microsoft Tabular Data Control Reference.

With this information encoded in the table, Internet Explorer 4.0 will ask the TDC for data to put into the table. It will then create one new row for each row of data. Notice how all the other table encoding tags remain unchanged. In fact, you can treat the incoming data exactly as if it were text that you hard-coded into your Web page. For example, if you wanted the symbols in the table to be bold and centered in their column, you could change the table entry to the following:

<TD><CENTER><B><DIV datafld="Symbol"></DIV></B></CENTER></TD>

You could also choose to completely leave out the symbol information from the table just by removing the <DIV> entry where it is specified. Although this might not necessarily be appropriate for this example, it's often convenient to omit some fields because that allows you to reuse the same data file in many different Web pages rather than maintaining multiple copies of almost identical data.

Declaring the TDC object

The only other new entry in your Web page is the TDC object declaration. The above examples use the following:

<OBJECT id=elements CLASSID="clsid:333C7BC4-460F-11D0-BC04-0080C7055A83">
    <PARAM NAME="DataURL" VALUE="minielts.txt">
    <PARAM NAME="UseHeader" VALUE="True">
</OBJECT>

The ID attribute identifies the TDC and its associated data for later use by elements such as tables, forms, and scripting. The ID attribute can be any arbitrary name, but it's best to start with a letter and avoid spaces and punctuation characters.

The DataURL property tells the TDC where to find the data file. You can provide any valid URL, or, as in this example, use a relative URL that will cause the TDC to look in the same place your Web page was found. Other valid DataURL settings include the following:

<PARAM NAME="DataURL" VALUE="data/elements.txt">
<PARAM NAME="DataURL" VALUE="http://www.mycoolsite.com.au/elements.txt">
<PARAM NAME="DataURL" VALUE="file://\\intranet\server\buried\down\a\long\path\elements.txt">

DataURL is the only property required by the TDC to access data. To delay the binding, omit the specification of the DataURL property in the object declaration, and set it later in script code.

The UseHeader property indicates whether the first line of the data file identified by DataURL lists the names of the fields. In the example text file above, the first line was:

Element,Symbol

This isn't part of the data. Instead, it identifies the names of the columns in the data set. Because the default value of this property is FALSE, the UseHeader property must be set to TRUE.

Relaxing TDC Security

By default, if the DataURL property specifies a URL on a different domain than that of the Web page, the TDC will silently fail to load the data. This feature prevents unauthorized pages or untrusted scripts from using the TDC to access private data. To allow content providers to create pages that access data on a different domain, providers can insert a domain string in the data. The string begins with "@!allow_domains" and is followed by a semicolon-delimited list of domain names and/or IP addresses. The string must appear exclusively at the beginning of the first line in the data set with no preceding white-space. The exact specification for the format string is as follows:

   domain_string: header_string "=" domain_list
   header_string: "@!allow_domains"
   domain_list: domain_spec [; domain_list ]
   domain_spec: * | [*.] domain | ipaddr

Observe that while wildcards may be used in domain names (*.microsoft.com), they are not supported in IP addresses.

The following is an example of a domain string that could be embedded in a data set to enable a page hosted on all microsoft.com and investor.msn.com servers to access the data.

   @!allow_domains=*.microsoft.com; investor.msn.com

A More Advanced Example: Sorting and Filtering

The example behind the following Show Me button demonstrates how you can automate the sorting and filtering of data in a table. Using the chemistry theme, the example displays a table that contains the first five periods of the periodic table. You can sort the data by clicking any of the three table headings (Position, Element, or Symbol); you can filter the data by choosing a specific period and group from the Period or Group list box.

Sorting data

Dynamic sorting is enabled using the Sort property and the Reset method on the TDC. In the previous example, a VBScript function supports the onclick event for each column heading in the table. When the user clicks a given heading, the corresponding function is called and the Sort property is assigned a value prior to calling the Reset method. The following example shows the function that handles sorting for the Symbol column.

function symbol_onclick()
    elem_list.Sort = "+Symbol"
    elem_list.Reset()
end function

In this example, the Sort property is assigned the name of the third column (Symbol), and then the Reset method is called. The "+" indicates an ascending sort. A "-" prefix indicates a descending sort.

The following excerpt from the HTML source file for this example demonstrates how the column headings were set up using the HTML <DIV> tag.

<THEAD><TR>
     <TD><DIV ID=position><B><U><FONT COLOR=BLUE>Position</FONT></U></B></DIV></TD>
     <TD><DIV ID=element><B><U><FONT COLOR=BLUE>Element</FONT></U></B></DIV></TD>
     <TD><DIV ID=symbol><B><U><FONT COLOR=BLUE>Symbol</FONT></U></B></DIV></TD>
</TR></THEAD>

Filtering data

Dynamic filtering is enabled using the Filter property and the Reset method of the TDC. In the example, a VBScript function supports the onchange event for each drop-down list box that appears above the table. When this function is invoked, a filter expression is constructed from the selected values in the Period and Group combo boxes, the expression is assigned to the Filter property, and the Reset method is called to synchronize the table displaying the data.

The following excerpt from the HTML source file shows the definition of the Period drop-down list box.

<SELECT ID=cboPeriod>
  <OPTION SELECTED VALUE=0>ALL
  <OPTION VALUE=1>1
  <OPTION VALUE=2>2
  <OPTION VALUE=3>3
  <OPTION VALUE=4>4
  <OPTION VALUE=5>5
</SELECT>

When a user selects a different value from either the Period drop-down or the Group drop-down, the following VBScript function handles the resulting onchange event.

function FilterGroupAndPeriod()
   cFilterExpr = ""
   if cboPeriod.selectedIndex > 0 then
      cFilterExpr = "Period=" & cboPeriod.selectedIndex
   end if
   if cboGroup.selectedIndex > 0 then
      if Not IsEmpty(cFilterExpr) then
         cFilterExpr = cFilterExpr & " & "
      end if
      cFilterExpr = cFilterExpr & "Group=" & cboGroup.selectedIndex
      elem_list.object.Filter = cFilterExpr
   end if
   elem_list.object.Filter = cFilterExpr
   elem_list.Reset
end function

The code builds a single expression representing a filter on both the Period and the Group columns in the data set. Notice that if the first value (ALL) is selected in either drop-down, the respective code will not contribute to the filter expression. Also note that if the user has selected an explicit period as well as a group, the subexpressions are separated by an "&" indicating to the TDC that the records to be displayed must meet both criteria. If the user selects "ALL" in both drop-downs, none of the code within the boundaries of the conditional statements is executed, the filter expression remains empty, and all the data is displayed in the bound table.

The final line in this function invokes the Reset method, which evaluates the filter expression, applies it to the data set, and forces MSHTML to re-render the table in which the data is displayed.

Summary

This article has described the features of the Tabular Data Control, a simple read-only data source object provided with Internet Explorer 4.0. For more detailed information on the methods and properties supported by this object, see the Microsoft Tabular Data Control Reference.


Microsoft Tabular Data Control Reference

The Microsoft® Tabular Data Control allows an HTML page to display data from delimited text files, either as part of tables or a row at a time. The data can optionally be filtered or sorted by the browser under script control (with no server involvement). If the first line of the text file is a header line that describes the column names and data types, intelligent sorting and filtering will occur. For example, dates and numbers will sort as expected rather than in strict text order (that is, 2 will sort before 10). Extensions in Microsoft® Internet Explorer 4.0 allow you to bind data fields to controls on an HTML form as well as a single table row that will be expanded to show the data in all rows.

This reference describes the object, properties, and method of the Tabular Data Control.

Objects

Properties

Methods


Objects

Object

Syntax

<OBJECT ID=object
CLASSID = "clsid:333C7BC4-460F-11D0-BC04-0080C7055A83">
[<PARAM NAME=property VALUE=setting>]
</OBJECT>

Object | String identifying the object.
Property | One of the elements in the table below.
Setting | Value for the property.

Property | Description
AppendData | Specifies whether new data is appended or replaces existing data.
CaseSensitive | Indicates whether the TDC distinguishes characters in the data set based upon their case.
CharSet | Identifies the character set of the data file.
DataURL | Specifies the location of the data file.
EscapeChar | Specifies the character used to escape special characters.
FieldDelim | Specifies the character used to mark the end of data fields.
Filter | Specifies the criteria to use for filtering the data.
Language | Specifies the language of the data file, including numerical and date formats.
RowDelim | Specifies the character used to mark the end of each row.
Sort | Identifies the columns to be sorted, and ascending ordescending sort order.
TextQualifier | Specifies the optional character that surrounds a field.
UseHeader | Specifies whether the first line of the data file contains header information.

Method | Description
Reset | Causes the control to filter or sort its data based on new settings.


Properties

This section describes the TDC properties.

  • AppendData
  • CaseSensitive
  • CharSet
  • DataURL
  • EscapeChar
  • FieldDelim
  • Filter
  • Language
  • RowDelim
  • Sort
  • TextQualifier
  • UseHeader


AppendData

Specifies whether new data is appended or replaces existing data.

Syntax

dataobj.AppendData = fValue

fValue Boolean expression that controls how data from DataURL is treated. If FALSE, when new data is read it replaces the existing data set. If TRUE, it is added to the existing data. The default value is FALSE.

When this property is set to its default value of FALSE, whenever DataURL is changed and Reset is called, the Tabular Data Control will clear any data it has stored, fetch a new copy of the data, and display it according to the Filter and Sort properties. When AppendData is TRUE, a data fetch will add the data to the existing data. For example, this could be used with search results so that initial results aren't discarded.

It is assumed that the new data exactly matches the format of the first data fetched. The header line is ignored and the data is added to the existing columns. If values are the incorrect type, they will be stored as string values and will thus sort to the end of the column.


CaseSensitive

Indicates whether or not comparisons with the data should ignore case.

Syntax

dataobj.CaseSensitive = fValue

fValue Boolean value. TRUE (default) indicates the data file should be treated case-sensitively. FALSE indicates that upper- and lower-case characters should be treated equally.


CharSet

Syntax

dataobj.CharSet = sValue

Identifies the character set of the data file.

sValue String expression that describes the character set used for the data file. If no value is supplied, the input file is interpreted using codepage 1252 (Western Alphabet).

In normal use, the CharSet property is set in the Web page (or is left at its default value) and never referenced again. Although you can set the property when the data has been loaded, this will not change the interpretation of the data. The only exception to this is if the DataURL property is set to a new value that forces all properties to be reevaluated.

The following are the possible values for the CharSet property.
CharSet Value | CodePage | Description
DIN_66003 | 20106 | IA5 (German)
NS_4551-1 | 20108 | IA5 (Norwegian)
SEN_850200_B | 20107 | IA5 (Swedish)
_autodetect | 50932 | Japanese (Auto Select)
_autodetect_kr | 50949 | Korean (Auto Select)
big5 | 950 | Chinese Traditional (Big5)
csISO2022JP | 50221 | Japanese (JIS-Allow 1 byte Kana)
euc-kr | 51949 | Korean (EUC)
gb2312 | 936 | Chinese Simplified (GB2312)
hz-gb-2312 | 52936 | Chinese Simplified (HZ)
ibm852 | 852 | Central European (DOS)
ibm866 | 866 | Cyrillic Alphabet (DOS)
irv | 20105 | IA5 (IRV)
iso-2022-jp | 50220 | Japanese (JIS)
iso-2022-jp | 50222 | Japanese (JIS-Allow 1 byte Kana)
iso-2022-kr | 50225 | Korean (ISO)
iso-8859-1 | 1252 | Western Alphabet
iso-8859-1 | 28591 | Western Alphabet (ISO)
iso-8859-2 | 28592 | Central European Alphabet (ISO)
iso-8859-3 | 28593 | Latin 3 Alphabet (ISO)
iso-8859-4 | 28594 | Baltic Alphabet (ISO)
iso-8859-5 | 28595 | Cyrillic Alphabet (ISO)
iso-8859-6 | 28596 | Arabic Alphabet (ISO)
iso-8859-7 | 28597 | Greek Alphabet (ISO)
iso-8859-8 | 28598 | Hebrew Alphabet (ISO)
koi8-r | 20866 | Cyrillic Alphabet (KOI8-R)
ks_c_5601 | 949 | Korean
shift-jis | 932 | Japanese (Shift-JIS)
unicode | 1200 | Universal Alphabet
unicodeFEFF | 1201 | Universal Alphabet (Big-Endian)
utf-7 | 65000 | Universal Alphabet (UTF-7)
utf-8 | 65001 | Universal Alphabet (UTF-8)
windows-1250 | 1250 | Central European Alphabet (Windows)
windows-1251 | 1251 | Cyrillic Alphabet (Windows)
windows-1253 | 1253 | Greek Alphabet (Windows)
windows-1254 | 1254 | Turkish Alphabet
windows-1255 | 1255 | Hebrew Alphabet (Windows)
windows-1256 | 1256 | Arabic Alphabet (Windows)
windows-1257 | 1257 | Baltic Alphabet (Windows)
windows-1258 | 1258 | Vietnamese Alphabet (Windows)
windows-874 | 874 | Thai (Windows)
x-euc | 51932 | Japanese (EUC)
x-user-defined | 50000 | User Defined


DataURL

Specifies the location of the data file.

Syntax

dataobj.DataURL = sValue

sValue String expression that points to the data file using a standard URL format such as http:, ftp:, or file: (for example, http://www.microsoft.com/dummy/testdata.txt).

Normally the DataURL property is specified in the Web page along with the <OBJECT> tag for the Tabular Data Control. However, if you change this property after the page has been loaded, this will cause the data file to be loaded on the next Reset. The most common use for DataURL is to set AppendData to TRUE and combine multiple different data files. It could also be used to force the data to be read a second time. You could use this to force a refresh during debugging, for example.

See also AppendData, Reset


EscapeChar

Specifies the character used to escape special characters.

Syntax

dataobj.EscapeChar = cValue

cValue Single character string that is used to avoid the meaning of the other special characters specified by the FieldDelim, RowDelim, and TextQualifier properties. If set to a zero-length string "" (the default), there is no escape character.

Having an escape character is useful if you have data that contains the same type of characters that you are using to delimit fields or rows. For example, if the TextQualifier property is set to the quotation mark character to surround input fields, but some of the fields themselves contain quotation marks, you could edit the data file to prefix the embedded quotation marks with the escape character. In this scenario, if TextQualifier is set to " (double-quote) and you set the EscapeChar property to \ (backslash), the following data file will be interpreted correctly.

"This is cool"
"This is \"really\" cool"

See also FieldDelim, RowDelim, TextQualifier


FieldDelim

Specifies the character used to mark the end of data fields.

Syntax

dataobj.FieldDelim = sValue

sValue String expression that separates one data field from the next. A comma (,) is the default character, but you can set it to any other character. Only a single character can be used to delimit the fields.

Setting nonprintable characters is dependent on the browser language used. In the initial object tag declaration, you can set the FieldDelim property to a tab character as follows:

<PARAM NAME=FieldDelim VALUE="&#09;">

See also EscapeChar, RowDelim, TextQualifier


Filter

Specifies how the data will be filtered.

Syntax

dataobj.object.Filter = sValue

sValue String expression containing one or more columns and associated criteria. By default, this is set to the empty string (that is, no filtering occurs and all rows are displayed). An invalid expression will cause all rows to be returned. If there is no header line that names the columns, they are given default names of Column1, Column2, Column3, and so on. The special wildcard character, *, can be used to match any character.

Filter restricts the data displayed to the user. It can be set in the <OBJECT> tag description to cause initial filtering, or the browser script language can set it and it will take effect when the Reset method is called. The data is fetched only once, so this is an efficient way of displaying the same data many different ways.

The following <OBJECT> tag description will cause address book data to be filtered so that only entries with phone numbers will be displayed.

<PARAM NAME=Filter VALUE="PhoneNum <> ''">

You could use the wildcard character to match all phone numbers starting with 9 with:

<PARAM NAME=Filter VALUE="PhoneNum <> '9*'">

A more complex filter could be:

<PARAM NAME=Filter VALUE="(Quantity > 10 & color = 'lime') |
    Quantity < 5"

This code would find rows with a quantity greater than 10 that are lime colored combined with all rows that have a quantity less than five.

The exact syntax support by filter is defined below. In essence, any arbitrary expression using the usual relational operators is allowed, including comparisons between fields. AND (&) and OR (|) operators have equal precedence and thus must be surrounded by parenthesis if combined.

Complex ::== Simple
 ::== Simple '&' Simple [ '&' Simple ... ]
 ::== Simple '|' Simple [ '|' Simple ... ]
Simple ::== '(' Complex ')'
 ::== Atom Relop Atom
Relop ::== '=' | '>' | '>=' | '<' | '<=' | '<>'
Atom ::== Characters up to a (, ), >, <, =, & or |

If an atom is recognizable as a field name, it is treated as a field name. Otherwise, it's treated as a value. Quotes (") are processed and force the atom to be treated as a value. Escape characters (\) are processed and allow the use of special characters within a field name. It is illegal to attempt a comparison of two columns with different types.

The definition of 'Complex' expressly forbids mixing logical ANDs and ORs (& and |) unless parentheses are used to clarify the query. The following is illegal:

field1 > 10 & field3 = "lime" | field4 < 5

But the following is allowed:

(field1 > 10 & field3 = "lime") | field4 < 5

See also Reset, Sort, UseHeader


Language

Specifies the language of the data file, including numerical and data formats.

Note The object property is specified to avoid a conflict with the language extender property which is exposed on all elements.

Syntax

dataobj.object.Language = sValue

sValue String expression that describes the language of the data file using the HTML standard codes (as defined by ISO 369). The default value is eng-us. Set this appropriately to ensure the correct handling of decimal separator characters in floating-point data and default data interpretation.

See also CharSet


RowDelim

Specifies the character used to mark the end of each row.

Syntax

dataobj.RowDelim = sValue

sValue String expression that separates one data field from the next. The default value is "newline", but it can be set to any other character. Only a single character may be used to delimit a row.

Special interpretation is done for end-of-line or newline characters, which should provide correct parsing in most circumstances.

See also EscapeChar, FieldDelim, TextQualifier


Sort

Identifies the columns to be sorted, and ascending or descending sort order.

Syntax

dataobj.Sort = sValue

sValue String expression that is the name of one or more comma-separated names of columns in the text file. Each name can be optionally prefixed with a minus sign (-) to indicate a descending sort. By default this property is set to the empty string. If there is no header line that names the columns, they are given default names of Column1, Column2, Column3, and so on. If Sort is set to an empty string (""), no data will be sorted.

Data types are sorted as follows:
Data type | Ascending | Descending
Text | "a", "b", "c" ... "z" | "z", "y", "x" ... "a"
Numeric | ... -1, 0, 1, ... | ...1, 0, -1...
Date | 1/1/1950, 1/1/1990, 1/1/2000 | 1/1/2000, 1/1/1990, 1/1/1950
Logical | False, False, ... , True, True | True, True, ..., False, False

Sort sorts the data displayed to the users. It can be set in the initial <OBJECT> tag description to cause initial sorting, or the browser script language can set it and sorting will take effect when the Reset method is called.

Text data is sorted case-insensitively.

The following example shows how you could sort a food list into ascending order by name and decreasing price.

dataobj.Sort = "FoodItem; -Price"

All invalid data always sorts higher than valid data. For example, a string in an ascending numeric column will display at the end. Multiple invalid data rows are grouped together but not sorted into a defined order within the group.

See Also

Filter, Reset


TextQualifier

Specifies the optional character that surrounds a field.

Syntax

dataobj.TextQualifier = cValue

cValue Single character string used to surround fields that can include special characters such as newlines, tabs, or commas. These characters can also be active as field or row delimiters. The default value is the double quote character (").

Comma-delimited text files and similar text data files usually surround text fields in those files with quotes. For example, a simple phone book text file could be arranged like the following:

Fred Nurks, "42 Worldwide Way, Woy Woy", 555-1212
Brianne Hardy, "Apt 3, 14 Hopalong Crescent, Wogga", 555-2121

Normally the commas in the address text would cause the fields to be read incorrectly, but the surrounding double-quote characters avoid that.

Another common use for TextQualifier is when one of the data fields contains HTML text with lots of separate paragraphs (also known as newline characters).

See also EscapeChar, FieldDelim, RowDelim


UseHeader

Specifies whether the first line of the data file contains header information.

Syntax

dataobj.UseHeader = fValue

fValue Boolean expression that indicates that the data file contains an initial line that names each column and optionally specifies its data type.

If fValue is TRUE, the first line of the data file should match the following layout:

fieldname:type, fieldname:type, ...

Note that the above assumes the default field and row delimiters (comma and newline, respectively).

Fieldname can be an arbitrary text string, although it is best to avoid spaces and other punctuation characters.

Type can be one of the following types of values:
String | Textual data (default)
Date | Calendar dates (see below for formatting)
Boolean | Logical data (Yes/No, True/False, 0/not 0)
Int | Integral numbers (-3, 1, 5)
Float | Floating point numbers (3.141, 2.77, 0)

Date can be optionally followed by a space and then the letters D, M, and Y in any order. These correspond to Day, Month, and Year and control the interpretation of the dates in the data file. The date data is treated as three numbers separated by characters, so the actual separation character is not important.

Boolean will interpret the following data:
True values: Yes, True, 1, -1, any nonzero number
False values: No, False, 0 (zero)

The decimal separator used by float data is determined by the Language property.

The following sample data file shows how the various data types can be declared when UseHeader is set to TRUE and the default settings for FieldDelim, RowDelim, and Language are used.

FoodItem,Price:Float,Purchased:Date YMD,OnOrder:Boolean,Quantity:Int
Bread,1.57,97/5/12,Yes,30
Cheese,3.52,96/2/2,No,5
Old Wine,183.99,1905-1-1,No,1

See also DataURL, Language, Reset


Methods Methods *
  * Previous Topic: UseHeader
  * Next Topic: Reset

Methods

This section describes the Reset method.


Reset

Causes the control to filter or sort its data based on new settings.

Syntax

dataobj.Reset

When Reset is called, all the data is filtered and sorted according to the settings of the filter and sort properties. A typical use of the Reset method would be to specify a new Sort or Filter in script in response to a user action.

Data will only be fetched again if either DataURL has been changed or if the data has changed since the last Reset. Note that setting DataURL to itself is viewed as a change, so you can force a refetch of the data from script with the following:

dataobj.DataURL = Dataobj.DataURL
dataobj.Reset

After the Reset method is invoked, the browser will redisplay the data if necessary.

See also Filter, Sort


Topic Not Found

No matching topic was found. Some possible reasons and remedies are as follows:

  • The file (.chm) that contains the destination topic is not in the expected location.

    Remedy: Rerun the MSDN Library Setup.

  • The file (.chm) that contains the current topic or destination topic is out-of-date and the link is no longer valid.

    Remedy: Install the latest version of the MSDN Library.

  • The MSDN Library CD is not in the CD-ROM drive.

    Remedy: Insert the MSDN Library CD into the CD-ROM drive.


Position:INT,Symbol,FullName,Period,Group
1,H,Hydrogen,1,1
2,He,Helium,1,18
3,Li,Lithium,2,1
4,Be,Beryllium,2,2
5,B,Boron,2,13
6,C,Carbon,2,14
7,N,Nitrogen,2,15
8,O,Oxygen,2,16
9,F,Fluorine,2,17
10,Ne,Neon,2,18
11,Na,Sodium,3,1
12,Mg,Magnesium,3,2
13,Al,Aluminum,3,13
14,Si,Silicon,3,14
15,P,Phosphorus,3,15
16,S,Sulfur,3,16
17,Cl,Chlorine,3,17
18,Ar,Argon,3,18
19,K,Potassium,4,1
20,Ca,Calcium,4,2
21,Sc,Scandium,4,3
22,Ti,Titanium,4,4
23,V,Vanadium,4,5
24,Cr,Chromium,4,6
25,Mn,Manganese,4,7
26,Fe,Iron,4,8
27,Co,Cobalt,4,9
28,Ni,Nickel,4,10
29,Cu,Copper,4,11
30,Zn,Zinc,4,12
31,Ga,Gallium,4,13
32,Ge,Germanium,4,14
33,As,Arsenic,4,15
34,Se,Selenium,4,16
35,Br,Bromine,4,17
36,Kr,Krypton,4,18
37,Rb,Rubidium,5,1
38,Sr,Strontium,5,2
39,Y,Yttrium,5,3
40,Zr,Zirconium,5,4
41,Nb,Niobium,5,5
42,Mo,Molybdenum,5,6
43,Tc,Technetium,5,7
44,Ru,Ruthenium,5,8
45,Rh,Rhodium,5,9
46,Pd,Palladium,5,10
47,Ag,Silver,5,11
48,Cd,Cadmium,5,12
49,In,Indium,5,13
50,Sn,Tin,5,14
51,Sb,Antimony,5,15
52,Te,Tellurium,5,16
53,I,Iodine,5,17
54,Xe,Xenon,5,18


Sorting and Filtering with the TDC

Position | Element | Symbol


Repeated Table Binding with the TDC

Element | Symbol


Static Table

Element | Symbol
Hydrogen | H
Helium | He
Lithium | Li
Beryllium | Be
Boron | B
Carbon | C
Nitrogen | N
Oxygen | O
Flourine | F
Neon | Ne


Element,Symbol
Hydrogen,H
Helium,He
Lithium,Li
Beryllium,Be
Boron,B
Carbon,C
Nitrogen,N
Oxygen,O
Flourine,F
Neon,Ne