Windows Messenger

Purpose

Windows® Messenger is an application that allows users to make PC-PC or PC-phone connections over the Internet. Either voice or voice and video calls can be established. The user of this service must make provisions with an Internet Telephony Service Provider (ITSP) to establish the network transport for the call. Windows Messenger provides an ActiveX® control that can be used on a Web page to establish calls as well as a mechanism to make provisions with an ITSP.

Where Applicable

Windows Messenger can be placed a Web page for use by businesses that advertise on the Internet. A click-to-talk button can be placed on a Web page that allows customers to talk directly to service representatives. Customers can access this service on a one-time-use basis.

Developer Audience

This technology is used by Web developers for businesses that want to create a customer service page on their Web site.

Run-time Requirements

Windows Messenger requires Whistler.

See Also

About Windows Messenger Client Provisioning

Using Windows Messenger Client Provisioning

Windows Messenger Client Provisioning Reference

Windows Messenger Real-time Communications API

Client Provisioning Reference

Feedback

Make error reports and feature requests directly to Microsoft.

Microsoft Platform SDK, February 2001 Edition.
This content last built on Thursday, February 01, 2001.


Windows Messenger Real-time Communications API

[This is preliminary documentation and subject to change.]

Real-time Communications is an end-user application that allows clients to make audio/video phone calls from their computer over an IP-based Internet connection. PC-PC, PC-phone, and phone-phone calls are currently supported. Windows Messenger can be used by a residential client or placed in an ActiveX® control on a Web page. A typical business application might be an e-commerce Web site with a click-to-talk button that allows customers to call their service representatives. The e-commerce company would make provisions with an Internet Telephony Service Provider (ITSP) to supply the network transport for the call using Windows Messenger.

The following material provides a general review of the Windows Messenger parameters and schema used by the Web site developer to provision the client for a one-time use of Windows Messenger.

  • About Windows Messenger Client Provisioning describes the HTML mechanism used to invoke a Windows Messenger session on a Web page and the XML container to store the client provisioning profiles.
  • Using Windows Messenger Client Provisioning covers more specific information useful in writing an HTML Web page to make a Windows Messenger call. Code snippets used on a customer service Web page and an example of the XML provisioning profile is also presented.
  • Windows Messenger Client Provisioning Reference presents the parameters passed to the Windows Messenger ActiveX control and the XML schema for creating the single-use provisioning profiles.


About Windows Messenger Client Provisioning

Windows Messenger can be used as a stand-alone application that is run from the command line, or it can be implemented as an ActiveX® control embedded in a Web page. Web developers can implement a one-time use of Windows Messenger that allows them to customize their call sessions to display video, or show a dial pad for credit card or other data entry. A provisioning profile to specify the line features and service provider used to place the call must also be included in the Web control. The provisioning profiles are stored in an XML document (see XML Sample Profile). For more information on the Web page mechanism to create a Windows Messenger call, see HTML Code Snippet.


Web Mechanism

Windows Messenger clients can initiate a one-time-use call, with an ActiveX control embedded in a Web page. The Web control uses an HTML object to instantiate the ActiveX control, which then places the Windows Messenger call from the Web site. Call control parameters such as video display or destination URL can be passed to the object in the HTML <param> tags. This control can be easily created in an editor such as Microsoft® FrontPage® and requires no additional code. The XML provisioning profile is used to store the Session Initiation Protocol (SIP), user ID session mode, and other line-related parameters along with the private ITSP data. For an example of the HTML code to set up a single-use call, see HTML code snippet. For a list of the call control parameters, see HTML parameters.


XML Provisioning Profiles

For a client to access an Internet telephony service, a profile must be created to "provision" or contract the client with a service provider. The profile contains the service provider, user ID, user URI, SIP, proxy address, and other user account information. The Web developer prepares the provisioning data in the format shown in the XML Sample Profile and passes the profile to the ActiveX control from the HTML parameter.


Using Windows Messenger Client Provisioning

A customer service Web page may contain the Windows Messenger ActiveX® control that is used to initiate a call. The control is created by the HTML object in the Web page and passed specific parameters used to customize the call. The provisioning profiles are passed to the ActiveX control and contain client information such as user ID and line configurations such as SIP Server. The profiles are stored in an XML document (see XML Sample Profile). For an example of the HTML code to instantiate the ActiveX component, see the HTML Code Snippet. The types of sessions currently supported by Windows Messenger are given in the Session Information section.


Session Information

The following table lists the modes and terminal types that are currently supported in the Windows Messenger application. The call mode can be either first party (client initiates the call) or third party (service provider initiates the call). The terminal can be a device on the PSTN network such as a phone, or an IP network device such as a PC. If the mode is First Party, the consumer has an IP terminal, and the provider terminal is PSTN, the SIP Server supports a PC-phone session initiated from the PC. Although there are several possible combinations of terminal/mode configurations, Windows Messenger currently supports only a subset of them.

