pcaole

OLE Automation Guide

OLE Automation Guide

Legal NoticeCopyright 2008 Symantec Corporation. All rights reserved.

Symantec, the Symantec Logoare trademarks or registered trademarks of SymantecCorporation or its affiliates in the U.S. and other countries. Other names may be trademarksof their respective owners.

This Symantec product may contain third party software for which Symantec is requiredto provide attribution to the third party (Third Party Programs). Some of the Third PartyPrograms are available under open source or free software licenses. The License Agreementaccompanying the Software does not alter any rights or obligations you may have underthose open source or free software licenses. Please see the Third Party Legal Notice Appendixto this Documentation or TPIP ReadMe File accompanying this Symantec product for moreinformation on the Third Party Programs.

The product described in this document is distributed under licenses restricting its use,copying, distribution, and decompilation/reverse engineering. No part of this documentmay be reproduced in any form by any means without prior written authorization ofSymantec Corporation and its licensors, if any.

THE DOCUMENTATION IS PROVIDED "AS IS" AND ALL EXPRESS OR IMPLIED CONDITIONS,REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OFMERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT,ARE DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TOBE LEGALLY INVALID. SYMANTEC CORPORATION SHALL NOT BE LIABLE FOR INCIDENTALOR CONSEQUENTIAL DAMAGES IN CONNECTION WITH THE FURNISHING,PERFORMANCE, OR USE OF THIS DOCUMENTATION. THE INFORMATION CONTAINEDIN THIS DOCUMENTATION IS SUBJECT TO CHANGE WITHOUT NOTICE.

The Licensed Software and Documentation are deemed to be commercial computer softwareas defined in FAR 12.212 and subject to restricted rights as defined in FAR Section 52.227-19"Commercial Computer Software - Restricted Rights" and DFARS 227.7202, "Rights inCommercial Computer Software or Commercial Computer Software Documentation", asapplicable, and any successor regulations. Any use, modification, reproduction release,performance, display or disclosure of the Licensed Software and Documentation by the U.S.Government shall be solely in accordance with the terms of this Agreement.

Symantec Corporation20330 Stevens Creek Blvd.Cupertino, CA 95014

http://www.symantec.com

Printed in the United States of America.

10 9 8 7 6 5 4 3 2 1

Technical SupportSymantec Technical Support maintains support centers globally. TechnicalSupports primary role is to respond to specific queries about product featuresand functionality. The Technical Support group also creates content for our onlineKnowledge Base. The Technical Support group works collaboratively with theother functional areas within Symantec to answer your questions in a timelyfashion. For example, the Technical Support group works with Product Engineeringand Symantec Security Response to provide alerting services and virus definitionupdates.

Symantecs maintenance offerings include the following:

A range of support options that give you the flexibility to select the rightamount of service for any size organization

Telephone and Web-based support that provides rapid response andup-to-the-minute information

Upgrade assurance that delivers automatic software upgrade protection

Global support that is available 24 hours a day, 7 days a week

Advanced features, including Account Management Services

For information about Symantecs Maintenance Programs, you can visit our Website at the following URL:

www.symantec.com/techsupp/

Contacting Technical SupportCustomers with a current maintenance agreement may access Technical Supportinformation at the following URL:


Before contacting Technical Support, make sure you have satisfied the systemrequirements that are listed in your product documentation. Also, you should beat the computer on which the problem occurred, in case it is necessary to replicatethe problem.

When you contact Technical Support, please have the following informationavailable:

Product release level

Hardware information

Available memory, disk space, and NIC information

Operating system

Version and patch level

Network topology

Router, gateway, and IP address information

Problem description:

Error messages and log files

Troubleshooting that was performed before contacting Symantec

Recent software configuration changes and network changes

Licensing and registrationIf your Symantec product requires registration or a license key, access our technicalsupport Web page at the following URL:


Customer serviceCustomer service information is available at the following URL:


Customer Service is available to assist with the following types of issues:

Questions regarding product licensing or serialization

Product registration updates, such as address or name changes

General product information (features, language availability, local dealers)

Latest information about product updates and upgrades

Information about upgrade assurance and maintenance contracts

Information about the Symantec Buying Programs

Advice about Symantec's technical support options

Nontechnical presales questions

Issues that are related to CD-ROMs or manuals

Maintenance agreement resourcesIf you want to contact Symantec regarding an existing maintenance agreement,please contact the maintenance agreement administration team for your regionas follows:

[email protected] and Japan

[email protected], Middle-East, and Africa

[email protected] America and Latin America

Additional enterprise servicesSymantec offers a comprehensive set of services that allow you to maximize yourinvestment in Symantec products and to develop your knowledge, expertise, andglobal insight, which enable you to manage your business risks proactively.

Enterprise services that are available include the following:

These solutions provide early warning of cyber attacks, comprehensive threatanalysis, and countermeasures to prevent attacks before they occur.

Symantec Early Warning Solutions

These services remove the burden of managing and monitoring security devicesand events, ensuring rapid response to real threats.

Managed Security Services

Symantec Consulting Services provide on-site technical expertise fromSymantec and its trusted partners. Symantec Consulting Services offer a varietyof prepackaged and customizable options that include assessment, design,implementation, monitoring, and management capabilities. Each is focused onestablishing and maintaining the integrity and availability of your IT resources.

Consulting Services

Educational Services provide a full array of technical training, securityeducation, security certification, and awareness communication programs.

Educational Services

To access more information about Enterprise services, please visit our Web siteat the following URL:

www.symantec.com

Select your country or language from the site index.

Technical Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

Chapter 1 Using OLE Automation with SymantecpcAnywhere . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

About OLE Automation .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9About the pcAnywhere Automation Server ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10What you can do with the pcAnywhere Automation Server ... . . . . . . . . . . . . . . . 10Before you start ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Automatically registering the remote engine .... . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Manually registering the remote engine .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Accessing the pcAnywhere Automation Server ... . . . . . . . . . . . . . . . . . . . . . . . . . 12Accessing the pcAnywhere Automation Server with Visual

Basic ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12Accessing the pcAnywhere Automation Server with Visual

C++ .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Launching host and remote OLE objects ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Where to find more information .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Chapter 2 Visual Basic object definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17About Visual Basic objects ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17CRemoteDataManager methods .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18CRemoteData properties ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Connection type properties ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23Dialing properties ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25COM device properties ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26NetBIOS device properties ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29ISDN via CAPI 2.0 device properties ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

CRemoteDataEx object ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31Visual Basic sample code for remote functionality ... . . . . . . . . . . . . . . . . . . . . . 32

CHostDataManager methods .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34CHostData properties ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Connection type properties ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38AssignConnection(ConnectionType) method .... . . . . . . . . . . . . . . . . . . . . . . . . . . . 41UnassignConnection(ConnectionType) method .... . . . . . . . . . . . . . . . . . . . . . . . . 41Dialing properties ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Contents

COM device properties ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42NetBIOS device properties ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45ISDN via CAPI 2.0 device properties ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

CHostDataEx object ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Visual Basic sample code for host functionality ... . . . . . . . . . . . . . . . . . . . . . . . . 54

Awrem32 functions .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Chapter 3 Visual C++ object definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59About Visual C++ objects ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59CRemoteDataManager methods .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60CRemoteData object ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Get and Set methods .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63Remote object Detail methods .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66Remote object methods .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

CRemoteDataEx object ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70Visual C++ sample code for remote functionality ... . . . . . . . . . . . . . . . . . . . . . . 70

CHostDataManager methods .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71CHostData object ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

Get and Set methods .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75Host object Detail methods .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76Host object methods .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

