Connected Property

Description

Returns or sets whether the current control is connected to the Microsoft Agent server.

Syntax

agent.Connected [= boolean]

Remarks

In many situations, specifying the control automatically creates a connection with the Microsoft Agent server. For example, specifying the Microsoft Agent control's CLSID in the <OBJECT> tag in a Web page automatically opens a server connection and exiting the page closes the connection. Similarly, for Visual Basic or other languages that enable you to drop a control on a form, running the program automatically opens a connection and exiting the program closes the connection. If the server isn't currently running, it automatically starts.

However, if you want to create an Agent control at run time, you may also need to explicitly open a new connection to the server using the Connected property. For example, in Visual Basic you can create an ActiveX object at run time using the Set statement with the New keyword (or CreateObject function). While this creates the object, it will not create the connection to the server, so you must use the Connected property before any code that calls into Microsoft Agent's programming interface, as shown in the following example:

    ' Declare a global variable for the control
    Dim MyAgent as Agent

    ' Create an instance of the control using New
    Set MyAgent = New Agent

    ' Open a connection to the server
    MyAgent.Connected = True

    ' Load a character
    MyAgent.Characters.Load "Genie", "C:\Some Directory\Genie.acs"

    ' Display the character
    MyAgent.Characters("Genie").Show

Note that creating a control using this technique does not expose the Agent control's events. In Visual Basic 5.0, you can access the control's events by including the control in your project's references, and use the WithEvents keyword in your variable declaration:

    Dim WithEvents agent as Agent

    ' Create an instance of the control using New
    Set MyAgent = New Agent

Using WithEvents to create an instance of the Agent control at run time automatically opens the connection with the Microsoft Agent server. Therefore, you don't need to include a Connected statement.

You can close your control's connection to the server at run time by setting the Connected property to False. However, you must first release all references you defined to objects created by the server. In particular, you must release any references you created to character and command objects. In Visual Basic, you can disassociate a reference to an object by setting the reference to Nothing:

    Dim Genie as IAgentCtlCharacter
    
    Sub LoadCharacter

    ' Load the character into the Characters collection
    Agent1.Characters.Load "Genie", _
    "C:\Program Files\Microsoft Agent\Characters\Genie.acs"

    ' Create a reference to the character
    Set Genie = Agent1.Characters("Genie")

    End Sub

    Sub CloseConnection

    ' Release the reference to the character object
    Set Genie = Nothing

    ' Close the connection with the server
    Agent1.Connected = False

    End Sub

Although you can reopen your connection by resetting the Connected property to True, not all information established with the server in the original connection will be preserved. For example, if you loaded a character, you will have to reload it again before you can play any of its animations.

Setting the Connected property to False does not destroy your instance of the control. You must use the syntax supported by your programming language for releasing the object. For example, in Visual Basic, you set the control to Nothing:

    Set Agent1 = Nothing

Attempting to query or set the Connected property before creating the control will raise an error.

--------------------------------------------------------