Mode | Consumer terminal | Provider terminal | Supported
First Party | IP Terminal | IP Terminal | Yes
First Party | IP Terminal | PSTN Terminal | Yes
First Party | PSTN Terminal | IP Terminal | No
First Party | PSTN Terminal | PSTN Terminal | No
Third Party | IP Terminal | IP Terminal | No
Third Party | IP Terminal | PSTN Terminal | No
Third Party | PSTN Terminal | IP Terminal | No
Third Party | PSTN Terminal | PSTN Terminal | Yes


HTML Code Snippet

The following code snippet shows the HTML Web page code used to invoke the Windows Messenger ActiveX control for a PC-PC call. Parameters are passed to the HTML object in the <param> tags and allow easy customization of the control. The provisioning profile for a one-time-use call is passed through the Provisioning Profile parameter. The profile is meant for a single-use call and can only be used for a specific destination URL. In addition, the code can specify the download location for the profile, if the client doesn't exist on the user's PC. For a list of parameters that can be used by the Windows Messenger control, see HTML Parameters.

<CENTER>
<OBJECT
    ID="RTCDLL"
    CLASSID="CLSID:A9329EEC-64FF-4EB4-BD89-FF99385D1D37">
    <param
        name="DestinationName"
        value="Vishwa Jhonst">
    <param
        name="CallScenario"
        value="0">
    <param
        name="ShowDialpad"
        value="0">
    <param
        name="AutoPlaceCall"
        value="1">
    <param
        name="ProvisioningProfile"
        value = "<ResClientOneTimeUsageProvisioningInfo
        xmlns=&quot;provisioning.xml&quot;>
        <UserInfo
            UserId=&quot;vishwaj@microsoft.com&quot;
            Password=&quot;c%y2&quot;
            UserURI=&quot;sip:vishwaj@microsoft.com&quot;>
        </UserInfo>
        <SIPServer
            Address=&quot;vishwaj-nb3&quot;
           Transport=&quot;UDP&quot;
            AuthMethod=&quot;md5&quot;
            Role=&quot;Proxy&quot;>
            <SessionInfo mode=&quot;FirstParty&quot;>
                <TerminalInfo
                    ConsumerTerminal=&quot;IP_Terminal&quot;
                    ProviderTerminal=&quot;IP_Terminal&quot;/>
            </SessionInfo>
        </SIPServer>
        <SIPServer
            Address=&quot;vishwaj-nb3&quot;
            Transport=&quot;UDP&quot;
            AuthMethod=&quot;md5&quot;
            Role=&quot;Registrar&quot;>
            <SessionInfo
                mode=&quot;FirstParty&quot;>
                <TerminalInfo
                    ConsumerTerminal=&quot;IP_Terminal&quot;
                    ProviderTerminal=&quot;IP_Terminal&quot;/>
            </SessionInfo>
        </SIPServer>
        </ResClientOneTimeUsageProvisioningInfo>">
    <param
        name="DisableVideoReception"
        value="0">
    <param
        name="DisableVideoTransmission"
        value="0">
    <param
        name="DisableVideoPreview"
        value="0">
</OBJECT>
</HTML>

See Also

Web Mechanism, XML One-time-use Schema, XML Sample Profile


XML Sample Profile

In a Web customer relations scenario, the client can be provisioned on a one-off basis. The profile created for this purpose can be used to call only a particular destination URL. The element in the XML schema that is used for one-time provisioning is the "ResClientOneTimeUsageProvisioningInfo". An example of a one-time usage profile is shown below:

<ResClientOneTimeUsageProvisioningInfo
        xmlns="provisioning.xml">
        <UserInfo
                UserId="John Smith"
                Password="not4now"/>
        <SIPServer
                Address="264.23.34.232"
                Transport="UDP"
                AuthMethod="digest"
                Role="Proxy">
                <SessionInfo
                       mode="FirstParty">
                        <TerminalInfo
                                ConsumerTerminal="IP_Terminal"
                                ProviderTerminal="IP_Terminal"/>
                </SessionInfo>
        </SIPServer>
        <ITSPPrivateData>
                <ProvisioningVersion>1.0</ProvisioningVersion>
                <BillTo>buy.com</BillTo>
        </ITSPPrivateData>
</ResClientOneTimeUsageProvisioningInfo>

See Also

XML One-time-use Schema, HTML Code Snippet, XML Provisioning Profiles


Windows Messenger Client Provisioning Reference

The following table provides links to the XML provisioning schema and the HTML parameter tags used by the ActiveX® control.