CHostDataEx object ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82Visual C++ sample code for host functionality ... . . . . . . . . . . . . . . . . . . . . . . . . . . 84

Awrem32 functions .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

Contents8

UsingOLEAutomationwithSymantec pcAnywhere

This chapter includes the following topics:

About OLE Automation

About the pcAnywhere Automation Server

What you can do with the pcAnywhere Automation Server

Before you start

Where to find more information

About OLE AutomationOLE Automation is a technology that lets you create an external application orother development tool (such as a script or macro) that can control and automateany exposed function within an application.

OLE Automation consists of the following components:

An application or software component that exposes itsfunctionality so that it can be accessed or controlled byother applications or development tools

The pcAnywhere Automation Server is an example of anOLE Automation server.

OLE Automation server

1Chapter

An application or development tool that accesses andcontrols the components that have been exposed by theOLE Automation server

You can use any programming language that supports OLEAutomation. The two most common programminglanguages are Microsoft Visual Basic and Microsoft VisualC++.

OLE Automation controller

An external application accesses an OLE Automation server by connecting to theserver and then requesting access to one or more of its published interfaces. Aninterface is an entry point that allows access to one or more related methods orproperties. After an application obtains an interface to the server, it can then callany internal interface method as though it were part of the external application.

About the pcAnywhere Automation ServerThe pcAnywhere Automation Server lets external applications managepcAnywhere remote and host files to automate remote control and file transfertasks. The pcAnywhere Automation Server functions as a programmablereplacement for the Symantec pcAnywhere user interface and mirrors much ofits default behavior.

For example, when you create a host object in pcAnywhere, the first availablemodem TAPI device is assigned by default. Similarly, when you create a host objectusing the pcAnywhere Automation Server and then enumerate through the listof assigned connections, the first available modem TAPI device is already assigned.

What you can do with the pcAnywhere AutomationServer

The pcAnywhere Automation Server lets you automate a variety of administrativeand productivity tasks.

You can use the pcAnywhere Automation Server to do the following:

Automatically distribute and install software updates on multiple computersacross your network

Schedule automatic file transfers between computers for audit or archivepurposes

Automatically add a name to or remove a name from the allowed callers liston every pcAnywhere host on your network

Using OLE Automation with Symantec pcAnywhereAbout the pcAnywhere Automation Server

10

This document contains several examples, written in both Visual Basic and VisualC++, to illustrate how to connect to and use the pcAnywhere Automation Server.

See About Visual Basic objects on page 17.

See About Visual C++ objects on page 59.

Before you startDuring a connection to the pcAnywhere Automation Server and its interfaces,identifier parameters, known as globally unique identifiers (GUIDs), are passedto the automation library API functions. A separate GUID is assigned to thepcAnywhere Automation Server and to each exposed interface. These GUIDs mustbe present in the system registry to connect an external application to thepcAnywhere Automation Server and its interfaces.

You can register the GUID entries automatically if you are running the externalapplication on a computer on which Symantec pcAnywhere is installed. Otherwise,you must register the GUID entries manually.

See Automatically registering the remote engine on page 11.

See Manually registering the remote engine on page 11.

Automatically registering the remote engineBefore you connect to another computer for the first time using your OLE client,you must self-register the remote engine. You can do this automatically when youstart a remote object in Symantec pcAnywhere.

To automatically register the remote engine

1 To open Symantec pcAnywhere, do one of the following:

On the desktop, double-click the Symantec pcAnywhere program icon.

On the Windows taskbar, clickStart>Programs>SymantecpcAnywhere.

2 In the pcAnywhere Manager window, click Remotes.

3 Double-click a remote connection item.

This process registers the remote engine. You do not need to complete theconnection.

Manually registering the remote engineIf pcAnywhere is not installed on the computer on which you are running theexternal application, you must register the GUIDs manually by running the

11Using OLE Automation with Symantec pcAnywhereBefore you start

pcAnywhere Automation Server executable file (Winawsvr.exe). You only needto run the executable file once to add the GUIDs to the registry. The Winawsvr.exefile is located in the installation directory.

Accessing the pcAnywhere Automation ServerYou can access the pcAnywhere Automation Server using any language platformthat supports OLE Automation. The two most popular language platforms thatsupport OLE Automation are Visual Basic and Visual C++.

The coding principles for these two platforms are similar, although in the VisualBasic environment, much of the low-level work is performed behind the scenesby the Visual Basic run-time system.

Accessing the pcAnywhere Automation Server with Visual BasicThe Visual Basic programming language has built-in support to interact with OLEAutomation servers, such as the pcAnywhere Automation Server. You create aStandard Exe project, and then enter code in each method to access thepcAnywhere Automation Server. Visual Basic takes the high-level method callsin the source files and expands them internally into the corresponding low-levelOLE Automation method calls.

To access the pcAnywhere Automation Server with Visual Basic

1 Add a pair of Object variables for each pcAnywhere object that you want toaccess.

For example, when working with remote objects, DIM aRemoteDataManagerand a RemoteDataObject as Object.

2 Use the RemoteDataManager to attach to the remote objects data manager.

For example, call the CreateObject method withWINAWSVR.REMOTEDATAMANAGER as a parameter.

Visual Basic uses the textual parameter to locate the managers identifier inthe registry and returns the interface to that manager.

3 Once there is a valid data manager object, use it to do any of the following:

Determine the current directory.

Change to another directory.

Enumerate the associated data object files in the current directory.

Using OLE Automation with Symantec pcAnywhereBefore you start

12

Create, retrieve, or delete a data object file.

4 After a data object is created or retrieved, you can get or set properties of theobject.

The Visual Basic syntax does not use a propertys name to differentiatebetween getting and setting its value. Instead, the propertys position inrelation to the assignment operator determines whether the underlyingmethod call is a Get or a Set.

The following examples demonstrate a Get and a Set:

To get an objects phone number value, place the property name to theright of the assignment operator.For example, s = RemoteData.PhoneNumber(), where s is a string variable.

To set the phone number, place the property name to the left of theassignment operator.For example, RemoteData.PhoneNumber = "555-1212"

Accessing the pcAnywhere Automation Server with Visual C++The pcAnywhere Automation Server uses type libraries to expose informationabout its interfaces and methods to automation clients that are written in VisualC++. These type libraries use Microsoft Foundation Classes (MFC), which can beimported into your application using the Visual C++ ClassWizard.

The data manager classes that are provided in the type libraries provide thefunctionality that is needed to obtain an interface to the pcAnywhere AutomationServer and perform high-level operations on the interfaces associated objecttype.

Use the data manager object to do the following:

Determine or change the current directory.

Enumerate through the list of data object files in the current directory.

Create, retrieve, or delete a named object.

Once created or retrieved, an object uses the associated data object class to examineor modify any of its exposed properties. Most of these properties are exposedthrough a pair of methods that begin with the word Get or Set. For example, auser calls the GetPhoneNumber method to examine the objects current phonenumber property and calls SetPhoneNumber to set it.

Importing and viewing classesThe pcAnywhere Automation Server uses the following type libraries:

13Using OLE Automation with Symantec pcAnywhereBefore you start

Provides the information needed to connect to the pcAnywhereAutomation Server and access its interfaces

Winawsvr.tlb

Provides the information needed to control pcAnywhere connectionsAwrem32.tlb

The following procedures explain how to import the class definitions from thepcAnywhere Automation Server type libraries into your MFC application and thenview the classes that have been added to your application.

To import classes

1 In Visual C++, create an MFC application.

2 On the View menu, click ClassWizard.

3 In the Class Wizard dialog box, click AddClass, and then click Froma typelibrary.

4 Double-click winawsvr.tlb.

5 In the Confirm Classes dialog box, click OK to import all class definitions.

