The ActiveX application/x-informationCard interface

The ActiveX application/x-informationCard interface exposes CardSpace to the web via an OBJECT tag.

<object type="application/x-informationCard" onclick="javascript" name="nameValue" id="idValue" > 
    <param name="issuer" value="uri" /> 
    <param name="issuerPolicy" value="uri" /> 
    <param name="requiredClaims" value="uri uri ..." /> 
    <param name="optionalClaims" value="uri uri ..." /> 
    <param name="tokenType" value="uri" /> 
    <param name="privacyUrl" value="uri" /> 
    <param name="privacyVersion" value="unsigned int" /> 
    <param name="requireUserInteraction" value="true|false" /> 
    <param name="onDisplayReady" value="javascript-function-name" /> 
    <param name="displayType" value="none|cardtile" /> 
</object> 

Parameters

Remarks

In general, most of the attributes and parameters are optional, with the following exceptions:

• The name attribute must be specified for form-based submission.

• The privacyVersion parameter must be specified and non-zero if the privacyUrl parameter is present.

• The issuer parameter must be present if the issuerPolicy parameter is present.

Requirements

Header: Declared in olectl.h.

Methods

The ActiveX control also exposes the following methods that you can invoke using script:

• bool hasCapability (string capability). This method takes one string parameter, which is a case-sensitive capability name. The method returns true if the specified capability is supported; otherwise, it returns false.

  The following table lists the capabilities for which you can query.

  Means that	Supports
  soap1_1	Supports SOAP 1.1 messages.
  soap1_2	Supports SOAP 1.2 messages.
  trust1_3	Supports the WS-Trust 1.3 protocol.
  trustFeb2005	Supports the WS-Trust February 2005 protocol, also called WS-Trust 1.2.
  usernamePasswordCredential	Supports managed cards backed by username/password credentials.
  kerberosV5Credential	Supports managed cards backed by Kerberos credentials.
  x509V3Credential	Supports managed cards backed by X.509 certificate credentials.
  x509KeyIdentifier	Supports wsse:KeyIdentifier within managed cards backed by X.509 certificates.
  x509Principal	Supports ic09:X509Principal within managed cards backed by X.509 certificates.
  x509SubjectAndIssuer	Supports ic09:x509SubjectAndIssuer within managed cards backed by X.509 certificates.
  cardtile	Supports the displayTypeCardTile OBJECT tag property.
  noSsl	Supports relying party applications that do not use SSL certificates.
  requireUserInteraction	Supports the requireUserInteraction OBJECT tag property.
  rpSts	Supports retrieving tokens using a Relying Party STS (RP-STS).
  tryGetTokenAutomatic	Supports the tryGetTokenAutomatic OBJECT tag method. This method is described in the following item.

• ICardOperation tryGetTokenAutomatic (function callback). This method takes one parameter, which is a script callback function to invoke when the attempt to get a token is complete. The method returns an object with a cancel method and a read-only status property.

  • The cancel method, which takes no parameters and returns no value, cancels the attempt to get a token. If the attempt is cancelled, the callback method is not invoked.

  • The status property returns an integer that indicates the status of the attempt to get a token, as follows.

    Value	Meaning
    0	The operation is in progress.
    1	The operation completed successfully. The issue token is available through the OBJECT tag’s value property.
    2	The operation could not complete without user interaction.

    The completion callback function should inspect the value returned by the status property and retrieve the token, if available, using the OBJECT tag’s value property.

  A page on a Relying Party Web site calls this method to request that a token be retrieved automatically, using a pre-selected card. For example, if a default card is associated with the Relying Party, or the administrator has configured a card for the Relying Party, this method attempts to get a token from the Claims Provider for that card.

Example

Invoking CardSpace via a FORM Submit: This example demonstrates retrieving a token via HTML's FORM mechanisms. When the form is submitted, CardSpace will pop up. When the user selects a card, the value of the returned token will be sent as a form parameter with the provided name. In this case, the name will be "token".

<html>
    <head>
        <title>Form-Based Object Tag</title>
    </head>
    <body>
        <form method="post" action="process.html">
            <object type="application/x-informationCard" name="token">
                <param name="issuer" value="https://microsoft.com/" />
            </object>
            <button type="submit">Click here to submit a card</button>
        </form>
    </body>
</html>

Invoking CardSpace using JavaScript: This example demonstrates retrieving a token through JavaScript. When the button is clicked, the value property is accessed. The first time value is accessed, CardSpace will be shown. Subsequent accesses will return the same token.

<html>
    <head>
        <title>Script-Based Object Tag</title>
    </head>
    <body>
        <script>
            function retrieveToken()
            {
                var objectTag = document.getElementById( 'token' );
                alert( objectTag.value );
            }
        </script>
        <form method="post" action="process.html">
            <object type="application/x-informationCard" id="token">
                <param name="issuer" value="https://microsoft.com/" />
            </object>
            <button onclick='retrieveToken();'>Click here to retrieve a card</button>
        </form>
    </body>
</html>

Catching Exceptions when Invoking CardSpace: This example demonstrates using JavaScript exception handling to detect the user cancelling the token request. -1073413869 maps onto the E_ICARD_USERCANCELLED error code.

<html>
    <head>
        <title>Script-Based Object Tag With Error Handling</title>
    </head>
    <body>
        <script>
            function fetchToken()
            {
                var objectTag = document.getElementById( "token" );
                try
                {
                    alert( "Token retrieved: " + objectTag.value );
                }
                catch( ex )
                {
                    if( ex.number == -1073413869 )
                    {
                        alert( "The user cancelled the operation." );
                    }
                    else
                    {
                        alert( "Unknown error occurred: " + ex.number );
                    }
                }
            }

        </script>
        <form method="post" action="process.html">
            <b>Click on the purple I to select a card.</b>
            <object type="application/x-informationCard" id="token" onclick="fetchToken();">
                <param name="issuer" value="https://microsoft.com/" />
                <param name="displayType" value="cardtile" />
            </object>
        </form>
    </body>
</html>

Copyright © 2007 by Microsoft Corporation. All rights reserved.