Interface groupings | Description
HTML Parameters | The HTML parameter tags used in the Web page to create the Windows Messenger ActiveX control.
XML One-time-use Schema | The XML schema used to provision the client for a one-time-only call.


HTML Parameters

In addition to the standard HTML parameter tags, the Windows Messenger ActiveX control accepts the following parameters.

Parameter type/name | Description
BSTR DestinationUrl | The destination URL address is a mandatory parameter.
BSTR DestinationName | Displayable name for the destination.
Int CallScenario | One of three call scenarios that are currently supported. The default value is zero (PC to PC), 1 is for PC-phone, and 2 is for phone-phone connections.
Bool ShowDialpad | A value of 1 will display the dialpad. This parameter is valid only when the connection is PC to phone.
XML ProvisioningProfile | The provisioning profile is a required parameter. The text is used as the provisioning profile for the session and is not persistent beyond this call. The use of this profile is limited to one call only, and either the profile itself or the server must enforce this.
Bool AutoPlaceCall | A value of 1 means a session is created using the given destination URL. The default value is zero, meaning no session is created and the normal is UI shown.
Bool DisableVideoReception | A value of 1 means received video is not displayed. The default value is set to zero to play displayed video.
Bool DisableVideoTransmission | A value of 1 means video is not sent. The default value is set to zero to send video.
Bool DisableVideoPreview | A value of 1 means sent video is not displayed. The default value is set to zero to display sent video.

Remarks

C++ applications can use the parameter tags programmatically outside of the context of an HTML page; however, direct method calls are easier. The C++ application can query for the same interfaces and invoke the same methods that the Web browser uses in the case of an HTML page.

In general, parameter tags are not used to replace all APIs for the following reasons:

  • Parameters can be passed only at instantiation time and never later, such as on a user action.
  • There is limited programmatic feedback for error conditions.
  • No out parameters are possible.
  • Only strings can be passed into the object as parameters.
  • Packaging the parameters in a property bag is relatively cumbersome.

See Also

Web Mechanism, HTML Code Snippet


XML One-time-use Schema

The provisioning schema is an XML document that contains the service provider, user account, address of proxy, registrar, and other SIP-related information. The XML schema for provisioning a client for a one-time use is listed below.

<?xml version="1.0"?>
<Schema
        name = "ProvisioningSchema.xml"
        xmlns = "urn:schemas-microsoft-com:xml-data"
        xmlns:dt = "urn:schemas-microsoft-com:datatypes">
<comments>
        Schema Version
        MajorRevisionNumber = 0
        MinorRevisionNumber = 5
</comments>

<ElementType
        name = "ResClientOneTimeUsageProvisioningInfo"
        model="closed"
        content="eltonly"
        order = "seq">
        <element type="UserInfo"/>
        <element
            type="SIPServer"
              minOccurs="1"
            maxOccurs="1"/>
        <element type="ITSPPrivateData"/>
</ElementType>

<ElementType
        name="UserInfo"
        model="closed"
        content="eltonly"
        order="seq">
        <AttributeType
            name ="UserId"/>
        <attribute
            type="UserId"/>
        <AttributeType
            name="Password"
            required="no"/>
        <!--Password will not be present if userid is anonymous-->
        <attribute
            type="Password"/>
        <AttributeType
            name ="UserURI"/>
        <!-- Represents the ID as the user is known to others, This ID is used
                       in the From, To, and Contact fields in the SIP messages.-->
        <attribute
            type="UserURI"/>
</ElementType>

<ElementType
        name="SIPServer"
        model="closed"
        content="mixed"
        order="seq">
        <AttributeType
            name ="Address"/>
        <attribute
            type="Address"/>
        <AttributeType
            name="Transport"
            dt:type="enumeration"
            dt:values="TCP UDP SSL"/>
        <attribute
            type = "Transport"/>
        <AttributeType
            name="AuthMethod"
            dt:type="enumeration"
            dt:values="basic
            md5digest"/>
        <attribute
             type = "AuthMethod"/>
        <AttributeType
            name="Role"
            dt:type="enumeration"
            dt:values="Proxy Registrar"/>
        <attribute
            type = "AuthMethod"/>
        <element
            type="SessionInfo"
            minOccurs="0"
            maxOccurs="*"/>
</ElementType>

<ElementType
        name="ITSPPrivateData"
        model="open">
        <!--For use by ITSPs to store private information
                   like Provisioning Version, account info, and so on.-->
</ElementType>
</Schema>

Remarks

  • The SIPServer record can represent a Proxy or Registrar, depending on the "Role" attribute.
  • Ιf the Authmethod is "basic," the Transport must be "SSL" for security reasons.
  • The SessionInfo tag represents the types of sessions supported by the SIPServer. The mode and terminals supported are shown in the Session Information section.

See Also

XML Sample Profile, XML Provisioning Profiles


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.