6 In the Class Wizard dialog box, click AddClass, and then click Froma typelibrary.

7 Double-click awrem32.tlb.

8 In the Confirm Classes dialog box, click OK to import all class definitions.

9 In the Class Wizard dialog box, click OK to complete the import process.

The classes are added to the application. These classes let you manipulateobjects and manage connections.

Importing the class definitions from the type libraries also adds support filesto the application. These files contain the class definitions and implementationsource code for the pcAnywhere Automation Server.

See Viewing the class definitions and implementation files on page 14.

To view the added classes

1 In Visual C++, open your MFC application.

2 In the Workspace window, click the ClassView tab.

Viewing the class definitions and implementation filesWhen you import the pcAnywhere Automation Server type libraries into yourapplication, the following files are added:

Winawsvr.h

Winawsvr.cpp

Using OLE Automation with Symantec pcAnywhereBefore you start

14

Awrem32.h

Awrem32.cpp

These files contain the class definitions and implementation source code for thepcAnywhere Automation Server. You do not need to edit these files; however,each application source file that contains calls to the pcAnywhere AutomationServer methods must include Winawsvr.h.

To view the class definitions and implementation files

1 In Visual C++, open your MFC application.

2 In the Workspace window, click the FileView tab.

Launching host and remote OLE objectsSymantec pcAnywhere requires that you store all host and remote objects in thedefault data directory. Before you launch a host or remote object that you createdusing OLE, ensure that the object is located in the pcAnywhere default datadirectory. The default directory is the All Users folder in Windows XP, and is theProgramData folder in Vista.

Where to find more informationFor more information about OLE automation, see the following references:

Box, Don. 1998. Essential COM. Reading, Mass.: Addison-Wesley.

Horton, Ivor. 1997. Beginning MFC Programming. Birmingham, UK.: WroxPress.

Rogerson, Dale. 1997. Inside COM. Redmond, Wash.: Microsoft Press.

Templeman, Julian. 1997. Beginning MFC COM Programming. Birmingham,UK.: Wrox Press.

15Using OLE Automation with Symantec pcAnywhereWhere to find more information

Using OLE Automation with Symantec pcAnywhereWhere to find more information

16

Visual Basic objectdefinitions


About Visual Basic objects

CRemoteDataManager methods

CRemoteData properties

CRemoteDataEx object

CHostDataManager methods

CHostData properties

CHostDataEx object

Awrem32 functions

About Visual Basic objectsThe pcAnywhere Automation Server provides the following components to supportOLE Automation:


Winawsvr

Provides the information needed to control pcAnywhere connectionsAwrem32

Table 2-1 describes the objects that comprise Winawsvr.

2Chapter

Table 2-1 Winawsvr objects

ReferenceDescriptionObject

See CRemoteDataManager methodson page 18.

Provides the methods for creating, opening,modifying, saving, and deletingCRemoteData objects

CRemoteDataManager

See CRemoteData properties on page 21.

See CRemoteDataEx object on page 31.

Defines the parameters for accessing andcontrolling pcAnywhere remotefunctionality

CRemoteData

See CHostDataManager methodson page 34.

Provides the methods for creating, opening,modifying, saving, and deleting CHostDataobjects

CHostDataManager

See CHostData properties on page 36.

See CHostDataEx object on page 47.

Defines the parameters for accessing andcontrolling pcAnywhere host functionality

CHostData

Awrem32 has one object, which consists of eight interfaces to support remotecontrol and file transfer sessions.

See Awrem32 functions on page 55.

Some functions are no longer supported. However, object definitions are providedfor use with earlier versions of pcAnywhere.

For functions that require passwords, password values can be set but not retrieved.This is for security purposes.

CRemoteDataManager methodsThe CRemoteDataManager methods provide the parameters and return valuesfor accessing and controlling CRemoteData objects.

Table 2-2 CRemoteDataManager methods

DescriptionParameter or returnvalue

CRemoteDataManagermethod

Returns the full path name of thecurrent directory in whichpcAnywhere remote objects arestored

Return Value = StringCurrentDirectory()

Changes the current directory inwhich pcAnywhere remote objectsare stored

Parameter =NewDirectory

ChangeDirectory(NewDirectory)

Visual Basic object definitionsCRemoteDataManager methods

18

Table 2-2 CRemoteDataManager methods (continued)



Finds the first pcAnywhere remoteobject file (*.chf) in the currentdirectory; file name pattern filtersbased on the specified file namepattern (an asterisk [*] finds all filesin the current directory)

Parameter = Pattern asstring

FindFirst(Pattern)

Return buffer for the full path nameof the remote object file (*chf) thatmatches the specified pattern

Parameter = Name asstring

FindFirst(Name string)

Return buffer for the full path nameof the remote object file thatmatches the pattern that is specifiedin the original call to FindFirst()


FindNext(Name)

TRUE if another remote object filethat matches the pattern that isspecified in the call to FindFirst() isfound. The full path name of thematching file is stored in Name

Return value = BooleanFindNext(Name)

The fully qualified remote object filename to be loaded


RetrieveObject(Name)

Specifies how this object is to beused. This relates to the passwordprotection

The options are as follows:

0 = Not specified

1 = View only

2 = View and Modify

3 = Execute

Parameter =AccessMode as integer

RetrieveObject(AccessMode)

Object password. May be NULLParameter = Passwordas string

RetrieveObject(Password)

The fully qualified remote object filename to be loaded


RetrieveObjectEx(Name)

19Visual Basic object definitionsCRemoteDataManager methods

Table 2-2 CRemoteDataManager methods (continued)



Specifies how this object is to beused. This relates to the passwordprotection


0 = Not specified

1 = View only

2 = View and Modify

3 = Execute

Parameter =AccessMode as integer

RetrieveObjectEx(AccessMode)

Object password. May be NULLParameter = Passwordas string

RetrieveObjectEx(Password)

CRemoteDataEx object from thespecified file

Return value = ObjectRetrieveObjectEx

Creates a CRemoteData object andreturns an LPDISPATCH pointer toit. The parameter is the fullyqualified remote object file namefor the new object


CreateObject(Name)

CRemoteDataReturn value = ObjectCreateObject

Creates a CRemoteDataEx objectand returns an LPDISPATCHpointer to it. The parameter is thefully qualified remote object filename for the new object


CreateObjectEx(Name)

CRemoteDataExReturn value = ObjectCreateObjectEx

The fully qualified remote object filename of the object to be deleted


DeleteObject(Name)

Object passwordParameter = Passwordas string

DeleteObject(Password)

TRUE if object is deletedReturn value = BooleanDeleteObject

Visual Basic object definitionsCRemoteDataManager methods

20

CRemoteData propertiesThe properties and parameters that are available for the CRemoteData object areshown as follows.

In Table 2-3, replace the information in angle brackets with the actual values.

Table 2-3 CRemoteData properties and parameters

DescriptionParameterProperty

Sets the computer name or IP address of thehost computer.

String.ComputerName(String)

Sets the phone number of the host computer.String.PhoneNumber(String)

Sets the system dialing properties.Bool.UseDialingProperties(Bool)

Sets the number of redial attempts beforecancelling the call.

Integer.RedialCount(Integer)

Sets the number of seconds to wait betweenredial attempts.

Integer.RedialDelay(Integer)

Sets the name of the user for automatic login.

For more information about using domainlogins:


String.AutoLoginName(String)

Sets the password for automatic logins in theremote object.

For security reasons, the pcAnywhereAutomation Server does not provide the abilityto read the password value. A password valueis not returned.

String.AutoLoginPassword(String)

Sets the password on the remote object for usewith the ExecuteProtection, ReadProtection,and WriteProtection settings.


String.Password(String)

Sets the requirement of a password to executethe object. Set by Password.

Bool.ExecuteProtection(Bool)

21Visual Basic object definitionsCRemoteData properties

Table 2-3 CRemoteData properties and parameters (continued)


Sets the requirement of a password to view theproperties of the remote object. Set byPassword.

Bool.ReadProtection(Bool)

Sets the requirement of a password to savechanges to the remote object. Set by Password.

Bool.WriteProtection(Bool)

Activates and deactivates session logging.Bool.LogSession(Bool)

Sets the fully qualified path and name to thelocation of the file that records the activesession.

String.RecordFile(String)

Activates and deactivates automatic sessionrecording.

Bool.RecordSession(Bool)

Sets the password of the object. Use thisproperty to refresh the local data copy of theremote object.

String.ReadObject(String)

Sets the password of the object. Use thisproperty to create the remote object or to writechanges that you have made to the remoteobject.

String.WriteObject(String)

The properties and return values for CRemoteData are shown in the followingtable.


Table 2-4 CRemoteData properties and return values

DescriptionReturn valueProperty

Returns the computer name or IP address ofthe host computer

StringString = .ComputerName

Returns the phone number of the hostcomputer

StringString = .PhoneNumber

Returns the system dialing properties that areset in the remote object

BoolBool = .UseDialingProperties

Returns the number of redial attempts that isset in the remote object

IntegerInteger = .RedialCount

Visual Basic object definitionsCRemoteData properties

22

Table 2-4 CRemoteData properties and return values (continued)


Returns the number of seconds between redialattempts

IntegerInteger = .RedialDelay

Returns the login name that is used forautomatic logins

StringString = .AutoLoginName

Returns the value of the ExecuteProtectionsetting

BoolBool = .ExecuteProtection

Returns the value of the ReadProtectionsetting

BoolBool = .ReadProtection

Returns the value of the WriteProtectionsetting

BoolBool = .WriteProtection

Returns TRUE if session logging is enabledBoolBool = .LogSession

Returns the fully qualified path and name ofthe session recording file

StringString = .RecordFile

Returns the value of the session recordingsetting

BoolBool = .RecordSession

Connection type propertiesThe following table defines the connection type properties and parameters.



Table 2-5 Connection type properties and parameters


Sets the connection type of the remote. Thevalue that is passed in must be a validconnection type as defined by theFirstConnectionType() andNextConnectionType() functions.

The following are examples of valid connectiontypes:

COM1

COM2

COM3

COM4

TCP/IP

SPX

NetBIOS

ISDN via CAPI 2.0

Modem name (as it appears on thecomputer)

String.ConnectionType(String)

The following table defines the connection type properties and return values.


Table 2-6 Connection type properties and return values


Returns the connection type of the remoteobject.

StringString = .ConnectionTypes


24

Table 2-6 Connection type properties and return values (continued)


Returns the number of available connectiontypes.


COM1

COM2

COM3

COM4

TCP/IP

SPX

NetBIOS

ISDN via CAPI 2.0


IntegerInteger = .ConnectionType

Returns the first available connection type.StringString = .FirstConnectionType

Returns the next available connection type.This is called sequentially for the number ofconnection types that is set in.ConnectionType to enumerateall connection types.

StringString = .NextConnectionType

Returns TRUE if the named connection typeis found in the list of available connectiontypes.

BoolBool =.FindConnectionType(ConnectionType)

Dialing propertiesThe following table defines the properties and parameters for setting the dialingproperties for modem connections.


Table 2-7 Properties and parameters for dialing properties


Sets the area code dialing properties formodem connections

String.AreaCode(String)


Table 2-7 Properties and parameters for dialing properties (continued)


Sets the country code dialing properties formodem connections

String.CountryCode(String)

The following table defines the properties and return values for modem dialingproperties.


Table 2-8 Properties and return values for dialing properties


Returns the area code dialing properties.StringString = .AreaCode

Returns the dialing properties country code.StringString = .CountryCode

Returns the number of available country codes.IntegerInteger = .CountryCodes

Returns the first available country code thatis listed in the operating system.

StringString = .FirstCountryCode

Returns the next available country code. Thisis called sequentially for the number of countrycodes that is set in to enumerateall country codes.

StringString = .NextCountryCode

COM device propertiesThe following table describes the properties and parameters that let you customizethe port settings for modem and other COM-based connections.



26

Table 2-9 COM device properties and parameters


Sets the communications parity

The following values are valid:

Odd

Even

Mark

Space

String.ComParity(String)

Sets the flow control of COM-based connectiontypes


XONXOFF

RTS/CTS

Both

String.ComFlowControl(String)

Sets the start setting of COM-based connectiontypes


Always connected

Carrier detect (DCD)

Clear to send (CTS)

Data set ready (DSR)

Ring indicator (RI)

Receive 2 s

Modem response

String.ComStartedBy(String)

Sets the end setting of COM-based connectiontypes


Always connected


Clear to send (CTS)


Ring indicator (RI)

String.ComEndedBy(String)


Table 2-9 COM device properties and parameters (continued)


Contains the maximum COM speed setting


110

300

600

1200

2400

4800

9600

38400

57600

115200

Long.ComSpeed(Long)

The following table describes the COM device properties and return values.


Table 2-10 COM device properties and return values


Returns one of the following values forcommunications parity:

Odd

Even

Mark

Space

StringString = .ComParity

Returns the Com Flow setting of the remoteobject


XONXOFF

RTS/CTS

Both

StringString = .ComFlowControl


28

Table 2-10 COM device properties and return values (continued)


Returns the Com Start control of COM-basedconnection types


Always connected


Clear to send (CTS)


Ring indicator (RI)

Receive 2 s

Modem response

StringString = .ComStartedBy

Returns the Com End control of COM-basedconnection types


Always connected


Clear to send (CTS)


Ring indicator (RI)

StringString = .ComEndedBy

Returns the current setting of the Com Speedof the remote object


110

300

600

1200

2400

4800

9600

38400

57600

115200

LongLong = .ComSpeed

NetBIOS device propertiesThe following table defines the property and parameter for a NetBIOS networkdevice.



Table 2-11 NetBIOS property and parameter


Sets the LAN Adapter (LANA) number forNetBIOS connections

Integer.LanaNumber(Integer)

The following table defines the NetBIOS property and return value.


Table 2-12 NetBIOS property and return value


Returns the current setting of the LAN Adapter(LANA) number for NetBIOS connections

IntegerInteger = .LanaNumber

ISDN via CAPI 2.0 device propertiesThe following table defines the properties and parameters for European ISDNconnections.


Table 2-13 ISDN via CAPI 2.0 properties and parameters


Activates or deactivates channel bonding forISDN CAPI devices

Bool.CapiChannelBonding(Bool)

Sets any additional CAPI extensions that areneeded for communications

String.CapiExtensions(String)

The following table defines the properties and return values for European ISDNconnections.


Table 2-14 ISDN via CAPI 2.0 properties and return values


Returns the current ISDN CAPI channelbonding setting in the remote object

BoolBool= .CapiChannelBonding


30

Table 2-14 ISDN via CAPI 2.0 properties and return values (continued)


Returns the current list of CAPI extensionsfrom the remote object

StringString = .CapiExtensions

CRemoteDataEx objectThe CRemoteDataEx object contains the same functionality as the CRemoteDataobject with some additional functionality.

The following table describes the properties and parameters.


Table 2-15 CRemoteDataEx parameters


Sets the name of the private key container touse.

String.PrivateKey(String)

Sets the common name of the private key touse.

String.CertificateName(String)

Sets the encryption level.


-1: None

0: pcAnywhere

1: Symmetric

2: Public key

Byte.EncryptionLevel(Byte)

Defines whether the remote computer allowsa connection to a host computer that uses alower level of encryption.

Bool.DenyLowerEncrypt(Bool)

Sets the domain name for automatic logins.This option is used with NT authentication andWindows authentication.

String.AutoDomain(String)

The following table describes the properties and return values for theCRemoteDataEx object.


31Visual Basic object definitionsCRemoteDataEx object

Table 2-16 CRemoteDataEx properties and return values


Returns the name of the currently activeprivate key container.

StringString = .PrivateKey

Returns the common name of the activeprivate key container.

StringString = .CertificateName

Returns one of the following encryptionsettings:

-1: None

0: pcAnywhere

1: Symmetric

2: Public key

ByteByte = .EncryptionLevel

Returns the value of the deny lower encryptionsetting.

BoolBool = .DenyLowerEncrypt

Returns the domain name setting forautomatic logins. This option is used with NTauthentication and Windows authentication.

StringString = .AutoDomain

Visual Basic sample code for remote functionalityThe following Visual Basic sample code retrieves a remote data object and modifiesits properties:

Private Sub Command1_Click()

Dim RemoteDataManager as Object

Dim RemoteData as Object

Dim s as string

'Create CRemoteDataManager object

Set RemoteDataManager = CreateObject(WINAWSVR.REMOTEDATAMANAGER)

'display and change current directory

s = RemoteDataManager.CurrentDirectory()

MsgBox ( s )

RemoteDataManager.ChangeDirectory ("C:\dev\bin.w32\data")

s = RemoteDataManager.CurrentDirectory()

MsgBox ( s )

Visual Basic object definitionsCRemoteDataEx object

32

'retrieve remote data object

Set RemoteData = RemoteDataManager.RetrieveObjectEx("pod.CHF",

2, 0)

'display some properties

s = RemoteData.AreaCode()

MsgBox (s)

s = RemoteData.PhoneNumber()

MsgBox (s)

'set some properties

RemoteData.AreaCode = "212"

RemoteData.PhoneNumber = "555-5555"

'write object to disk

RemoteData.WriteObject (0)

End Sub

Use the FindFirst and FindNext methods to display the remote file in a directoryas follows:




Dim s as string

Set RemoteDataManager =

CreateObject("WINAWSVR.REMOTEDATAMANAGER")

RemoteDataManager.ChangeDirectory

("C:\dev\bin.w32\data")

RemoteDataManager.FindFirst "*", s

MsgBox (s)

RemoteDataManager.FindNext s

MsgBox (s)

End Sub

33Visual Basic object definitionsCRemoteDataEx object

Create a remote object. Set the connection type to TCP/IP and the computer name"Host1," and then launch it as follows:




Dim s as string

Set RemoteDataManager =

CreateObject("WINAWSVR.REMOTEDATAMANAGER")

MsgBox (RemoteDataManager.CurrentDirectory())

RemoteDataManager.ChangeDirectory ("C:\dev\bin.w32\data")

MsgBox (RemoteDataManager.CurrentDirectory())

Set RemoteData = RemoteDataManager.CreateObject("test")

RemoteData.ConnectionType = "TCP/IP"

RemoteData.ComputerName = "Host1"

s = RemoteData.ConnectionType

MsgBox (s)

s = RemoteData.ComputerName

MsgBox (s)

RemoteData.WriteObject (0)

End Sub

CHostDataManager methodsThe CHostDataManager methods provide the parameters and return values foraccessing and controlling CHostData objects.

DescriptionParameter orreturn value

CHostDataManagermethod

The full path name of the currentpcAnywhere data directory in whichpcAnywhere host objects are stored

Return value =String

CurrentDirectory()

File name pattern to filter object files (anasterisk [*] finds all files in the currentdirectory)

Parameter =Pattern as string

FindFirst(Pattern)

Return buffer for the full path name of thehost object file that matches the specifiedpattern

Parameter =Name as string

FindFirst(Name string)

Visual Basic object definitionsCHostDataManager methods

34



TRUE if a host object file matching thespecified pattern is found. The full path nameof the matching file is stored in Name

Return value =Boolean

FindFirst

Return buffer for the full path name of thehost object file that matches the patternspecified in the original call to FindFirst()


FindNext(Name)

TRUE if another host object file matching thepattern specified in the call to FindFirst() isfound. The full path name of the matchingfile is stored in Name


FindNext

The fully qualified host object file name to beloaded


RetrieveObject(Name)

Specifies how this object is to be used. Thisrelates to the password protection. Theoptions are as follows:

0 = Not specified

1 = View only

2 = View and Modify

3 = Execute

Parameter =AccessMode asinteger

RetrieveObject(AccessMode)

Object password. May be NULLParameter =Password asstring

RetrieveObject(Password)

CHostData object from the specified fileReturn value =Object

RetrieveObject

The fully qualified host object file name to beloaded


RetrieveObjectEx(Name)

Specifies how this object is to be used. Thisrelates to the password protection


0 = Not specified

1 = View only

2 = View and Modify

3 = Execute

Parameter =AccessMode asinteger

RetrieveObjectEx(AccessMode)

35Visual Basic object definitionsCHostDataManager methods



Object password. May be NULLParameter =Password asstring

RetrieveObjectEx(Password)

CHostDataEx object from the specified fileReturn value =Object

RetrieveObjectEx

Creates a CHostData object and returns anLPDISPATCH pointer to it. The parameter isthe fully qualified host object file name forthe new object


CreateObject(Name)

CHostDataReturn value =Object

CreateObject

Creates a CHostDataEx object and returns anLPDISPATCH pointer to it. The parameter isthe fully qualified host object file name forthe new object


CreateObjectEx(Name)

CHostDataExReturn value =Object

CreateObjectEx

The fully qualified host object file name ofthe object to be deleted


DeleteObject(Name)

Object passwordParameter =Password asstring

DeleteObject(Password)

TRUE if object is deletedReturn value =Boolean

DeleteObject

Launches a host object file, which opens thepcAnywhere host terminal window. Theparameter is the fully qualified host objectfile of the object to be launched


Launch(Name)

TRUE if object is successfully launchedReturn value =Boolean

Launch

CHostData propertiesThe following table describes the properties and parameters that are availablefor the CHostData object.

Visual Basic object definitionsCHostData properties

36


Table 2-17 CHostData properties and parameters


Sets the phone number of the host computer.String.PhoneNumber(String)

Sets the system dialing properties.Bool.UseDialingProperties(Bool)

Sets the number of redial attempts beforecancelling the call.

Integer.RedialCount(Integer)

Sets the number of seconds to wait betweenredial attempts.

Integer.RedialDelay(Integer)

Sets the password on the host object for usewith the ExecuteProtection, ReadProtection,and WriteProtection settings.


String.Password(String)

Sets the requirement of a password to executethe object. Set by Password.

Bool.ExecuteProtection(Bool)

Sets the requirement of a password to view theproperties of the host object. Set by Password.

Bool.ReadProtection(Bool)

Sets the requirement of a password to savechanges to the host object. Set by Password.

Bool.WriteProtection(Bool)

Activates and deactivates session logging.Bool.LogSession(Bool)

Sets the fully qualified path and name to thelocation of the file that records the activesession.

String.RecordFile(String)

Activates and deactivates automatic sessionrecording.

Bool.RecordSession(Bool)

Sets the password for the object. You can usethis property to refresh the local data copy ofthe host object.

String.ReadObject(String)

Sets the password for the object. Use thisproperty to create the host object or to writechanges that you have made to the host object.

String.WriteObject(String)

37Visual Basic object definitionsCHostData properties

The following table describes the CHostData properties and return values.


Table 2-18 CHostData properties and return values


Returns the phone number of the hostcomputer

StringString = .PhoneNumber

Returns the use of the system dialingproperties that are set in the host object

BoolBool = .UseDialingProperties

Returns the number of redial attempts that isset in the host object

IntegerInteger = .RedialCount

Returns the number of seconds between redialattempts

IntegerInteger = .RedialDelay

Returns the value of the ExecuteProtectionsetting

BoolBool = .ExecuteProtection

Returns the value of the ReadProtectionsetting

BoolBool = .ReadProtection

Returns the value of the Write Protectionsetting

BoolBool = .WriteProtection

Returns TRUE if session logging is enabledBoolBool = .LogSession

Returns the fully qualified path and name ofthe session recording file

StringString = .RecordFile

Returns the value of the session recordingsetting

BoolBool = .RecordSession

Connection type propertiesThe following table describes the connection type properties and parameters.



38

Table 2-19 Connection type properties and parameters


Sets the connection type of the host. The valuethat is passed in must be a valid connectiontype as defined by the FirstConnectionType()and NextConnectionType() functions.


COM1

COM2

COM3

COM4

TCP/IP

SPX

NetBIOS

ISDN via CAPI 2.0


String.ConnectionType(String)

Sets the connection type that is defined in thestring to active status.

String.AssignConnection(String)

Sets the connection type that is defined in thestring to inactive status.

String.UnassignConnection(String)

The following table describes the connection type properties and return values.


Table 2-20 Connection type properties and return values


Returns the connection type of the hostobject.

StringString = .ConnectionTypes


Table 2-20 Connection type properties and return values (continued)


Returns the number of available connectiontypes.

The following are examples of validconnection types:

COM1

COM2

COM3

COM4

TCP/IP

SPX

NetBIOS

ISDN via CAPI 2.0


IntegerInteger = .ConnectionType

Returns the first available connection type.StringString = .FirstConnectionType

Returns the next available connection type.This is called sequentially for the number ofconnection types that is set in.ConnectionTypes to enumerateall connection types.

StringString = .NextConnectionType

Returns TRUE if the named connection typeis found in the list of available connectiontypes.

BoolBool =.FindConnectionType(ConnectionType)

Returns the maximum number of connectiontypes that can be active on this host.

IntegerInteger = .MaxAssignedConnections

Returns the first assigned active connectiontype.

StringString = .FirstAssignedConnection

Returns the next assigned active connectiontype.

StringString = .NextAssignedConnection

Returns TRUE if the connection type that ispassed in matches any of the activeconnection types.

BoolBool =.FindAssignedConnection(ConnectionType)


40

AssignConnection(ConnectionType) methodThe AssignConnection(Connection Type) method places the requested connectiontype on the host objects list of assigned connection types and makes it the currentconnection type when processing subsequent device-specific method calls.

If the requested connection type is already on the list of assigned connections,the list of assigned connections does not change. Only the current connectiontype is changed to the requested type. It is normal to call the AssignConnectionmethod on the same object multiple times in the course of getting and settingconnection-specific values.

AssignConnection returns TRUE if the connection type that is passed in exists onthe computer and is either successfully assigned or already assigned. It returnsFALSE if either the requested connection type does not exist on the computer orthe current assigned connection count is already at the maximum allowed level.

A pcAnywhere host object can support up to two assigned connection types. TheAssignConnection method returns FALSE if it detects an attempt to exceed thislimit.

The following table defines the AssignConnection parameter:

DescriptionParameter

The name of a connection device type to be assignedConnectionType asstring

The following table defines the AssignConnection return value:

DescriptionReturn value

TRUE if this device type is available and the maximum allowedassigned connection count has not already been reached

Boolean

UnassignConnection(ConnectionType) methodThe UnassignConnection(Connection Type) method returns TRUE if the connectiontype that is passed in is successfully removed from the list of assigned connectiontypes.

The following table defines the UnassignConnection parameter:

DescriptionParameter

The name of a connection device type to be unassignedConnectionType asstring


The following table defines the UnassignConnection return value:

DescriptionReturn value

TRUE if this device type is successfully unassignedBoolean

Dialing propertiesThe following table defines the properties and return values for setting the dialingproperties for modem connections.


Table 2-21 Properties and parameters for modem dialing properties


Sets the area code for the modem connectionsString.AreaCode(String)

Sets the country code for modem connectionsString.CountryCode(String)

The following table defines the properties and return values for modem dialingproperties.


Table 2-22 Properties and return values for modem dialing properties


Returns the area code.StringString = .AreaCode

Returns the country code.StringString = .CountryCode

Returns the number of available country codes.IntegerInteger = .CountryCodes

Returns the first available country code thatis listed in the operating system.

StringString= .FirstCountryCode

Returns the next available country code. Thisis called sequentially for the number of countrycodes that is set in .CountryCodesto enumerate all country codes.

StringString = .NextCountryCode

COM device propertiesThe following table defines the properties and parameters that let you customizethe port settings for modem and other COM-based connections.


42


Table 2-23 COM device properties and parameters


Sets the communications parity


Odd

Even

Mark

Space

String.ComParity(String)

Sets the flow control of COM-based connectiontypes


XONXOFF

RTS/CTS

Both

String.ComFlowControl(String)

Sets the start setting of COM-based connectiontypes


Always connected


Clear to send (CTS)


Ring indicator (RI)

Receive 2 s

Modem response

String.ComStartedBy(String)

Sets the end setting of COM-based connectiontypes


Always connected


Clear to send (CTS)


Ring indicator (RI)

String.ComEndedBy(String)


Table 2-23 COM device properties and parameters (continued)


Sets the maximum COM speed setting


110

300

600

1200

2400

4800

9600

38400

57600

115200

Long.ComSpeed(Long)

The following table describes the COM device properties and return values.


Table 2-24 COM device properties and return values


Returns one of the following values as thecommunications parity:

Odd

Even

Mark

Space

StringString = .ComParity

Returns the Com Flow setting of the host object


XONXOFF

RTS/CTS

Both

StringString = .ComFlowControl


44

Table 2-24 COM device properties and return values (continued)


Returns the Com Start control of COM-basedconnection types


Always connected


Clear to send (CTS)


Ring indicator (RI)

Receive 2 s

Modem response

StringString = .ComStartedBy

Returns the Com End control of COM-basedconnection types


Always connected


Clear to send (CTS)


Ring indicator (RI)

StringString = .ComEndedBy

Returns the current setting of the Com Speedof the host object


110

300

600

1200

2400

4800

9600

38400

57600

115200

LongLong = .ComSpeed

NetBIOS device propertiesThe following table defines the property and parameter for NetBIOS networkdevices.



Table 2-25 NetBIOS property and parameter


Sets the LAN Adapter (LANA) number forNetBIOS connections

Integer.LanaNumber(Integer)

The following table defines the property and return value for NetBIOS networkdevices.


Table 2-26 NetBIOS return values


Returns the current setting of the LAN Adapter(LANA) number for NetBIOS connections

IntegerInteger = .LanaNumber

ISDN via CAPI 2.0 device propertiesThe following table defines the properties and parameters for European ISDNconnections.


Table 2-27 ISDN via CAPI 2.0 properties and parameters


Activates or deactivates channel bonding forISDN CAPI devices

Bool.CapiChannelBonding(Bool)

Sets any additional CAPI extensions that areneeded for communications

String.CapiExtensions(String)

Table 2-28 defines the properties and return values for European ISDNconnections.

Table 2-28 ISDN via CAPI 2.0 properties and return values


Returns the current ISDN CAPI channelbonding setting in the host object

BoolBool= .CapiChannelBonding


46

Table 2-28 ISDN via CAPI 2.0 properties and return values (continued)


Returns the current list of CAPI extensionsfrom the host object

StringString = .CapiExtensions

CHostDataEx objectThe CHostDataEx object contains the same functionality as the CHostData objectwith some additional functionality.

The following table describes the properties and parameters.


Table 2-29 CHostDataEx properties and parameters


Sets the name of the private key container touse.

String.CryptPrivateKey(String)

Sets the common name of the private key touse.

String.CryptCommonName(String)

Sets the encryption level.


-1: None

0: pcAnywhere

1: Symmetric

2: Public key

Byte.CryptReqLevel(Byte)

Defines whether the host computer acceptsconnections from a remote computer that usesa lower level of encryption.

Bool.CryptRefuseLower(Bool)

Sets the fully qualified path to the caller files.String.CallersPath(String)

Defines whether the host user will be promptedto confirm connections.

Bool.ConfirmConnect(Bool)

Sets the number of seconds before the promptto confirm the connection time limit expires.

Byte.ConfirmTimeout(Byte)

47Visual Basic object definitionsCHostDataEx object

Table 2-29 CHostDataEx properties and parameters (continued)


Defines whether the connection should beended if the prompt to confirm the connectiontime limit expires.

Bool.ConfirmDeny(Bool)

Forces the use of case-sensitive passwords.Bool.PwCaseSensitive(Bool)

Sets the number of consecutive failed logonattempts that are allowed before ending theconnection.

Byte.PwAttempts(Byte)

Sets the number of minutes that a user has tocomplete the logon before the connection isdropped.

Byte.PwTimeout(Byte)

Defines which mouse and keyboard will beactive during the connection.


0: Host and remote

1: Host

2: Remote

Byte.ActiveKbds(Byte)

Sets the number of minutes in which thekeyboard and mouse can be inactive before theconnection is ended.

Byte.InactiveTimeout(Byte)

Sets the lock host computer upon startupsetting.

Bool.LockSystemWhileWait(Bool)

Sets the run minimized host startup option.Bool.MinimizeOnLaunch(Bool)

Enables the host to run as a service.Bool.RunAsService(Bool)

Sets the number of minutes to wait beforeallowing another caller to connect.

Byte.ConnLostWait(Byte)

Defines whether to wait for another connectionor cancel the host if the session endsabnormally.


FALSE: Wait

TRUE: Cancel host

Bool.ConnLostHostOpts(Bool)

Visual Basic object definitionsCHostDataEx object

48



Activates or deactivates the end of sessionsecurity options for sessions that endabnormally.

Bool.EnableConnLostSecurity(Bool)

Sets the authentication type.


0: pcAnywhere

1: pcAnywhere

2: Windows

3: NT

4: pcAnywhere

5: pcAnywhere

6: ADS Active Directory Services

7: Microsoft LDAP

8: FTP

9: HTTP

10: HTTPS

11: RSA SecurID

pcAnywhere authentication is used by defaultif no authentication value is set or if the setvalue is not valid (for example, theauthentication type is not available).

Byte.AuthenticationType(Byte)

Sets the security options for handling anabnormal end of session.


1: Log off user

2: Restart host computer

3: Lock computer

Byte.ConnLostSecurity(Byte)

Sets the number of seconds to wait before thehost modem calls back the remote.

Byte.CallbkDelay(Byte)

Defines whether the host waits for anotherconnection or is cancelled after a normal endof session.


FALSE: Wait for next connection

TRUE: Cancel host

Bool.EndSessHostOpts(Bool)




Activates or deactivates the security optionsfor a normal end of session.

Bool.EnableEndSessSecurity(Bool)

Sets the security options for a normal end ofsession.


1: Log off user


3: Lock computer

Byte.EndSessSecurity(Byte)

Sets screen blanking on the host computer.Some video cards do not support this option.

Bool.BlankHost(Bool)

Disables the use of the mouse on the remotecomputer during a session.

Bool.AllowRemoteMouse(Bool)

Forces the computer to restart after any endof session if TRUE.

Bool.RebootOnDisconnect(Bool)

Logs off the user after the session ends.Bool.PasswordAfterDisc(Bool)

Logs failed password attempts.Bool.LogFailures(Bool)

Enables drive security options. This setting isvalid only on NTFS file systems.

Bool.AllowDriveSecurity(Bool)

Enables the use of directory services forauthentication.

Bool.UseDirectoryServices(Bool)

Sets the directory services settings.String.DirectoryServiceEntry(String)

The following table describes the properties and return values for the CHostDataExobject.


Table 2-30 CHostDataEx properties and return values


Returns the currently active private keycontainer.

StringString = .CryptPrivateKey

Returns the common name of the activeprivate key container.

StringString = .CryptCommonName


50

Table 2-30 CHostDataEx properties and return values (continued)


Returns one of the following encryptionsettings:

-1: None

0: pcAnywhere

1: Symmetric

2: Public key

ByteByte = .CryptReqLevel


BoolBool = .CryptRefuseLower

Returns the currently active path to the callerfiles.

StringString = .CallersPath

Returns the value of the confirm connectionsetting.

BoolBool = .ConfirmConnect


ByteByte = .ConfirmTimeout

Returns the value of the disconnect if timeoutsetting.

BoolBool = .ConfirmDeny

Returns the value of the make passwords casesensitive setting.

BoolBool = .PwCaseSensitive

Returns the value of the limit login attemptsper call setting.

ByteByte = .PwAttempts

Returns the value of the limit time to completelogin setting (in minutes).

ByteByte = .PwTimeout

Returns the active keyboard and mousesettings.


0: Host and remote

1: Host

2: Remote

ByteByte = .ActiveKbds

Returns the number of minutes to wait beforedisconnecting if the inactivity time limitexpires.

ByteByte = . InactiveTimeout

Returns the lock host computer upon startupsetting.

BoolBool = .LockSystemWhileWait




Returns the run minimized on host startupsetting.

BoolBool = .MinimizeOnLaunch

Returns the run host as a service setting.BoolBool = .RunAsService

Returns the number of minutes to wait beforeallowing another connection.

ByteByte = .ConnLostWait

Returns whether to wait for anotherconnection or cancel the host if the sessionends abnormally.


FALSE: Wait

TRUE: Cancel host

BoolBool = .ConnLostHostOpts

Returns the value of the security option thatis set for handling an abnormal end of session.

BoolBool = .ConnLostWait

Returns the number reference of theauthentication type.


0: pcAnywhere

1: pcAnywhere

2: Windows

3: NT

4: pcAnywhere

5: pcAnywhere

6: ADS Active Directory Services

7: Microsoft LDAP

8: FTP

9: HTTP

10: HTTPS

11: RSA SecurID

pcAnywhere authentication is used by defaultif no authentication value is set or if the setvalue is not valid (for example, theauthentication type is not available).

ByteByte = .AuthenticationType


52



Returns the numeric representation of thesecurity level that is set for handling anabnormal end of session.


1: Log off user


3: Lock computer

ByteByte = .ConnLostSecurity

Returns the number of seconds to wait beforethe host modem calls back the remote.

ByteByte = .CallbkDelay

Returns whether the host waits for anotherconnection or is cancelled after a normal endof session.


FALSE: Wait for next connection

TRUE: Cancel host

BoolBool = .EndSessHostOpts

Returns whether the end of session securityoptions are enabled for a normal end ofsession.

BoolBool = .EnableEndSessSecurity

Returns the security option that is set for anormal end of session.


1: Log off user


3: Lock computer

ByteByte = .EndSessSecurity

Returns the screen blanking option that is set.BoolBool = .BlankHost

Returns whether the remote user has keyboardand mouse control during a session.

BoolBool = .AllowRemoteMouse

Returns whether the host computer isrestarted after the session ends.

BoolBool = .RebootOnDisconnect

Returns whether the host user is logged offafter the session ends.

BoolBool = .PasswordAfterDisc

Returns whether the log password failuresoption is set.

BoolBool = .LogFailures




Returns whether the drive security option isenabled.

BoolBool = .AllowDriveSecurity

Returns whether the directory services optionis enabled.

BoolBool = .UseDirectoryServices

Returns the directory service settings.StringString = .DirectoryServiceEntry

Visual Basic sample code for host functionalityThe following Visual Basic sample code retrieves a host data object and modifiesits properties:


Dim HostDataManager as Object

Dim HostData as Object

Dim s as string

'Create CHostDataManager object

Set HostDataManager = CreateObject(WINAWSVR.BEHOSTDATAMANAGER)

'display and change current directory

s = HostDataManager.CurrentDirectory()

MsgBox ( s )

HostDataManager.ChangeDirectory ("C:\dev\bin.w32\data")

s = HostDataManager.CurrentDirectory()

MsgBox ( s )

'retrieve remote data object

Set HostData = HostDataManager.RetrieveObject("pod.BHF", 2, 0)

'display some properties

s = HostData.AreaCode()

MsgBox (s)

s = HostData.PhoneNumber()

MsgBox (s)

'set some properties


54

RemoteData. HostData = "212"

RemoteData. HostData = "555-5555"

'write object to disk

HostData.WriteObject (0)

End Sub

Use the FindFirst and FindNext methods to display the host file in a directory asfollows:


Dim HostDataManager as Object

Dim HostData as Object

Dim s as string

Set HostDataManager = CreateObject("WINAWSVR.BEHOSTDATAMANAGER")

HostDataManager.ChangeDirectory ("C:\dev\bin.w32\data")

HostDataManager.FindFirst "*", s

MsgBox (s)

HostDataManager.FindNext s

MsgBox (s)

End Sub

Awrem32 functionsThe Awrem32 functions provide the parameters and return values for handlingconnections between the host and remote computers.


Awrem32 function

The fully qualified .chf file name thatcontains information about the hostcomputer


awConnect(FileName)

TRUE if command executedReturn value =Boolean

awConnect

55Visual Basic object definitionsAwrem32 functions


Awrem32 function

After calling this function, the callingprogram must delete the object (C++ -delete IAwrem32X*, VB - set ObjectName= Nothing;)


awDisconnect()

Contains the fully qualified path and filename to be copied from the host computer

Parameter =HostFile asstring

FileXferFromHost(HostFile)

Contains the fully qualified destinationpath and file name. The HostFile andRemoteFile strings do not have to beidentical

Parameter =RemoteFile asstring

FileXferFromHost(RemoteFile)


FileXferFromHost

Copies a file from the remote computer tothe host computer. The parameters cancontain wildcard characters

The parameter contains the fully qualifieddestination path and file name

Parameter =HostFile asstring

FileXferToHost(HostFile)

Contains the fully qualified path and filename to be copied from the remotecomputer. The HostFile and RemoteFilestrings do not have to be identical

Parameter =RemoteFile asstring

FileXferToHost(RemoteFile)

Contains the drive and path to create thefolder on the host computer

Parmeter =FolderName asstring

CreateFolderOnHost(FolderName)


CreateFolderOnHost

Executes an existing file on the hostcomputer. This function only executesbatch, command, and executable files. Itdoes not execute files that are associatedwith executables. For example, thisfunction does not open Microsoft Word ifyou execute a .doc file.

The parameter contains the fully qualifiedpath to the file on the host computer

Parameter =FileName asstring

ExecuteHostFile(FileName)

Visual Basic object definitionsAwrem32 functions

56


Awrem32 function


ExecuteHostFile

Returns the last error generated inAwrem32

Return value =String

GetError()

Returns the current status of yourconnection to the host computer

The possible values include the following:

-1 = Lost connection

0 = No connection

1 = Session connected

Return value =Short

ConnectionStatus()

57Visual Basic object definitionsAwrem32 functions

Visual Basic object definitionsAwrem32 functions

58

Visual C++ objectdefinitions


About Visual C++ objects

CRemoteDataManager methods

CRemoteData object

CRemoteDataEx object

CHostDataManager methods

CHostData object

CHostDataEx object

Awrem32 functions

About Visual C++ objectsThe pcAnywhere Automation Server provides the following components to supportOLE Automation:


Winawsvr

Provides the information needed to control pcAnywhereconnections

Awrem32

The objects that are described in Table 3-1 comprise Winawsvr.

3Chapter

Table 3-1 Winawsvr objects

ReferenceDescriptionObject

See CRemoteDataManager methodson page 60.

Provides the methods for creating, opening,modifying, saving, and deletingCRemoteData objects

CRemoteDataManager

See CRemoteData object on page 63.


Defines the parameters for accessing andcontrolling pcAnywhere remotefunctionality

CRemoteData

See CHostDataManager methodson page 71.

Provides the methods for creating, opening,modifying, saving, and deleting CHostDataobjects

CHostDataManager

See CRemoteData object on page 63.


Defines the parameters for accessing andcontrolling pcAnywhere host functionality

CHostData

Awrem32 has one object, which consists of eight interfaces to support remotecontrol and file transfer sessions.

See Awrem32 functions on page 85.

Some functions are no longer supported. However, object definitions are providedfor use with earlier versions.

For functions that require passwords, password values can be set but not retrieved.This is for security purposes.

CRemoteDataManager methodsThe CRemoteDataManager methods provide the parameters and return valuesfor accessing and controlling CRemoteData objects.


Method

The full path name of the currentpcAnywhere data directory in whichpcAnywhere remote objects are stored

Parameter =BSTR

BSTR CurrentDirectory();

Changes the current directory in whichpcAnywhere remote objects are stored.Parameter is the name of an existingdirectory

Return value is TRUE if successful

Parameter =LPCTSTRlpszNewDirectory

Return value =BOOL

BOOLChangeDirectory(LPCTSTRlpszNewDirectory);

Visual C++ object definitionsCRemoteDataManager methods

60


Method

File name pattern to filter object files (anasterisk [*] finds all files in the currentdirectory)

Parameter =LPCTSTRlpszPattern

BOOL FindFirst(LPCTSTRlpszPattern, BSTR FAR*);

Return buffer for the full path name ofthe remote object file that matches thespecified pattern

Parameter =BSTR FAR *pbstrFullQualName

BOOLFindFirst(pbstrFullQualName);

TRUE if a remote object file matchingthe specified pattern is found. The fullpath name of the matching file is storedin pbstrFullQualName

Return value =BOOL

BOOL FindFirst

After FindFirst() has been successfullycalled to get the name of a remote objectfile in the current directory, FindNext()can be called to find the next file thatmatches the pattern, if any

Return value is TRUE if another remoteobject file matching the pattern specifiedin the call to FindFirst() is found. Thefull path name of the matching file isstored in pbstrFullQualName

Parameter =BSTR FAR *pbstrFullQualName

Return value =BOOL

BOOL FindNext(BSTR FAR*pbstrFullQualName);

Retrieves a CRemoteData object by filename

Parameter is the fully qualified remoteobject file name to be loaded

Parameter =LPCTSTRlpszFQName

LPDISPATCHRetrieveObject(LPCTSTRlpszFQName);

Specifies how this object is to be used.This relates to the password protection.The options are as follows:

0 = Not specified

pcaole

Documents

symantec product

party software

licensed software

free software licenses

technical support group

symantec logoare trademarks

support centers

party programs