RemoteWare API Manual

Version 4.1 Service Pack 1A RemoteWare API Manual Version 4.1 Service Pack 1A This document was prepared to assist licensed users of RemoteWare by XcelleNet, Inc.; its contents may not be used for any other purpose without prior written permission. The material contained herein is supplied without representation or warranty of any kind and is based on typical use. Any unusual use may produce unpredictable results. XCELLENET ASSUMES NO RESPONSIBILITY AND SHALL HAVE NO LIABILITY OF ANY KIND ARISING FROM THE SUPPLY OR USE OF THIS DOCUMENT OR THE MATERIAL CONTAINED HEREIN. Companies, names, information, and data used in examples herein are fictitious unless otherwise noted. The information in this document is furnished for informational use only and is subject to change without notice. References in this manual to XcelleNet products, programs, or services do not imply that XcelleNet intends to make these available in all countries in which XcelleNet operates. Restricted Rights: Use, duplication, or disclosure by the U.S. Government is subject to restrictions as set forth in FAR 52.227-19. © 1997- 2003 XcelleNet, Inc. All Rights Reserved. All rights reserved, including the right to reproduce this document or any portion thereof in any form. Printed in the United States of America. RemoteWare is a trademark of XcelleNet, Inc. Other product and company names mentioned herein may be the brand names, trade names, trademarks or registered trade- marks of their respective orders. Contents

USING THIS GUIDE

About this guide ...... vii Working with an electronic guide...... vii Using bookmarks and links...... viii Using the Find feature ...... ix Printing this guide...... x Using RemoteWare online Help ...... xi RemoteWare Support Services...... xii What’s in this guide ...... xiii Related publications...... xiv Additional information sources ...... xvi

CHAPTER 1: INSTALLING API FILES

Supported environments ...... 18 Supported compilers...... 19 Installing the API files from the CD-ROM ...... 20 Copying API files ...... 20 Testing your API programs...... 21 Using the APIs with Visual Basic...... 21

CHAPTER 2: USING THE API FUNCTIONS

Error handling...... 24 Types of errors ...... 24 Interpreting data types...... 26

CHAPTER 3: SERVER API FUNCTIONS

General notes ...... 28 New functions ...... 28 Building Server applications...... 29 Error codes...... 30 Server Alarm API functions...... 31 Server worklist API functions ...... 35 Server Notify API functions...... 51 iv RemoteWare API Manual

Server database API functions...... 56 Server Object API functions...... 76 Server Schedule API function ...... 101 Server Information API function...... 104 Server Reset Security API function...... 107

CHAPTER 4: 16-BIT WINDOWS AND 32-BIT OS/2 CLIENT APIS

General notes ...... 110 Compiling and linking applications for Windows ...... 110 Compiling and linking applications for OS/2 ...... 111 Error codes...... 112 Client Configuration and Status API functions ...... 112 Transaction Pipe API functions ...... 132 Transaction Pipe Notification Types ...... 133 Transaction Pipe Error Codes...... 133 Client Worklist API functions...... 141 Client Dialing Directory API functions ...... 153 Client Object API functions ...... 154

CHAPTER 5: DOS CLIENT APIS

General notes ...... 164 Compiling and linking applications ...... 164 Error codes...... 165 DOS Client Configuration and Status API functions...... 165

CHAPTER 6: WORKLIST EVENTS

Using worklists ...... 176 Client vs. Server worklist APIs...... 176 Communicating between worklists and programs ...... 176 Worklist default files and paths...... 179 File transfer events...... 180 Operating system events ...... 189 Session control events ...... 212 Server events ...... 229

CHAPTER 7: WIN32 COM OBJECT CLIENT APIS Contents v

Overview of Win32 COM OBJECT Client APIs...... 237 Interface Definition Language (IDL)...... 237 Error handling...... 238 Win32 Client API structure...... 240 RWClient Object ...... 240 EnumRWClientInfo Object...... 240 XWorkList Object ...... 240 RWClientInfo Object ...... 240 RWClientDialingEntry Object...... 241 IRWClientDialingEntryCollection Object ...... 241 RWClientWOSelection Object ...... 241 IRWClient API Methods ...... 242 IRWClientInfo API Methods ...... 264 IRWClientDialingEntry API ...... 267 IRWClientSessionStatus API Methods...... 284 IRWClientTextExplanation API Methods ...... 305 IRWClientDialingDirectory API Methods...... 315 IRWClientSessionResultLog API Methods...... 322 IRWClientStatus API methods...... 338 IRWClientWOSelection API methods...... 364 IRWClientDialingEntryCollection API Methods ...... 374 IRWClientInfoCollection API Methods ...... 377 Transaction Pipe API functions ...... 386 Transaction Pipe Notification Types ...... 387 Transaction Pipe function Error Codes ...... 387 IXWorkList API methods ...... 394 IRWClientStatusEvents API methods ...... 413 Enumerations and Structures...... 418 Client ActiveX Controls ...... 422

APPENDIX A DIAL SCRIPTS

Using DLLCALL...... 432

INDEX vi RemoteWare API Manual Chapter X: Chapter Title <-- Apply “chapter hidden” style

Using This Guide

This guide introduces you to RemoteWare, a remote systems management tool specifically designed to distribute software to and perform inventory scans for remote and fixed-site users. It contains fundamental information necessary to use the software, including a conceptual overview and highly interactive walkthroughs. We recommend that you print this guide so that it is readily available as you perform your tasks. However, if you prefer to use this guide online, you may find it helpful to zoom to 150% for enhanced readability. For information on printing the guide, see “Printing this guide” on page x.

About this guide This book is intended for the administrator who maintains the RemoteWare Server. Before working with RemoteWare, we strongly recommend that you possess a working knowledge of the Windows NT® or Windows 2000® operating system. You should also be familiar with the operating environments which run the RemoteWare Clients. In addition, the RemoteWare system administrator should be familiar with Windows NT® or Windows 2000® Server concepts such as services, networks, user and group account administration, domains, and system security.

Working with an electronic guide If you’re reading this guide right now, you’re looking at it in Adobe Acrobat Reader. You might be tempted to print the document immediately, but wait—Acrobat Reader actually has several features we’ve incorporated into this document to make it easier to use electronically, including: • Bookmarks for accessing task-driven topics, such as creating Client installation kits • A hyperlinked Table of Contents and Index viii RemoteWare AntiVirus Manager Administrator’s Guide

• Links on the first page of each chapter that take you directly to the topic covered • Hyperlinked cross references Acrobat also has several features that make it easy for you to access the information you need. See your Adobe Acrobat Reader online Help for more information.

Using bookmarks and links We’ve included bookmarks and links in the guide to search for topics. When you open the guide in Acrobat Reader, the Bookmarks and Page view automatically appears.

Bookmarks You can access topics in the guide several different ways. You can click on any of the bookmark icons in the left pane to go directly to a topic. To see more topics, click the icon next to a bookmark. This will list all of the other topics covered in that section. To close the list, click the icon next to the bookmark.

Links

Table of Contents and Index Both the Table of Contents and the Index are hyperlinked, so you can click on a link and go straight to the information you need to access. In the Table of Contents, both the headings and the page numbers are linked. In the Index, only the page numbers are linked. To select a topic from the Table of Contents or the Index:

1 Select the Hand tool from the toolbar. The pointer symbol will change to a hand symbol.

2 Place the hand symbol over the heading or the page number containing the information you want to view and click. Acrobat Reader will take you to the page you selected. Using This Guide ix

Chapter introductions On the first page of each chapter, you’ll see blue hyperlinks that lead you to various topics within that chapter. Use the hand tool to click on the link, and Acrobat Reader will take you to that topic.

Cross-references You’ll see blue hyperlinked cross-references throughout each chapter. Just use the hand tool to click on the link, and Acrobat Reader will take you to the next page.

Using the Find feature You can use Acrobat’s Find option to do a full-text search of any document you have open. To do a full-text search of the RemoteWare guide:

1 Click the Find toolbar button. The Find dialog box will appear.

2 In the Find What area, enter the term(s) you want to find. To close the Find dialog box, click Cancel at any time. 3 Select any of these check box options that apply: • Match Whole Word Only. Select this option if you want Acrobat Reader to search for that exact term only. • Match Case. Select this option to do a case-sensitive search for words. • Find Backwards. Select this option if you want Acrobat Reader to move backwards instead of forwards when searching for a word. 4 Click Find to begin your search. Once Acrobat Reader finds the term, it will close the Find dialog box. 5 To continue searching for other instances of a term, select Find Again from the View menu. The Find dialog Box will reappear, with the original term still in the Find What area. 6 Click Find Again. Repeat this process until you’ve found the section you want to view. x RemoteWare AntiVirus Manager Administrator’s Guide

Printing this guide From Acrobat Reader you can print the entire guide or print a range of pages. To print the guide: 1 On the File menu, select Print. 2 Make sure you have the correct printer and number of copies selected, then click OK. Using This Guide xi

Using RemoteWare online Help RemoteWare contains online Help that provides explanations of features and steps for completing tasks. For more general information, see your Windows NT, 95/98, or 2000 online Help. To access RemoteWare online Help: On the Help menu, select RemoteWare Help. The main Help window will appear.

Features in the RemoteWare online Help include: Table of Contents. Provides the Help file contents for the application you currently have open. Includes an introduction and task-driven topic headings. Index. Provides a quick link within to any topic within the application associated with the key word you select. Search. Allows you to search all the Help file contents by entering a word or phrase. Glossary. Provides short, concise definitions for key terms in the RemoteWare application. Internal links. Provide direct jumps to related other topics. Pop-up Help. Provides pop-up definitions of terms without requiring you to move to another topic or access the glossary. xii RemoteWare AntiVirus Manager Administrator’s Guide

RemoteWare Support Services XcelleNet offers a variety of support options to help you get the most out of RemoteWare. If you have a question about the product, first look in the documentation or consult the online Help. If you can’t find the answer, contact Customer Support. Customers who are on a maintenance plan with XcelleNet may contact Technical Support Monday through Friday from 8:30 A.M. to 8:30 P.M. EST for assistance. Call the Technical Support staff at 1-800-669-1211 toll free, 678-585-7320 in the Atlanta, Georgia area or +44 208 538 5888 for Europe, Middle East or Africa. You can find detailed information on obtaining Technical Support on XcelleNet’s www.XcelleNet.com web site. Using This Guide xiii

What’s in this guide This guide contains the chapters summarized in the table below. See the Contents for a full listing.

Table 1. Chapters in this guide

Chapter Title Description

Chapter 1 Installing API Files Lists compiler requirements and provides instructions for installing the RemoteWare API files. Chapter 2 Using the API Functions Discusses issues and requirements for successfully using RemoteWare API functions. Chapter 3 Server API Functions Covers the Server API functions that run on the RemoteWare Server, including how to use the functions and interpret their return codes. Chapter 4 16-bit Windows and 32-bit OS/2 Describes the APIs for use with the Client APIs RemoteWare 16-bit Clients running under Windows 3.x, NT, or 95. Also explains the use of the OS/2 version of the APIs to build applications for OS/2 Nodes. Chapter 5 DOS Client APIs Describes the DOS Client API calls for the DOS programming environment and explains how to use the functions and interpret their return codes. Chapter 6 Worklist Events Describes the events that you can use to build a worklist. Chapter 7 Win32 COM Object Client APIs Describes the collection of Component Object Model (COM) objects that enable you to write programs that interact with XcelleNet’s RemoteWare Client software. Appendix A Dial Scripts Describes the methods for using dial scripts to execute customized code. xiv RemoteWare AntiVirus Manager Administrator’s Guide

Related publications

In addition to this manual, the following related manuals are available in printed format from your RemoteWare representative. They are also available in electronic format on the RemoteWare CD-ROM as described in the following section. • RemoteWare Server Administrator’s Guide. Explains how to operate and maintain a RemoteWare system. It takes a task-oriented approach to describing features. • RemoteWare Server Reference Guide. Contains a detailed description of every application, facility, window, menu, and control present in the RemoteWare Server. Use this book when you want to know what something does, how it is used, or why it behaves as it does.

Electronic documentation The following documents are available on the RemoteWare CD. Unless otherwise specified, all documents reside in the \Documents directory. All electronic documents require the Adobe Acrobat reader to view and print PDF files. Install the reader from the RemoteWare CD using the\Acroread\ar32e01.exe file.

Administrator guides • RemoteWare Workshop Developer’s Guide. Explains how to use RemoteWare Workshop to create and publish customized desktop-style Workshop applications. • RemoteWare Subscriber Administrator’s Guide. Shows how to build and deploy lists of files and applications to the Client. It also explains how to use the Subscriber Lists at the RemoteWare Client. • RemoteWare Inventory Manager Administrator’s Guide. Explains how to use Inventory Manager for centralized monitoring and reporting of hardware and software resources on RemoteWare Clients. Instructions include how to create Inventory Manager Profiles that control the operating and scheduling of Client inventory scans, and how to assign those Profiles to Clients. The guide also describes how to view and interpret the centrally stored resource information for each Client. • RemoteWare Software Manager Administrator’s Guide. Explains how to use Software Manager to efficiently and securely distribute, install, and manage software for enterprise system users. Includes how to create and define software package contents and then assign that package to a RemoteWare Client. • RemoteWare Migration Guide. Explains how to plan and implement many aspects of migration from RemoteWare for OS/2 to RemoteWare. • RemoteWare Multicast System Administrator’s Guide. Explains how to use RemoteWare Multicast. Multicast allows administrators to distribute files to a large Using This Guide xv

number of RemoteWare Clients with a single communication session from the Server. It contains fundamental information necessary to use the software, including a conceptual overview and highly interactive walkthroughs. • RemoteWare ActiveX Controls Reference Manual. Presents the 32-bit ActiveX controls that are included with the RemoteWare 32-bit Client software. These controls add selected Client functionality to ActiveX or OLE container applications. • RemoteWare Workshop Programmer’s Guide. Describes optional programmatic extensions that enhance Workshop environments. • Summit BasicScript Reference Manual and Summit BasicScript User’s Guide provide information on the options and structure for RemoteWare scripting. These documents are available in the \Document\Development Tool Administrator Guides\Summit BasicScript Documentation directory on the RemoteWare CD. • User’s Guide/VirusScan for Windows 3.1®, 95, and NT. Helps the Windows Client user understand the functionality in McAfee VirusScan for Windows 3.1, Windows 95, and Windows NT Workstation 4.0. • pcAnywhere™. Assists you in using pcAnywhere with RemoteWare Remote Control.

Client guides • RemoteWare 32-Bit Windows Client User’s Guide. Helps the 32-bit Windows Client user install, set up, and understand the functionality in the RemoteWare Client. • RemoteWare Windows 3.x Client User’s Guide. Helps the 16-bit Client user install, learn, and take advantage of all the features available in the RemoteWare Windows 3.x Client software. • RemoteWare OS/2 Client User’s Guide. Presents the features, setup procedures, available options, and connection methods for the OS/2 Client software. • RemoteWare Text-Based Clients User’s Guide. Explains how to use the UNIX, VMS, 4690 and DOS Clients to communicate with the RemoteWare Server. • RemoteWare Software Manager Client User’s Guide. Describes how Client users can subscribe to Software Manager packages and then communicate with a RemoteWare Server to receive those packages. xvi RemoteWare AntiVirus Manager Administrator’s Guide

Additional information sources There are several sources of information related to RemoteWare. They include the following: • Online help. The RemoteWare online help provides easy access to information about each application’s main functions. • PDF documentation. The RemoteWare administrator and user guides are available as electronic documents on the RemoteWare CD-ROM. • RemoteWare information on the web. For current RemoteWare information, visit XcelleNet’s www.XcelleNet.com web site. CHAPTER 1

1 Installing API Files

This chapter lists the compiler requirements and provides instructions to install the RemoteWare API files.

This chapter includes:

• Supported operating system environments

• Supported compilers

• Installing the API files from the RemoteWare CD-ROM

• Installing the Win32 COM Object Client APIs

• Test bed information

• Using the APIs with Visual Basic 18 RemoteWare API Manual

Supported environments The RemoteWare APIs operate on any IBM PC compatible computer running the following:

Table 2. Supported operating environments

API Type Supported Operating System

Server API Windows NT (version 4.0 with Service Pack 3 or later) 16-bit Windows Client API Windows 3.1x (under MS-DOS 3.1 or later); Windows 95, Windows 98, or Windows NT (version 4.0 with Service Pack 3 or later) 32-bit OS/2 Client API OS/2 4.0 DOS Client API MS-DOS 5.0 or later 32-bit Windows Client API Windows 95, Windows 98, or Windows NT (version 4.0 with Service Pack 3 or later) Win32 COM Object Client APIs Windows 95 Windows 98, or Windows NT (version 4.0 with Service Pack 3 or later) 32-bit Windows Client ActiveX Windows 95, Windows 98, or Windows NT (version 4.0 with Control Service Pack 3 or later)

The compiler you use may have stricter system requirements than these. See your compiler documentation for details. CHAPTER 1 / Installing API Files 19

Supported compilers The RemoteWare API supports the programming languages shown in the following table.

Table 3. Supported compilers

API Type Supported Compilers

Server API Microsoft Visual C++ 5.0 16-bit Windows Client API Microsoft Visual C++ 1.52 Microsoft Visual Basic Professional 4.0 (16-bit) 32-bit OS/2 Client API IBM Visual Age 3.0 DOS Client API Microsoft Visual C++ 1.52 32-bit Windows Client API Microsoft Visual C++ 5.0 Microsoft Visual Basic Professional 4.0 (32-bit) Win32 COM Object Client APIs Microsoft Visual C++ 4.2 Microsoft Visual Basic Professional 5.0 (32-bit) 32-bit Windows Client ActiveX Microsoft Visual C++ 4.2 Control Microsoft Visual Basic Professional 5.0 (32-bit)

You may be able to use other compilers and programming languages with the APIs, although XcelleNet has only tested the languages above. In addition, all examples in this manual demonstrate API functions with Microsoft C++. 20 RemoteWare API Manual

Installing the API files from the CD-ROM All RemoteWare APIs except the Win32 COM Object Client APIs are installed when you install the RemoteWare Developer’s Kit from the Server installation program on the RemoteWare CD. Follow the instructions in the RemoteWare Server Installation Guide to start the installation, then choose Developer’s Kit from the Setup Menu. Follow the onscreen instructions.

Copying API files If you want to work with specific APIs only, you can copy the appropriate files from the machine on which the RemoteWare Developer’s Kit was installed. The table below shows the default directories in which the files are installed. If you changed the installation path during the RemoteWare Developer’s Kit installation, substitute the new path for \rdk.

Table 4. Directories for API families

API Type Directory for C++ version

32-bit Windows Client ActiveX Control \rdk\ActiveX\ DOS Client API \rdk\Client\Dos\Include\ \rdk\Client\Dos\Lib\ OS/2 Client API \rdk\Client\Os2\Include\ \rdk\Client\Os2\Lib\ 16-bit Windows Client API \rdk\Client\win16\Msvc152\Include\ \rdk\Client\win16\Msvc152\Lib\ 32-bit Windows Client API \rdk\Client\Win32\Msvc60\Include\ \rdk\Client\Win32\Msvc60\Lib\ Server API \rdk\Server\Include\ \rdk\Server\Lib\

To copy specific API files:

1 Create or designate a directory where you intend to develop your API programs. If you plan to develop multiple APIs on this computer (for example, both the Server and 32-bit Client APIs), create a separate directory on your hard drive for each API.

2 Copy the contents of the directories listed in Table 4 to the directories you created in step 1. CHAPTER 1 / Installing API Files 21

Testing your API programs The computer where you test your API programs must have certain files installed. If you are testing programs that use RemoteWare Server APIs, you must install the DLLs where the operating system can find them. You must also run any programs that use the RemoteWare Server APIs from the Server’s data drive. If you are testing programs that use the DOS Client APIs or 16- or 32-bit Windows Client APIs, you must have the corresponding RemoteWare Client software installed. All necessary DLLs and related files are installed when you install the Client software. You must also run your programs that use Client APIs from the Client’s data drive.

Using the APIs with Visual Basic All of the Client API functions described in this manual work with Visual Basic except the 16-bit Client’s RWNObjectQueryInfo and RWNObjectQueryObjects functions. Note: You can ignore any references to #define statements in this manual when using Visual Basic. 22 RemoteWare API Manual CHAPTER 2

2 Using the API Functions

This chapter discusses issues and requirements for successfully using RemoteWare API functions. This chapter applies only to the APIs referenced in Chapters 3, 4, 5, 6, and 7.

This chapter includes:

• Error handling

• Interpreting data types 24 RemoteWare API Manual

Error handling Many RemoteWare API functions return an error code to indicate whether the function completed successfully. Your program should always check the return codes of any function that returns something other than void. Otherwise, your program may not function as expected. For example, suppose you create a program that starts a session on a particular RemoteWare Client using the RWSScheduleSession() API function. The session’s worklist contains a NOTIFY command that signals your program when the session reaches a particular point. To wait for that signal, your program uses the API function RWSNotifyWait(). If a session could not be scheduled for some reason, the NOTIFY signal would never be issued. Therefore, if your program does not check the RWSScheduleSession() return code, your program would wait for a NOTIFY signal that never arrives and would seem to hang.

Types of errors Generally, errors fall into two groups: recoverable errors and non-recoverable errors. It is your responsibility to decide which is which, although some errors (such as invalid parameters) indicate bugs in your program that are difficult to recover from while the program is running. For example, the RWSScheduleSession() function in the next example can return one of the error codes listed in the following table. Table 5. Error types

Error code Description

0 (zero) The function was successful E_RWS_PARAM Invalid calling parameter E_RWS_NOCLIENTS No Clients are assigned to the group specified, or no Clients are assigned to the session if RWS_ALL_ASSIGNED was specified. E_RWS_DISABLED The specified session or the specified individual Client is disabled. E_RWS_SCHED The session was not successfully submitted to the scheduler. other A Windows NT error occurred. This value indicates the WIN32 error code. A simple error handler could print an error message and terminate if the return code is something other than zero. An elaborate handler might automatically attempt to correct any error condition. The following code provides an in-between approach to handling return codes. In the example, the function MyAlert() displays a message explaining the problem and asking the user whether to retry the function or abort the program. CHAPTER 2 / Using the API Functions 25

short error; USHORT status; char from_client[NAMELGT]; /* ... */ /* start the session */ status = RWSScheduleSession( “DailyUpdate", "ATLANTA", RWS_NOW ); switch( status ) { case 0: /* no problem */ done = TRUE; break;

case E_RWS_PARAM: /* invalid parameter */ printf( “internal error... exiting\n” ); terminate(); break;

// E_RWS_NOCLIENTS will not come up since we are only // working with a single client instead of a group or // all assigned clients.

case E_RWS_DISABLED: /* session or client disabled */ done = MyAlert( “Session or client disabled.” ); break;

case E_RWS_SCHED: /* session not scheduled */ done = MyAlert( “Session not scheduled.” ); break;

default: /* WIN32 error */ printf( “WIN32 error: %d\n”, status ); terminate(); break;

RWSNotifyWait( MyQueue, from_client, &error ); 26 RemoteWare API Manual

Interpreting data types The following table lists the data types used for the functions and parameters described in Chapters 3, 4, 5, and 6. Table 6. Data types Data Type Description

BOOL Unsigned integer (32-bit in WIN32, 16-bit in all other operating systems).

BYTE 8-bit unsigned character. char, CHAR 8-bit signed character.

FAR (Windows 3.1x and DOS only.) Defines a data pointer or function consisting of a 16-bit segment address and a 16-bit offset address.

INT Signed integer (32-bit in WIN32, 16-bit in all other operating systems).

LONG 32-bit signed integer.

PASCAL (Windows 3.1x and DOS only.) Defines a function using the Pascal naming conventions (the function name becomes all uppercase with no prepended underscore) and parameter-passing conventions.

PRWHANDLE Pointer to a variable of type RWHANDLE. RWHANDLE is a WIN32 HANDLE type.

PSZ Pointer to a C string, which is a NULL-terminated (zero-terminated) data string.

PUSHORT Pointer to USHORT. short, SHORT 16-bit signed integer.

ULONG 32-bit unsigned integer.

unsigned Unsigned integer (32-bit in WIN32; 16-bit in all other operating systems).

unsigned short 16-bit unsigned integer.

USHORT 16-bit unsigned integer.

void Indicates a C function with no return value; also used in function prototypes.

WORD 16-bit unsigned integer. CHAPTER 3

3 Server API Functions

This chapter covers the Server API functions that run on the RemoteWare Server, including how to use the functions and interpret their return codes. It also presents the functions, their parameters, relevant comments, and examples.

This chapter includes:

• General notes on using Server API functions

• New Server API functions

• Building Server applications

• Server API error codes

• Server Alarm API functions

• Server Worklist API functions

• Server Notify API functions

• Server Database API functions

• Server Object API functions

• Server Schedule API functions 28 RemoteWare API Manual

General notes To use the RemoteWare Server API functions, your program should contain an #include followed by an #include . To use Worklist or Object (work object) API functions, link with RWSRUNTM.LIB, and run with RWSRUNTM.DLL in your path. To use all other functions, link with RWSAPI.LIB, and run with RWSAPI.DLL in your path. When including RWSAPI.H, be sure to #define INCL_RWS_WORKLIST if your program uses the worklist APIs. The portion of the header file containing the worklist constants, structures, and prototypes is conditionally included. As always, programs using the RemoteWare for Windows NT Server APIs must run on the Server’s data drive.

New functions The Worklist API functions have been restructured compared to previous RemoteWare versions earlier than version 3.31. • RWSResetSecurity() resets the fourth level of Client security on a RemoteWare Server. • RWSWorklistAction() no longer exists. It is replaced by the separate RWS functions described below. • RWSGetNumberofRecords() determines the number of records in a worklist file. • RWSReadWorklistRecord() reads a specified number of records from an open worklist file. • RWSWriteWorklistRecord() writes a specified number of records to an open worklist file. • RWSDeleteWorklistRecord() deletes a worklist record at a specified offset from the first record in an open worklist file. • RWSAppendWorklistRecord() appends a worklist record at the end of an open worklist file. • RWSWorklistSave() saves an open worklist file. • RWSWorklistClose() more easily closes a worklist file handle using a single parameter. • RWSWorklistOpen() remains unchanged. CHAPTER 3 / Server API Functions 29

Building Server applications To build an application using the RemoteWare APIs, simply include the RWSRUNTM.LIB and RWSAPI.LIB files in your project. If the application you build do not behave the same, check the following: • Verify you are using the correct version of your compiler. For example, confirm you are not building 32-bit code with a 16 bit compiler. • Confirm you have the correct set of include files and libraries for your environment. You may have to generate an import library. See your compiler manual for more information on how to create import libraries from a DLL without object files or source. 30 RemoteWare API Manual

Error codes The RemoteWare Server APIs generally return two types of error codes. A positive error code is likely a WIN32 error that you can look up in most Windows NT technical references. A negative error is probably specific to RemoteWare. The following table shows a list of all the error codes defined for the RemoteWare Server. The description of each function also lists the error codes that may be returned by that function.

Table 7. Server API error codes

Name Description

E_RWS_EOF End of file reached. E_RWS_PARAM Invalid parameter supplied. E_RWS_NOCLIENTS No Clients are assigned. E_RWS_DISABLED The specified session or Client was disabled. E_RWS_SCHED Submit session failed. E_RWS_EXISTS Specified name already exists. E_RWS_NOT_EXISTS Specified name does not exist. E_RWS_MAX Maximum number of objects already created. E_RWS_INCOMPLETE Object was created but not all information was successfully associated with the object. E_RWS_INVALID_KEY Invalid key specified. E_RWS_INVALID_OWNER The owner of the group does not match the owner of the object. E_RWS_MSG_LOGGED API logs a message to the Server Log if an error occurred while modifying the assignments. E_RWS_LOW_MEMORY Insufficient memory available to perform the requested operation. E_RWS_NOAPPREGFILE Application registration file could not be found E_RWS_IN_USE Item is being edited elsewhere. E_RWS_NO_RENDEL Object cannot be renamed or deleted because of its assignment to a group E_RWS_UNDEFINED Unknown error occurred. E_RWS_FAILED General failure occurred E_RWS_CONFLICT Conflicting assignment exists. E_RWS_AUTOASN_FAILED Autoassign attempt caused a conflicting assignment, so the autoassign was not completed. CHAPTER 3 / Server API Functions 31

Server Alarm API functions Alarm API functions let you check the status of RemoteWare for Windows NT Server alarms, set alarms under program control, or clear (delete) alarms. The RWSAPI.DLL file contains these functions. You must execute programs using these functions on the Server’s data drive. Uses for these functions include: • Monitoring certain alarms and taking appropriate action • Setting alarms, for example, to indicate an error detected by your program • Passing RemoteWare alarms to a network management system Valid Alarm API functions and alarm types for the RemoteWare Server include:

Table 8. Server Alarm API functions

Function Name Description

RWSIsAlarmSet Check the status of the specified alarm. RWSGetAlarmText Get the alarm message text for the last occurrence of the alarm. RWSSetUserAlarm Set the User alarm and log message text associated with the alarm. RWSClearAlarm Clears an alarm that is currently set.

Table 9. Alarm API types

Alarm Type Description

ALARM_SERVER_REBOOT The Server was rebooted. ALARM_SCHEDULER_LOADING The Loader is still running. ALARM_SCHEDULER_OFF The Scheduler is disabled. ALARM_SCHEDULER_OVERRUN A session is out of range. ALARM_SERVER_DISK_FULL The Server disk is full. ALARM_CLIENT_DISK_FULL A Client disk is full. ALARM_LOW_MEMORY The Server is low on memory. ALARM_FATAL_ERROR A System Fatal Error was detected. ALARM_PORT_FAILURE The COM port has excessive errors. ALARM_XSUPPORT Support Response was received. ALARM_SERVER_DOWN A Clustered Server is down. ALARM_SCHEDULER_FULL All Scheduler queues are full. ALARM_USER_DEFINED User-defined alarm or User Alarm. ALARM_MODEM_ERROR The Server modem has generated an error. 32 RemoteWare API Manual

Alarm Type Description

ALARM_SERVER_SUSPENDED The Server is in a suspended state. ALARM_SECURITY_FAILURE A Sentinel security failure was detected. ALARM_MANUAL_CLIENTREG Manual verification of a Client’s registration information is required. ALARM_MTA_FAILURE Mail Transfer Agent failure occurred. Internally, alarm types are integers from 0 (zero) to TOTAL_ALARMS-1, where TOTAL_ALARMS is a symbolic constant defined in RWSAPI.H.

Server Alarm API RWSIsAlarmSet Description This function returns the status of the specified alarm (i.e., whether the alarm is set or cleared). Applicable Alarm All. For information on Alarm Types, see “Server Alarm API Types functions” on page 31.

C Synopsis BOOL RWSIsAlarmSet( SHORT iAlarm ); Parameters iAlarm This parameter specifies the alarm type that you want to test. For a list of valid Alarm Types, see “Server Alarm API functions” on page 31. Return values This function returns one of the following values: True The alarm is set. False The alarm is cleared.

Example if( RWSIsAlarmSet(ALARM_SERVER_DISK_FULL) ) { printf( “Server disk is full.\n” ); exit(); } CHAPTER 3 / Server API Functions 33

Server Alarm API RWSGetAlarmText Description This function returns the alarm message text for the last occurrence of the specified alarm. RWSGetAlarmText() is valid only for the following alarm types: Applicable Alarm ALARM_CLIENT_DISK_FULL Types ALARM_PORT_FAILURE ALARM_MODEM_ERROR ALARM_USER_DEFINED ALARM_FATAL_ERROR ALARM_SERVER_DOWN ALARM_MTA_FAILURE ALARM_MANUAL_CLIENTREG

For information on Alarm Types, see “Server Alarm API functions” on page 31.

C Synopsis BOOL RWSGetAlarmText( SHORT iAlarm, PSZ pszText ); Parameters iAlarm This parameter specifies the alarm type for which you are requesting message text. Only the alarm types listed at the beginning of this RWSGetAlarmText() description provide message text. The other alarm types are invalid for this function. pszText On entry, you pass a text pointer to a buffer of ALARM_TEXT_SIZE+1 bytes (ALARM_TEXT_SIZE is a symbolic constant defined in RWSAPI.H). If the function returns successfully, this buffer contains the null-terminated error text. Return values This function returns one of the following values: True The function completed successfully. False The supplied Alarm type (iAlarm) was invalid.

Example char AlarmText[ALARM_TEXT_SIZE+1];

if ( RWSIsAlarmSet(ALARM_USER_DEFINED) ) { RWSGetAlarmText( ALARM_USER_DEFINED, AlarmText ); printf( “User alarm: %s\n”, AlarmText ); } 34 RemoteWare API Manual

Server Alarm API RWSSetUserAlarm Description This function sets the User alarm and logs associated message text to the Server’s Message Log. Applicable Alarm ALARM_USER_DEFINED Types For information on Alarm Types, see “Server Alarm API functions” on page 31.

C Synopsis VOID RWSSetUserAlarm( PSZ pszText ); Parameters pszText A pointer to a null-terminated string containing the error text you want to assign to the user alarm. This text appears in the Server’s Message Log.

The string can be up to ALARM_TEXT_SIZE bytes, plus a null terminator (ALARM_TEXT_SIZE is a symbolic constant defined in RWSAPI.H). If you exceed this length, the Server will truncate the string to this size. Return values None

Example RWSSetUserAlarm( “This text explains the alarm” );

Server Alarm API RWSClearAlarm

Description This function clears the specified alarm, if it is set. Use this function to clear RemoteWare for Windows NT Server alarms after you have corrected the condition that caused the alarm. Applicable Alarm ALARM_SERVER_REBOOT Types ALARM_SCHEDULER_OVERRUN ALARM_CLIENT_DISK_FULL ALARM_FATAL_ERROR ALARM_PORT_FAILURE ALARM_USER_DEFINED ALARM_MODEM_ERROR ALARM_MTA_FAILURE ALARM_MANUAL_CLIENTREG

For information on Alarm Types, see “Server Alarm API functions” on page 31. CHAPTER 3 / Server API Functions 35

Server Alarm API RWSClearAlarm (Continued)

C Synopsis BOOL RWSClearAlarm( SHORT iAlarm ); Parameters iAlarm This parameter specifies the alarm type that you want to clear. Only the alarm types listed at the beginning of this RWSGetAlarmText() description provide message text; the other alarm types are invalid for this function. Return values This function returns one of the following values: True The alarm was cleared successfully. False Either the alarm was not set or you supplied an invalid alarm type.

Example RWSClearAlarm( ALARM_USER_DEFINED );

Server worklist API functions Worklist API functions may be used to create and manipulate a list of events just as an operator would in the Work Object Editor on the RemoteWare Server. The RWSRUNTM.DLL file contains the Worklist API functions. Any programs that use these functions must be executed on the Server’s data drive. Your programs can use these APIs to perform tasks or modify existing units of work on the Server. For a more detailed description of worklists and related issues, see “Worklist Events” on page 175. The following table lists the RemoteWare Server Worklist API functions. Uses for these functions include: • Retrieving a Client’s directory listing • Building a list of Client files to be collected by the Server • Commanding a Client to run an executable program • Synchronizing a Client and the Server’s system clock 36 RemoteWare API Manual

Function Name Description

RWSWorklistOpen Opens a worklist file for further actions using other Worklist API functions. RWSWorklistClose Closes a worklist file handle. RWSWorklistSave Saves an open worklist file. RWSGetNumberOfRecords Determines the number of records in a specified open worklist file handle. RWSReadWorklistRecord Reads a specified number of records from an open worklist file. RWSWriteWorklistRecord Writes a specified number of records to an open worklist file. RWSDeleteWorklistRecord Deletes a worklist record at a specified offset from the first record in an open worklist file. RWSAppendWorklistRecord Appends a worklist record at the end of an open worklist file.

Server Worklist API RWSWorklistOpen Description RWSWorklistOpen() opens a worklist file and loads it into a buffer for further operations by other Worklist API functions. All operations (Read/Write/Delete) are performed on this buffer.

The buffer is saved to disk using RWSWorklistSave(), which writes the buffer to disk but keeps the worklist handle open. RWSWorklistClose() closes the worklist handle.

C Synopsis INT RWSWorklistOpen( PRWHANDLE phWorklist, LPCSTR pszWorklistFile ); Parameters phWorklist This is a pointer to a variable of type RWHANDLE, which receives the file handle upon successful opening of the worklist file. pszWorklistFile This is a pointer to a null-terminated string that specifies the worklist file’s name. Worklist filenames typically take the form \\WORKLIST\\.EVF. Return values This function returns 0 (zero) if successful, or an WIN32 error code if an error occurs. CHAPTER 3 / Server API Functions 37

Server Worklist API RWSWorklistOpen (Continued)

Example RWHANDLE fhWorklistHandle; INT rc;

rc = RWSWorklistOpen( &fhWorklistHandle, “test.evf”);

if ( rc ) { printf( “RWSWorklistOpen: error %d\n”, rc ); } else { puts(“RWSWorklistOpen:OK”); }

Server Worklist API RWSWorklistClose Description This function closes a worklist file handle that was opened using RWSWorklistOpen(), but does not save the file.

C Synopsis INT RWSWorklistClose( RWHANDLEhWorklist ); Parameters hWorklist This variable initially received the file handle from the call to RWSWorklistOpen() and identifies the Worklist file to be closed. Return values This function returns 0 (zero) if successful, or an WIN32 error code if an error occurs.

Example RWHANDLE fhWorklistHandle; INT rc;

rc = RWSWorklistClose( fhWorklistHandle ); if ( rc ) { printf( “RWSWorklistClose: error %d\n”, rc ); } else { puts( “RWSWorklistClose: OK” ); } 38 RemoteWare API Manual

Server Worklist API RWSWorklistSave Description This function saves a worklist file that was opened using RWSWorklistOpen(), but does not close the file handle.

C Synopsis NT RWSWorklistSave( RWHANDLE hWorklist ); Parameters hWorklist This variable initially received the file handle from the call to RWSWorklistOpen() and identifies the Worklist file to be saved. Return values This function returns 0 (zero) if successful, or an WIN32 error code if an error occurs.

Example RWHANDLE fhWorklistHandle; INT rc;

rc = RWSWorklistSave( fhWorklistHandle );

if ( rc ) { printf( “RWSWorklistSave: error %d\n”, rc ); } else { puts( “RWSWorklistSave: OK” ); }

Server Worklist API RWSGetNumberOfRecords Description This function returns the number of records contained in a specified worklist handle, which was opened using RWSWorklistOpen().

C Synopsis INT RWSGetNumberOfRecords( RWHANDLE hWorklist ); Parameters hWorklist This variable contains the file handle that was provided by RWSWorklistOpen() and specifies the particular Worklist file for which the record count is needed. Return values This function returns the number of records contained in the specified open worklist file handle. CHAPTER 3 / Server API Functions 39

Server Worklist API RWSGetNumberOfRecords (Continued)

Example RWHANDLE fhWorklistHandle; UINT uiCount;

uiCount = RWSGetNumberOfRecords ( fhWorklistHandle );

printf( “RWSGetNumberOfRecords returned %d\n”, uiCount );

Server Worklist API RWSReadWorklistRecord Description This function reads a specified number of records from a worklist file handle that was opened by RWSWorklistOpen(). The record number from which to start reading is specified in the iRecordNumber member of the RWWORKLIST structure that is passed to RWSReadWorklistRecord().

C Synopsis INT RWSReadWorklistRecord( RWHANDLE hWorklist, PRWWORKLIST pWorklistRec, PUINT puiReadCount ); Parameters hWorklist This variable contains the file handle provided by RWSWorklistOpen() and specifies the particular Worklist file that should be read. pWorklistRec This is a pointer to a variable or array of variables of type RWWORKLIST (described later in this section) that will receive the record(s) to be read. The record number from which to start reading must be specified in the iRecordNumber member of this structure (only in the first element of an RWWORKLIST array). If an array is used, the number of array elements should equal the value of puiReadCount (see the next parameter). puiReadCount This is a pointer to an unsigned integer. On entry, the integer should be the number of records you wish to read. On return, the integer contains the number of records actually read. 40 RemoteWare API Manual

Server Worklist API RWSReadWorklistRecord (Continued)

RWWORKLIST The RWWORKLIST parameter is used as described in the pWorklist Rec parameter above. The RWWORKLIST parameter is also used in the RWSReadWorklistRecord(), RWSWriteWorklistRecord(), and RWSAppendWorklistRecord() functions.

Structure of typedef struct _RWWORKLIST RWWORKLIST { USHORT cb; SHORT iRecordNumber; SHORT sCommand; BYTE bWhere; BYTE bWhen; ULONG ulOptions; LONG lUserContext; USHORT usReferenceCount; CHAR szParam1[MAX_PARAM_LENGTH]; CHAR szParam2[MAX_PARAM_LENGTH]; BYTE Reserved[36]; } RWWORKLIST, *PRWWORKLIST; cb This is the size of this RWWORKLIST record. iRecordNumber This is the worklist record number from which to start reading or writing records (depending on whether the RWSReadWorklistRecord() or RWSWriteWorklistRecord() function is called). A value is not required for the RWSAppendWorklistRecord() function. CHAPTER 3 / Server API Functions 41

Server Worklist API RWSReadWorklistRecord (Continued) sCommand This is a worklist command.

Valid command values

WL_SENDFILE Send a file to the Client.

WL_GETFILE Get a file from the Client.

WL_SENDDIR Send a directory to the Client.

WL_GETDIR Get a directory from the Client.

Note: The WL_SENDDIR and WL_GETDIR events are provided for backward compatibility only. For new applications, use the WL_SENDFILE and WL_GETFILE events with wildcards instead. WL_RENAMEFILE Rename a file.

WL_DELETEFILE Delete a file.

WL_COPYFILE Copy a file.

WL_APPENDFILE Append one file to another.

WL_FILESTAT Check if file exists.

WL_DIRECTORY Pipe directory listing to a file.

WL_CHECKDISK Check disk statistics.

WL_MAKEDIR Make a directory. 42 RemoteWare API Manual

Server Worklist API RWSReadWorklistRecord (Continued)

sCommand Valid command values (continued)

WL_REMOVEDIR Remove a directory.

WL_SETTIME Set Client time.

WL_EXECUTE Execute another program.

WL_WORKLIST Insert a worklist.

WL_NOTIFY Notify another process.

WL_REBOOT_CLIENT Reboot Client at end of session.

WL_WAIT Wait for file or timeout.

WL_ASCII_APPEND Append ASCII file with ^Z check.

WL_USER_ALARM Set user alarm and message.

WL_END_SESSION End session gracefully.

WL_IF_TRUE If previous event is true then...

WL_IF_FALSE If previous event is false then...

WL_ELSE_IF Else do the following...

WL_END_IF End of IF block.

WL_REPEAT_IF_TRUE Repeat if previous event true. CHAPTER 3 / Server API Functions 43

Server Worklist API RWSReadWorklistRecord (Continued) sCommand Valid command values (continued)

WL_REPEAT_IF_FALSE Repeat if previous event false.

WL_END_REPEAT End repeat block.

WL_EXCEPTION Exception worklist.

WL_GROUP_TEST Test if Client is in specific group.

WL_COMMENT Add comment text.

WL_SET_VARIABLE Set environment variable’s value.

WL_TEST_VARIABLE Test environment variable.

WL_CHECK_FILE Check file date/time/size. bWhere This parameter specifies where the worklist command should be executed.

Valid command values

WL_ON_SERVER The command runs on the Server.

WL_ON_CLIENT The command runs on the Client.

Note: Some commands run only on the Server; others run only on the Client. The function does not verify that the location is valid for the command you specify. 44 RemoteWare API Manual

Server Worklist API RWSReadWorklistRecord (Continued)

bWhen This parameter specifies when the worklist command is executed.

Valid command values

WL_BEFORE Execute before communication session.

WL_DURING Execute during communication session.

WL_AFTER Execute after communication session.

Note: Some commands do not support all three possible bWhen values. The function does not verify that the bWhen value is valid for the command you specify. ulOptions This bit mask specifies one or more options for this worklist command.

Valid command values

WL_NO_OVERWRITE Do not overwrite an existing file.

WL_UPDATEFILE Send only if file has different date, time, or size.

WL_SAFE_SEND Send using temporary files.

WL_CRITICAL Critical event.

WL_DELETE_AFTER Delete file if successful.

WL_CRITICAL_RETRY Critical event with retries.

WL_NO_COMPRESS Do not apply compression.

WL_NOT_NEEDED Not required for successful completion. CHAPTER 3 / Server API Functions 45

Server Worklist API RWSReadWorklistRecord (Continued) ulOptions WL_CONDITIONAL_FALSE (Continued) Conditional execute if FALSE.

WL_SEND_NEWER Update only if file is newer.

WL_COMPARE_EQUAL Executes if equal.

WL_COMPARE_GREATER Executes if greater than.

WL_COMPARE_GREATEREQ Executes if great than or equal to.

WL_COMPARE_LESS Executes if less than.

WL_COMPARE_LESSEG Executes if less than or equal to.

WL_COMPARE_NOT EQ Executes if no equal.

WL_PREVIOUS_FALSE Executes if previous event false.

WL_PREVIOUS_TRUE Executes if previous event true. szParam1, szParam2 These two members hold parameters (each of size MAX_PARAM_LENGTH) that are passed with the worklist command. For example, in the WL_SENDFILE and WL_GETFILE commands, these parameters specify the source and destination filenames. Reserved This area is reserved for future use. Return values The function returns TRUE if successful, or FALSE otherwise. 46 RemoteWare API Manual

Server Worklist API RWSReadWorklistRecord (Continued)

Example RWHANDLE fhWorklistHandle; RWWORKLIST worklistRec; UINT uiCount; INT rc;

worklistRec.cb = sizeof( worklistRec );

// the following specifies which record in the open // worklist file we wish to begin reading from: worklistRec.iRecordNumber = 0;

uiCount = 1; // read one record

rc = RWSReadWorklistRecord( fhWorklistHandle, &worklistRec, &uiCount ); if ( !rc ) { printf( “RWSReadWorklistRecord: error!\n” ); } else { printf( “RWSReadWorklistRecord: OK, read %d recs\n”, uiCount ); } CHAPTER 3 / Server API Functions 47

Server Worklist API RWSWriteWorklistRecord

Description This function writes a specified number of records to a worklist file handle that was opened by RWSWorklistOpen(). The record number from which to start writing is specified in the iRecordNumber member of the RWWORKLIST structure that is passed to RWSWriteWorklistRecord().

C Synopsis INT RWSWriteWorklistRecord( RWHANDLE hWorklist, PRWWORKLIST pWorklistRec, PUINT puiWriteCount ); Parameters hWorklist This variable contains the file handle that was provided by RWSWorklistOpen() and specifies the particular Worklist file that should be written. pWorklistRec This is a pointer to a variable or array of variables of type RWWORKLIST that contain the record(s) to be written. (For a description of the RWWORKLIST structure, see “RWSReadWorklistRecord” on page 39.) The record number from which to start writing must be specified in the iRecordNumber member of this structure (only in the first element of an RWWORKLIST array). If an array is used, the number of array elements should equal the value of puiReadCount (see the next parameter). puiWriteCount This is a pointer to an unsigned integer. On entry, the integer should be the number of records you wish to write. On return, the integer contains the number of records actually written. Return values The function returns TRUE if successful, or FALSE otherwise.

Example RWHANDLE fhWorklistHandle; RWWORKLIST worklistRec; UINT uiCount; INT rc;

worklistRec.cb = sizeof( worklistRec );

// the following specifies which record in the open // worklist file we wish to write to. In this // case, we wish to write to the first record, // record 0: 48 RemoteWare API Manual

Server Worklist API RWSWriteWorklistRecord (Continued)

Example worklistRec.iRecordNumber = 0; (Continued) worklistRec.sCommand = WL_SENDFILE; worklistRec.bWhere = WL_ON_CLIENT; worklistRec.bWhen = WL_DURING; worklistRec.ulOptions = WL_SAFE_SEND; worklistRec.lUserContext = 0; worklistRec.usReferenceCount = 0; strcpy( worklistRec.szParam1, “a.tmp” ); strcpy( worklistRec.szParam2,”b.tmp” );

uiCount = 1; // write one record

rc = RWSWriteWorklistRecord( fhWorklistHandle, &worklistRec,&uiCount ); if ( !rc ) { printf( “RWSWriteWorklistRecord: error!\n” ); } else { printf( “RWSWriteWorklistRecord: OK, wrote %d recs\n”,uiCount ); }

Server Worklist API RWSDeleteWorklistRecord

Description This function deletes a specified number of records from a worklist file that was opened by RWSWorklistOpen(). The record number from which to start deleting is specified in the iRecordNumber parameter.

C Synopsis INT RWSDeleteWorklistRecord( RWHANDLE hWorklist, INT iRecordNumber, PUINT puiDeleteCount ); Parameters hWorklist This variable contains the file handle that was provided by RWSWorklistOpen() and specifies the particular Worklist file that should be written. iRecordNumber The worklist record number of the first record to delete. CHAPTER 3 / Server API Functions 49

Server Worklist API RWSDeleteWorklistRecord (Continued) puiDeleteCount Pointer to an unsigned integer. On entry, the integer should be the number of records you wish to delete (starting at iRecordNumber). On return, the integer contains the number of records actually deleted. Return values This function returns TRUE if successful or FALSE otherwise.

Example RWHANDLE fhWorklistHandle; UINT uiCount; INT rc;

uiCount = 2;

// Delete the first two worklist records rc = RWSDeleteWorklistRecord( fhWorklistHandle, 0, &uiCount ); if ( !rc ) { printf( “RWSDeleteWorklistRecord: error!\n” ); } else { printf( “RWSDeleteWorklistRecord: OK, deleted %d recs\n”, uiCount ); }

Server Worklist API RWSAppendWorklistRecord

Description This function appends a specified number of records to a worklist file that was opened by RWSWorklistOpen().

C Synopsis INT RWSAppendWorklistRecord( RWHANDLE hWorklist, PRWWORKLIST pWorklistRec, PUINT puiAppendCount ); Parameters hWorklist This variable contains the file handle that was provided by RWSWorklistOpen() and specifies the particular Worklist file that should be modified. 50 RemoteWare API Manual

Server Worklist API RWSAppendWorklistRecord (Continued)

pWorklistRec This is a pointer to a variable or array of variables of type RWWORKLIST that contains the record(s) to be appended. The number of array elements should be equal to the value of puiAppendCount (see the next parameter). For a description of the RWWORKLIST structure, see the “RWSReadWorklistRecord” section earlier in this chapter. puiAppendCount This is a pointer to an unsigned integer. On entry, the integer should be the number of records you wish to append. On return, the integer contains the number of records actually appended. Return values This function returns TRUE if successful, or FALSE otherwise.

Example RWHANDLE fhWorklistHandle; RWWORKLIST worklistRec; UINT uiCount; INT rc;

worklistRec.cb = sizeof( worklistRec );

worklistRec.iRecordNumber = 0; worklistRec.sCommand = WL_SENDFILE; worklistRec.bWhere = WL_ON_CLIENT; worklistRec.bWhen = WL_DURING; worklistRec.ulOptions = WL_SAFE_SEND; worklistRec.lUserContext = 0; worklistRec.usReferenceCount = 0; strcpy( worklistRec.szParam1, “a.tmp” ); strcpy( worklistRec.szParam2, “b.tmp” );

uiCount = 1; // append one record

rc = RWSAppendWorklistRecord( fhWorklistHandle, &worklistRec, &uiCount ); if ( !rc ) { printf( “RWSAppendWorklistRecord: error!\n” ); } else { printf( “RWSAppendWorklistRecord: OK, appended %d recs\n”, uiCount ); } CHAPTER 3 / Server API Functions 51

Server Notify API functions The Server Notify API functions let your program wait for notify requests to process requests or monitor worklists and work queues. These functions create, maintain, and delete WIN32 queues. Worklists and work queues can signal your program by sending a NOTIFY command to the queue. The RWSAPI.DLL file contains these functions. You must execute programs using these functions on the Server’s data drive. You can use Notify API functions to: • Signal your program when a worklist or work queue has completed • Alert your program to a problem encountered by a worklist or work queue • Send data to your program based on the outcome of a worklist or work queue event The following table shows a summary of the Notify API functions:

Table 10. RemoteWare Notify API function summary

Function name Description

RWSNotifyCreate Creates a WIN32 queue. RWSNotifyClose Closes a WIN32 queue. RWSNotifyWait Waits for the specified WIN32 queue to receive a NOTIFY signal. RWSNotifyPending Checks to see if a NOTIFY signal is pending for the specified WIN32 queue.

Server Notify API RWSNotifyCreate Description This function creates a WIN32 queue. Programs and worklists can use this queue to signal your program using the NOTIFY command.

C Synopsis BOOL RWSNotifyCreate( PHQUEUE phq, PSZ pszQueue, PINT piError ); Parameters phq On entry, this pointer contains the address of a variable to receive the queue handle. When the function returns, your variable is updated to contain the assigned handle. This handle should be used for all subsequent queue operations. 52 RemoteWare API Manual

Server Notify API RWSNotifyCreate (Continued)

pszQueue This parameter points to a null-terminated string that names the WIN32 queue on which you wish to receive NOTIFY commands. It must be a valid WIN32 queue name, such as /queues/MyApp.Que. piError On entry, this parameter points to a variable to receive the WIN32 error code. If the function returns FALSE, this variable is updated to reflect the WIN32 error code that contributed to the function’s failure. You can use this error code to determine what caused the problem. Return values If the function returns TRUE, it was successful. If it returns FALSE, then the storage pointed to by piError contains the WIN32 error code explaining what happened.

Example HQUEUE Handle; INT WIN32Error;

if( !RWSNotifyCreate(&Handle, “/queues/MyQueue”, &WIN32Error) ) { printf( “couldn’t create queue: WIN32 error %d\n”, WIN32Error ); terminate(); }

Server Notify API RWSNotifyClose Description This function closes the specified WIN32 queue.

C Synopsis BOOL RWSNotifyClose( HQUEUE hq, PINT piError ); Parameters hq This parameter is the handle that was returned to your application after calling RWSNotifyCreate(). piError On entry, this parameter points to a variable to receive the WIN32 error code. If the function returns FALSE, this variable is updated to reflect the WIN32 error code that contributed to the function’s failure. You can use this error code to determine what caused the problem. CHAPTER 3 / Server API Functions 53

Server Notify API RWSNotifyClose (Continued)

Return values If the function returns TRUE, it was successful. If it returns FALSE, then the storage pointed to by piError contains the WIN32 error code explaining what happened.

Example HQUEUE Handle; INT WIN32Error;

if( !RWSNotifyClose(Handle, &WIN32Error) ) printf( “couldn’t close queue: error %d\n”, WIN32Error );

Server Notify API RWSNotifyWait Description This function waits for a NOTIFY event to be received on the specified queue.

C Synopsis BOOL RWSNotifyWait( HQUEUE hq, PSZ pszClient, PINT piError ); Parameters hq This parameter is the handle that was returned to your application after calling RWSNotifyCreate(). pszClient On entry, this parameter points to a buffer of characters. On return, the buffer contains the text that was sent with the NOTIFY command. If no text was specified in the NOTIFY command, the default value sent is the name of the RemoteWare Client that generated the event. piError On entry, this parameter points to a variable to receive the WIN32 error code. If the function returns FALSE, this variable is updated to reflect the WIN32 error code that contributed to the function’s failure. You can use this error code to determine what caused the problem. Return values If the function returns TRUE, it was successful. If it returns FALSE, then the storage pointed to by piError contains the WIN32 error code explaining what happened. 54 RemoteWare API Manual

Server Notify API RWSNotifyWait (Continued)

Example HQUEUE Handle; INT WIN32Error;

char Notify_Msg[256]; if( RWSNotifyWait(Handle, Notify_Msg, &WIN32Error ) ) printf( “Notify Received: %s\n”, Notify_Msg ); else printf( “RWSNotifyWait failed: error %d\n”, WIN32Error );

Server Notify API RWSNotifyPending

Description This function checks to see if a NOTIFY event is pending on the specified queue. You can use this function instead of RWSNotifyWait() when your program needs to perform other tasks while waiting on a NOTIFY event, or if you only want to wait a certain amount of time to receive the event.

C Synopsis BOOL RWSNotifyPending( HQUEUE hq, PINT piError ); Parameters hq This parameter is the handle that was returned to your application after calling RWSNotifyCreate(). piError On entry, this parameter points to a variable to receive the WIN32 error code. If the function returns FALSE, this variable is updated to reflect the WIN32 error code that contributed to the function’s failure. Use this error code to determine what caused the problem. Return values If the function returns TRUE, a NOTIFY is pending. If it returns FALSE, the storage pointed to by piError contains the WIN32 error code explaining the error. An error code of ERROR_QUEUE _EMPTY or ERROR_SUCCESS indicates the queue is empty. CHAPTER 3 / Server API Functions 55

Server Notify API RWSNotifyPending (Continued)

Example HQUEUE Handle; INT WIN32Error; BOOL rc;

rc=( !RWSNotifyPending(Handle, &WIN32Error) ) if (rc==FALSE) { if( WIN32Error == ERROR_SUCCESS || WIN32Error == ERROR_QUEUE_EMPTY)) { printf( “Notify is not pending.\n” ); else printf( “ERROR, RWSNotifyPending Win32 Error %d\n”,WIN32Error); } else printf( “Notify is pending\n”); 56 RemoteWare API Manual

Server database API functions Server Database APIs let you access information from the RemoteWare for Windows NT Server database and logs. The RWSAPI.DLL file contains these functions. You must execute programs using these functions on the Server’s data drive. You may need to set a lower priority for processes with intensive disk I/O to prevent connections from being lost during communications. Use the WIN32 function SetThreadPriority or SetPriorityClass to modify the priority. RemoteWare Server Database API functions are read-only and automatically open the data files necessary to complete the function. Open data files remain open until you explicitly close the files with the RWSReadClose() API function, or until your program exits. The following table lists the RemoteWare Server Database API function summary. Table 11. Database API functions Function name Description

RWSReadClose Closes all open data files used by the specified Server API function type. RWSReadFileLog Reads records from the file transfer log, starting from the specified position. RWSReadMsgLog Reads records from the message log, starting from the specified position. RWSReadClientComments Reads the comments record data for the specified RemoteWare Client. RWSReadClientInfo Reads the Client information record for the specified RemoteWare Client. RWSReadSessLog Reads records from the session history log, starting from the specified position CHAPTER 3 / Server API Functions 57

Server Database API RWSReadClose Description This function closes any files and frees any memory used by the specified Server API function type. This function is optional since ending the calling process automatically closes the files and frees the memory.

C Synopsis INT RWSReadClose( READTYPEfReadType ); Parameters fReadType This specifies which file is to be closed.

Valid command values

RT_FILELOG Close the file log.

RT_MSGLOG Close the message log.

RT_CLIENTINFO Close the Client information.

RT_CLIENTCMNT Close the Client comments.

RT_SESSLOG Close the session log. piError On entry, this parameter points to a variable to receive the WIN32 error code. If the function returns FALSE, this variable is updated to reflect the WIN32 error code that contributed to the function’s failure. Use this error code to determine what caused the problem. Return values The function returns one of the following values: 0 (zero) The function was successful. E_RWS_PARAM Either the alarm was not set or you supplied an invalid alarm type. other WIN32 error occurred; value is the WIN32 error code. 58 RemoteWare API Manual

Server Database API RWSReadClose (Continued)

Example INT retval; retval = RWSReadClose( RT_FILELOG ); switch( retval ) { case 0: printf( “Files closed successfully\n” ); break; case E_RWS_PARAM: printf( “Invalid parameter\n” ); break; default: printf( “Close failed: error code %d\n”, retval ); }

Server Database API RWSReadFileLog Description This function reads the specified number of records from the file transfer log, starting from the specified position.

C Synopsis INT RWSReadFileLog( READPOS fReadPos, UINT cRecsToRead, PFILELOGREC pflogBuf, PUINT pcRecsRead ); Note: When this function is called, the structtype (FILELOGREC) is populated, but the szServer and szSession fields are blank. CHAPTER 3 / Server API Functions 59

Server Database API RWSReadFileLog (Continued)

Parameters fReadPos This parameter specifies the position from which to start reading. Select one of the following values:

Valid values

RP_LATESTREC Read from the most recently logged record.

RP_NEXTREC Read the record that exists before (that is, backwards in logged time) the last read record. cRecsToRead This parameter specifies the number of records to read. If more than one record is specified, the last record read will be the first record in the buffer (i.e., the buffer is LIFO). pflogBuf This parameter points to the buffer that contains the records read. The records are of type FILELOGREC, which is defined below. Your program must allocate this buffer and make it large enough to contain the number of records you want to read. pcRecsRead On entry, this parameter is the address of an integer to receive the number of records actually read. On return, if the function is successful, the integer is updated to reflect the number of records actually read. This number may be less than cRecsToRead if insufficient records were available to satisfy the request. FILELOGREC The RWWORKLIST parameter is used as described in the pflogBuf parameter above. Structure of typedef struct _FILELOGREC FILELOGREC { BYTE bStatusMask; // Status Bit Mask CHAR szServerPath[RWPATHLGT]; // Server Disk\Path\File Name CHAR szClientPath[RWPATHLGT]; // Client Disk\Path\File Name LONG lDateTime; // File Date/Time Stamp BYTE bCmd; // Command Id LONG lStartTime; // Event Start Time 60 RemoteWare API Manual

Server Database API RWSReadFileLog (Continued)

Structure of LONG lEndTime; FILELOGREC // Event End Time (Continued) CHAR szClient[RWCLIENTLGT]; // Client Name CHAR szSession[RWSESLGT]; // Session Name CHAR szServer[RWSERVERLGT]; // Server Name BYTE bValidMask; // Valid field mask LONG lFileSize; // File size. Only valid if FL_FILESIZE // bit is set in bValidMask BYTE bCompressionRatio; // Compression Ratio. Only valid if FL_COMPRESS // bit is set in bValidMask SHORT sFailCode; // Event failure code (WIN32 error code) CHAR szFill[ 93 ]; // For future fields } FILELOGREC, *PFILELOGREC; bStatusMask This member is a bit mask containing one of the following values:

Valid values

FL_NO_EXECUTE The transfer was not executed.

FL_SUCCESS The transfer was successful.

FL_FAILED The transfer failed. bCmdmember This member contains one of the file transfer commands shown below:

Valid values

FL_GETFILE RemoteWare Client to Server.

FL_SENDFILE RemoteWare Server to Client. CHAPTER 3 / Server API Functions 61

Server Database API RWSReadFileLog (Continued)

bValidMask This member indicates whether the lFileSize or bCompressionRatio members contain valid data. This parameter contains one or more of the following values:

Valid values

FL_FILESIZE lFileSize is valid.

FL_COMPRESS bCompressionRatio is valid. Return values The function returns one of the following values: 0 (zero) The function was successful. E_RWS_EOF All records have been read. E_RWS_PARAM An invalid fReadPos specified. other A WIN32 error occurred. This value is the WIN32 error code.

Example INT Retval; FILELOGREC LogRecords; UINT RecsRead; retval = RWSReadFileLog( RP_NEXTREC, 1, &LogRecords, &RecsRead ); if( (retval == 0) && (RecsRead != 0) ) { switch( LogRecords.bStatusMask ) { case FL_NO_EXECUTE: printf( “file transfer not executed\n”); break;

case FL_SUCCESS: printf( “file transfer successful\n” ); break;

default: printf( “file transfer failed\n” ); break; } } else printf( “read failed: error code %d\n”, retval ); 62 RemoteWare API Manual

Server Database API RWSReadMsgLog

Description This function reads the specified number of records from the message log, starting from the specified position.

C Synopsis INT RWSReadMsgLog( READPOS fReadPos, UINT cRecsToRead, PMSGLOGREC pmlogBuf, PUINT pcRecsRead ); Parameters fReadPos This parameter specifies the position from which to start reading. Specify one of the following values:

Valid values

RP_LATESTREC Read from the most recently logged record.

RP_NEXTREC Read the record that exists before (that is, backwards in logged time) the last read record. cRecsToRead This parameter specifies the number of records to read. If more than one record is specified, the last record read will be the first record in the buffer (i.e., the buffer is LIFO). pmlogBuf This parameter points to the buffer that contains the records read. The records are of type MSGLOGREC, which is defined below. Your program must allocate this buffer and make it large enough to contain the number of records you want to read. pcRecsRead On entry, this parameter is the address of an integer to receive the number of records actually read. On return, if the function is successful, the integer is updated to reflect the number of records actually read. This number may be less than cRecsToRead if insufficient records were available to satisfy the request. MSGLOGREC The MSGLOCREC parameter is used as described in the pmlogBuf parameter above. CHAPTER 3 / Server API Functions 63

Server Database API RWSReadMsgLog (Continued)

Structure of typedef struct _MSGLOGREC MSGLOGREC { ULONG ulTime; // Time the message was submitted INT iPID; // Id of process that submitted the // the message USHORT fMsgType; // Type of message (see below) SHORT iMsgCode; // Code submitted with message (Usually // WIN32 error code) CHAR szMsg[RWMSGLGT]; // Message text CHAR szServer[RWSERVERLGT]; // Name of Server logging process was on CHAR szNetUser[RWNETUSERLGT]; // Name of net user currently logged in // main menu CHAR szFill[ 93 ]; // For future fields } MSGLOGREC, *PMSGLOGREC; fMsgType This member indicates one of the message type values shown below:

Valid values

ML_FATAL_ERROR Message concerning a fatal error.

ML_ERROR Message concerning an error.

ML_INFO Informational message only.

ML_DEBUG Internal system error message.

ML_USER Message was logged by the user. 64 RemoteWare API Manual

Server Database API RWSReadMsgLog (Continued)

Return values The function returns one of the following values: 0 (zero) The function was successful. E_RWS_EOF All records have been read. E_RWS_PARAM An invalid fReadPos specified. other A WIN32 error occurred. This value is the WIN32 error code.

Example INT WIN32Error; MSGLOGREC MsgRec; UINT RecsRead; WIN32Error = RWSReadMsgLog( RP_NEXTREC, 1, &MsgRecord, &RecsRead ); if( (retval == 0) && (RecsRead != 0) ) printf( “Message from server %s\n”, MsgRecord.szServer ); else printf( “read failed: error code %d”\n, WIN32Error );

Server Database API RWSReadClientComments

Description This function reads the comments record and data for the specified RemoteWare Client.

C Synopsis INT RWSReadClientComments( READPOS fReadPos, PSZ pszClientName, PCLIENTCMNTREC pcmntBuf, PSZ pszCmntData ); CHAPTER 3 / Server API Functions 65

Server Database API RWSReadClientComments (Continued)

Parameters fReadPos This parameter specifies the position from which to start reading. Specify one of the following values:

Valid values

RP_NEXTREC Read data for the next RemoteWare Client, in alphabetical order.

RP_USENAME Read data for the Client specified by pszClientName. pszClientName If RP_USENAME is specified for fReadPos, then this parameter specifies which Client record to read. Otherwise, it is NULL. pcmntBuf This parameter points to the buffer to receive the Client comment record. The records are of type CLIENTCMTREC, which is defined later in this section. pszCmntData On entry, this parameter is the address of a buffer to receive the Client comment data. If you do not want the Client comment data, use NULL for pszCmntData. Your buffer should have at least MAX_COMMENTDATA bytes. The comment is returned as a single null-terminated string, but may include embedded carriage returns and other information exactly as entered in the Client comment field. CLIENTCMTREC The CLIENTCMTREC parameter is used as described in the pcmntBuf parameter above. Structure of typedef struct _CLIENTCMNTREC CLIENTCMTREC { CHAR szName[ RWCLIENTLGT ]; CHAR szSerialNumber[ SERIALNUMLGT ]; // Client serial # CHAR szContact1[ CMNTFLDLGT ]; // Fields for contact 1 CHAR szAddr1_1[ CMNTFLDLGT ]; CHAR szAddr1_2[ CMNTFLDLGT ]; CHAR szCityState1[ CMNTFLDLGT ]; CHAR szZipCode1[ ZIPCODELGT ]; CHAR szPhone1[ PHONELGT ]; CHAR szContact2[ CMNTFLDLGT ]; // Fields for contact 2 66 RemoteWare API Manual

Server Database API RWSReadClientComments (Continued)

Structure of CHAR szAddr2_1[ CMNTFLDLGT ]; CLIENTCMTREC CHAR szAddr2_2[ CMNTFLDLGT ]; (Continued) CHAR szCityState2[ CMNTFLDLGT ]; CHAR szZipCode2[ ZIPCODELGT ]; CHAR szPhone2[ PHONELGT ]; CHAR szFill[ 100 ]; // For future fields } CLIENTCMNTREC, *PCLIENTCMNTREC; Return values The function returns one of the following values: 0 (zero) The function was successful. E_RWS_EOF All records have been read. E_RWS_PARAM An invalid fReadPos specified. other A WIN32 error occurred. This value is the WIN32 error code.

Example INT retval; CLIENTCMNTREC CommentRec; CHAR CommentData[MAX_COMMENTDATA]; retval = RWSReadClientComments( RP_NEXTREC, NULL, &CommentRec, &CommentData ); if( !retval ) { printf( “Client %s: Contact %s at %s\n”, CommentRec.szName, CommentRec.szContact1, CommentRec.szPhone1 ); } else printf( “read comment error: %d\n”, retval ); CHAPTER 3 / Server API Functions 67

Server Database API RWSReadClientInfo Description This function reads the Client information record for the specified RemoteWare Client from the Client database.

C Synopsis INT RWSReadClientInfo( READPOS fReadPos, PSZ pszClientName, PCLIENTINFOREC pinfoBuf ); Parameters fReadPos This parameter specifies the position from which to start reading. Specify one of the following values:

Valid values

RP_NEXTREC Read data for the next RemoteWare Client, in alphabetical order.

RP_USENAME Read data for the Client specified by pszClientName. pszClientName If RP_USENAME is specified for fReadPos, then this parameter specifies which Client record to read. pinfoBuf This parameter points to the buffer to receive the Client comment record. The records are of type CLIENTINFOREC, which is defined later in this section. CLIENTINFOREC The CLIENTINFOREC parameter is used as described in the pinfoBuf parameter above.

Structure of typedef struct _CLIENTINFOREC CLIENTINFOREC { USHORT usStatus; // Client Status (1==enabled or // 0==disabled) CHAR szName[RWCLIENTLGT]; // Client’s unique name CHAR szDescription[DESCLGT]; // Description such as Client’s location LONG lCreationDate; // Time/date stamp of the Client’s // creation 68 RemoteWare API Manual

Server Database API RWSReadClientInfo (Continued)

Structure of CHAR chDiskDrive; CLIENTINFOREC // Default disk drive letter (Continued) CHAR szClientPath[RWPATHLGT]; // Default Client path CHAR szPhone1[DIALSTRLGT]; // Primary phone number CHAR szPhone2[DIALSTRLGT]; // Alternate phone # CHAR szPassword[PSWDLGT]; // Client’s password SHORT sTimeOffset; // Offset from Host Time Zone CHAR szRsc1[RWRSCLGT]; // Primary resource CHAR szRsc2[RWRSCLGT]; // Alternate resource CHAR szLdClass1[RWLDCLGT]; // Name of primary long distance class CHAR szLdClass2[RWLDCLGT]; // Name of secondary long distance class CHAR szClientType[TYPELGT]; // Type of Client USHORT fClientMask; // Mask denoting Client configuration; // see below for bit definitions CHAR fLastStatus; // Last session status; see below for // bit definitions LONG lStartTime; // Last session start time LONG lEndTime; // Last session end time USHORT usFilesSent; // Number of files sent USHORT usFilesRcvd; // Number of files rcvd LONG lMemSize; // Client Memory size LONG lMemFree; // Free Memory (Memory fields valid if // ND_STATS bit set in fClientMaskfield) CHAPTER 3 / Server API Functions 69

Server Database API RWSReadClientInfo (Continued)

Structure of LONG lDiskSize; CLIENTINFOREC // Disk size (Continued) LONG lDiskFree; // Free disk space (Disk fields valid if // ND_STATS bit is set in fClientMask // field) ULONG ulBytesSent; // Number of bytes sent ULONG ulBytesRcvd; // Number of bytes rcvd ULONG ulPacketsSent; // Number of pkts sent ULONG ulPacketsRcvd; // Number of pkts rcvd ULONG ulReXmits; // Number of retransmits ULONG ulRejects; // Number of rejects ULONG ulActiveTime; // Active time in seconds ULONG aulPermitServers[NUM_PSERVERS]; // Serial numbers of Servers that are // allowed to communicate with this // Client CLIENTCFG aClientConfigurations[NUM_CLIENT_CONFIGS]; // Client configurations BYTE bPrimaryClientConfig; // Index into aClientConfigurations // representing Client configuration for // primary Server resource, or // INVALID_CLIENTCONFIG if undefined BYTE bAltClientConfig; // Index into aClientConfigurations // representing Client configuration for // alternate Server resource, or // INVALID_CLIENTCONFIG if undefined CHAR szFill[ 20 ]; // For future fields } CLIENTINFOREC, *PCLIENTINFOREC; 70 RemoteWare API Manual

Server Database API RWSReadClientInfo (Continued)

fClientMask Specify one of the following values:

Valid values

ND_ATTRIBUTES File Attributes Enabled.

ND_ESD ESD is Enabled.

ND_APLCOM Applications are Enabled.

ND_SWOSELECTION Work object selection permitted in Dial Directory. fLastStatus Specify one of the following values:

Valid values

ND_UNDEFINED No sessions.

ND_SUCCESS Successful session.

ND_NOCONNECT Unable to connect to Client.

ND_FAIL Connected but session failed. lMemSize, These members are set according to the most recently-executed lMemFree, lDiskSize, CHECK_DISK worklist event. and lDiskFree Return values The function returns one of the following values: 0 (zero) The function was successful. E_RWS_EOF All records have been read. E_RWS_PARAM An invalid fReadPos specified. other A WIN32 error occurred. This value is the WIN32 error code. CHAPTER 3 / Server API Functions 71

Server Database API RWSReadClientInfo (Continued)

Example INT retval; CLIENTINFOREC ClientInfo; retval = RWSReadClientInfo( RP_NEXTREC, NULL, &ClientInfo ); if( !retval ) printf( “Client %s: primary phone is %s\n”, ClientInfo.szName, ClientInfo.szPhone1); else printf( “read Client info failed: error %d\n”, retval );

Server Database API RWSReadSessLog Description This function reads the specified number of records from the session history log, starting from the specified position.

C Synopsis INT RWSReadSessLog( READPOS fReadPos, UINT cRecsToRead, PSESSLOGREC pslogBuf, PUINT pcRecsRead); Parameters fReadPos This parameter specifies the position from which to start reading. Specify one of the following values:

Valid values

RP_LATESTREC Read from the most recently logged record.

RP_NEXTREC Read data for the next RemoteWare Client, in alphabetical order. cRecsToRead This parameter specifies the number of records to read. If more than one record is specified, the last record read will be the first record in the buffer (i.e., the buffer is LIFO). pslogBuf This parameter points to the buffer that contains the records read. The records are of type SESSLOGREC, which is defined later in this section. Your program must allocate this buffer and make it large enough to contain the number of records you want to read. 72 RemoteWare API Manual

Server Database API RWSReadSessLog (Continued)

pcRecsRead On entry, this parameter is the address of an integer to receive the number of records actually read. On return, if the function is successful, the integer is updated to reflect the number of records actually read. This number may be less than cRecsToRead if not enough records were available to satisfy the request. SESSLOGREC The SESSLOGREC parameter is used as described in the pslogBuf parameter above.

Structure of typedef struct _SESSLOGREC SESSLOGREC { BYTE StatusMask; // Status Bit Mask (see below) BYTE bFailCode; // Session failure reason (see below) CHAR szSession[RWSESLGT]; // Session name CHAR szClient[RWCLIENTLGT]; // Client name BYTE bPort; // Port on which session occurred CHAR szResource[RWRSCLGT]; // Resource Type BYTE bTotalTries; // Total tries for this session INT iDataRate; // Data Rate (bps) LONG lStartTime; // Start date/time LONG lEndTime; // End date/time CHAR szLdClass[ RWLDCLGT ]; // Long Distance Class CHAR szServer[ RWSERVERLGT ]; // Name of Server comm ran on CHAR szFill[ 93 ]; // For future fields } SESSLOGREC, *PSESSLOGREC; CHAPTER 3 / Server API Functions 73

Server Database API RWSReadSessLog (Continued)

bStatusMask Specify one of the following values:

Valid values

SL_SUCCESSFUL Session was successful.

SL_FAILED Session Failed.

SL_RECOVER Failed Session Recovered.

SL_FINAL Final Session Log Entry. bFailCode Specify one of the following values:

Valid values

SL_UNDEFINED Undefined error - only valid if !( bStatusMask & SL_SUCCESSFUL ).

SL_NOCONNECT Unable to connect.

SL_CRITICAL Failed due to critical event.

SL_TIMEOUT Timeout waiting for Client.

SL_LOSTLINK Failed due to lost link.

SL_NOANSWER Client modem did not answer.

SL_BUSY Received a busy signal.

SL_NODIALTONE No dial tone on host line.

SL_MODEMERROR Error trying to dial modem. 74 RemoteWare API Manual

Server Database API RWSReadSessLog (Continued)

bFailCode SL_NORESOURCES (Continued) Unable to get resources.

SL_CLIENT_PASSWORD Invalid Client password.

SL_SERIAL_NUMBER Invalid system serial number.

SL_REBOOT System was rebooted.

SL_BAD_DRIVE Invalid Default Disk Drive.

SL_ESD_FAIL Send ESD Failed.

SL_OUT_OF_RANGE Out of range session.

SL_WRONG_CLIENT Wrong Client Name.

SL_UNSCHEDULED Session was unscheduled.

SL_USER_ABORT User Aborted Session.

SL_SECURITY Client Security Failed. Return values The function returns one of the following values: 0 (zero) The function was successful. E_RWS_EOF All records have been read. E_RWS_PARAM An invalid fReadPos specified. other A WIN32 error occurred. This value is the WIN32 error code. CHAPTER 3 / Server API Functions 75

Server Database API RWSReadSessLog (Continued)

Example INT retval; SESSLOGREC SessData; UINT RecsRead; retval = RWSReadSessLog( RP_NEXTREC, 1, &SessData, &RecsRead );

if( !retval ) printf( “Client %s was connected to server %s\n”,SessData.szClient, SessData.szServer ); else printf( “read session log error: %d\n”, retval ); 76 RemoteWare API Manual

Server Object API functions RemoteWare for Windows NT Server Object APIs let you manipulate work objects. The RWSRUNTM.DLL file contains these functions. You must execute programs using these functions on the Server’s data drive. Use Object APIs to perform the following tasks: • Creating and deleting work objects • Specifying or modifying the execution window for an object • Setting the work object’s priority • Limiting the work object’s execution to specific Client types The following table shows the Object API function summary: Table 12. Object API functions Function name Description

RWSObjectCreate Creates a work object. RWSObjectDelete Deletes an existing work object. RWSObjectLock Excludes other processes from modifying a work object. RWSObjectUnlock Unlocks a work object. RWSObjectRead Reads object information for the work object specified. RWSObjectWrite Writes a work object’s information. RWSObjectRename Renames a work object. RWSObjectAssign Assigns a work object to a group. RWSObjectUnassign Removes a work object from a group. RWSObjectQueryObjects Enumerates defined work objects on the Server. RWSObjectQueryMembers Enumerates work objects assigned to a specific group. CHAPTER 3 / Server API Functions 77

Server Object API RWSObjectCreate Description This function creates an empty work object.

C Synopsis INT RWSObjectCreate( PSZ pszCaller, POBJECTREC pObjectRec, PSZ pszKey ); Parameters pszCaller This parameter is a pointer to a null-terminated string that identifies your program to the RemoteWare Server. It can be any descriptive string of up to OBJLGT bytes; it need not be an 8.3 filename. The string you provide is used to log object calls to the RemoteWare Server’s Server Log. pObjectRec This parameter is a pointer to the record defining the object information. The record is of type OBJECTREC, which is described later in this section. pszKey This parameter is a pointer to a null-terminated string of up to KEYLGT bytes, which you can use to restrict access to work objects created by your application. This prevents accidental modification of your work objects by the user or by other application programs. If you do not want to restrict access, pass NULL for this parameter. OBJECTREC The OBJECTREC parameter is used as described in the pObjectRec parameter above. 78 RemoteWare API Manual

Server Object API RWSObjectCreate (Continued)

Structure of typedef struct _OBJECTREC OBJECTREC { USHORT usRecSize; // Size of this record. CHAR szName[OBJLGT]; // Object name. CHAR szOwner[OWNERLGT]; // Object owner’s name. LONG lLastModified; // Time the record was last written (in // seconds since 1970). LONG flFlags; // Flags (see below). BYTE bType; // Type (see below). BYTE bStatus; // 0=Disabled, 1=Enabled. BYTE bExecution; // Execution (see below). BYTE bPriority; // Object priority (WOPRI_MIN..WOPRI_MAX) // PSZpszWorkListFile; // Specify full worklist path when // creating a WOTY_WORKLIST object. // Specify RWS_DELETE to clear object // worklist events. This field only // valid for RWSObjectWrite(). PSZ pszEsdListFile; // Specify full file path of ESD // worklist when creating a WOTY_ESD // object. Specify RWS_DELETE to clear // object ESD events. This field // only valid for RWSObjectWrite(). PSZ pszBefEsdListFile; // Specify full file path of ESD // “before” worklist when creating a // WOTY_ESD object. Specify RWS_DELETE // to clear object ESD before events. // This field only valid for // RWSObjectWrite(). CHAPTER 3 / Server API Functions 79

Server Object API RWSObjectCreate (Continued)

Structure of PSZ pszAftEsdListFile; OBJECTREC // Specify full file path of ESD “after” (Continued) // worklist when creating a WOTY_ESD // object. Specify RWS_DELETE to clear // object ESD “after” events. This field // only valid for RWSObjectWrite(). BYTE abClientTypes[MAXCLIENTTYPES]; // Limit execution to Clients of this // type. Values are valid until the // first WOCT_ANY is found. WOCT_ANY is // only valid if it is the first value. // Valid types are listed at the end of // this section. WOTIME ExecuteStart; // Execution window start time. Set all // record fields to zero (0) if this // field should be ignored on write. WOTIME ExecuteStop; // Execution window end time. Set all // record fields to zero (0) if this // field should be ignored on write. WOTIMEDATEActivateStart; // Activation date/time. Set all record // fields to zero (0) if this field // should be ignored on write. WOTIMEDATEActivateStop; // Deactivation date/time. Set all // record fields to zero (0) if this // field should be ignored on write. BYTE abUserData[USERDATALGT]; // User defined data: not used by // RemoteWare. . // — // — This section pertains to objects of type // — WOTY_APPLICATION only. // — BYTE bLaunchMode; // Launch mode (see end of section) CHAR szExeFile[RWPATHLGT]; // Executable file spec. CHAR szPath[RWPATHLGT]; // Working dir/path. CHAR szCmd[RWPATHLGT]; // Command line string. 80 RemoteWare API Manual

Server Object API RWSObjectCreate (Continued)

Structure of WOTIMEDATE ScheduleStart; OBJECTREC // Schedule execution start time. Set all (Continued) // record fields to zero (0) if this field // should be ignored on write. WOTIMEDATE ScheduleStop; // Schedule execution end time. Set all // record fields to zero (0) if this field // should be ignored on write. BYTE bScheduleRepeatDays; // Repeat schedule every x days. Specify // zero (0) to ignore on write. WOTIME ScheduleRepeatTime; // Repeat schedule every hh:mm:ss. Set all // record fields to zero (0) if this field // should be ignored on write. BOOL fRelease; // If TRUE, executes object eventsif object // enabled. If FALSE, object events not // executed even if object is enabled. // — // — End application info. // — CHAR szFill[ 64 ]; // For future fields. } OBJECTREC, *POBJECTREC; flFlags The flFlags field is a bitmask.

Specify one of the following values:

Valid values

WOF_READONLY_ASN Session, Client, user assignments cannot be modified.

WOF_READONLY_MEMBERS Member assignments cannot be modified.

WOF_READONLY_EVENTS Events cannot be modified. CHAPTER 3 / Server API Functions 81

Server Object API RWSObjectCreate (Continued)

flFlags WOF_ONEONLY (Continued) Only one Application or Application group with the specified owner can be directly assigned to a user at a time.

WOF_NO_USERASN Object cannot be directly assigned to a user or user group.

WOF_NO_MEMBER_RENDEL No member object can be renamed or deleted.

WOF_AUTO_CLIENTASN Object should automatically be assigned to any existing Clients and any new Clients added in the future. bType Specify one of the following values:

Valid values

WOTY_ESD ESD work object.

WOTY_WORKLIST Worklist work object.

WOTY_GROUP Worklist and/or ESD group object.

WOTY_APPLICATION Application object.

WOTY_APPLICATION_GROUP Application group object. bLaunchMode WOLM_NONE bExecution WOEX_DEFAULT Object normally executes but can be turned off by the user.

WOEX_FORCED Object always executes.

WOEX_REQUESTABLE Object normally does not execute but may be requested by user. 82 RemoteWare API Manual

Server Object API RWSObjectCreate (Continued)

bClientType WOCT_ANY Any Client type.

WOCT_DOS_CLIENT DOS compatible Client.

WOCT_WIN32_CLIENT WIN32 Client.

WOCT_SERVER_CLIENT Server Client.

WOCT_VAX_CLIENT VAX Client.

WOCT_XENIX_CLIENT XENIX Client.

WOCT_UNIX_CLIENT UNIX Client.

WOCT_4690_CLIENT 4690 Client.

WOCT_NB_DOS_CLIENT DOS Client using NetBIOS.

WOCT_AIX_CLIENT AIX Client.

WOCT_MAC_CLIENT Macintosh Client.

WOCT_WINDOWS_CLIENT Windows Client.

WOCT_ATT_CLIENT AT&T UNIX Client. Return values The function returns one of the following values: 0 (zero) The function was successful. E_RWS_EXISTS The object name is not unique. E_RWS_PARAM The object information is invalid. CHAPTER 3 / Server API Functions 83

Server Object API RWSObjectCreate (Continued)

E_RWS_INCOMPLE The object was partially created, but an error occurred and the object TE could not be deleted. In this case an object will be created, but the information from pObjectRec will not be associated with the object. E_RWS_AUTOASN_ Object could not be automatically assigned to existing Clients. FAI L ED other A WIN32 error occurred. This value is the WIN32 error code.

Example OBJECTREC ObjectRec; INTrc;

// initialize the record

memset( &ObjectRec, 0, sizeof( OBJECTREC ) ); ObjectRec.usRecSize = sizeof( OBJECTREC ); strcpy( ObjectRec.szName, “Sample Object” ); ObjectRec.bType = WOTY_WORKLIST;

// create the object

rc = RWSObjectCreate( “t_object”, ObjectRec, NULL );

switch ( rc ) { case 0: printf( “‘Sample Object’ created.\n” ); break;

case E_RWS_EXISTS: printf( “Error “Sample Object’ already exists.\n”); break;

case E_RWS_MAX: printf( “Max # of objects already exists.\n”); break;

default: printf( “Error %d creating ‘Sample Object’.\n”,rc ); break; } 84 RemoteWare API Manual

Server Object API RWSObjectDelete

Description This function deletes an existing work object.

C Synopsis INT RWSObjectDelete( PSZ pszCaller, PSZ pszObjectName, PSZ pszKey, BOOL fLock ); Parameters pszCaller This parameter is a pointer to a null-terminated string that identifies your program to the RemoteWare for Windows NT Server. It can be any descriptive string; it need not be an 8.3 filename. The string you provide is used to log object calls to the RemoteWare Server’s Server Log. pszObjectName This parameter is a pointer to a null-terminated string that identifies the object to delete. pszKey This parameter is a pointer to a null-terminated string containing the key with which the object was created. fLock This parameter should be TRUE if the object has not already been locked. If deleting multiple objects, you should first lock all of the objects, and then call this function using FALSE as the fLock parameter. Return values This function returns one of the following values: 0 (zero) The function was successful. E_RWS_NOT_ The object does not exist. EXISTS E_RWS_INVALID_K The key is invalid. EY E_RWS_ The object could not be deleted, but some assignments were undone. INCOMPLETE E_RWS_NO_ The object is assigned to a group that has its RENDEL WOF_NO_MEMBER_RENDEL flag set. E_RWS_IN_USE The object is being edited elsewhere. other A WIN32 error occurred; this value is the WIN32 error code. CHAPTER 3 / Server API Functions 85

Server Object API RWSObjectDelete (Continued)

Example INT rc;

rc = RWSObjectDelete( “t_object”, “Sample Object”, NULL, TRUE );

switch ( rc ) { case 0: printf( “‘Sample Object’ deleted.\n” ); break;

case E_RWS_NOT_EXISTS: printf( “‘Sample Object’ does not exist.\n”); break;

default: printf( “Error %d deleting ‘Sample Object’.\n”, rc ); break; }

Server Object API RWSObjectLock

Description This object locks a work object, excluding other processes from making changes to it. Use this to protect an object or group of objects while making modifications.

C Synopsis INT RWSObjectLock( PSZ pszObjectName ); Parameters pszObjectName This parameter is a pointer to a null-terminated string that identifies the object to lock. Return values This function returns one of the following values: 0 (zero) The function was successful. E_RWS_NOT_ The object does not exist. EXISTS E_RWS_IN_USE The object is being edited elsewhere. 86 RemoteWare API Manual

Server Object API RWSObjectLock (Continued)

other A WIN32 error occurred; this value is the WIN32 error code.

Example INT rc;

rc = RWSObjectLock( “Sample Object” ); switch ( rc ) { case 0: printf( “‘Sample Object’ locked.\n” ); break;

case E_RWS_NOT_EXISTS: printf( “‘Sample Object’ does not exist.\n”); break;

default: printf( “Error %d locking ‘Sample Object’.\n”, rc ); break; }

Server Object API RWSObjectUnlock

Description This function unlocks a work object, allowing other processes to access it.

C Synopsis INT RWSObjectUnlock( PSZ pszObjectName ); Parameters pszObjectName This parameter is a pointer to a null-terminated string that identifies the object to unlock. Return values This function returns one of the following values: 0 (zero) The function was successful. E_RWS_NOT_ The object does not exist. EXISTS other A WIN32 error occurred; this value is the WIN32 error code. CHAPTER 3 / Server API Functions 87

Server Object API RWSObjectUnlock (Continued)

Example INT rc;

rc = RWSObjectUnlock( “Sample Object” ); switch ( rc ) { case 0: printf( “‘Sample Object’ unlocked.\n” ); break;

case E_RWS_NOT_EXISTS: printf( “‘Sample Object’ does not exist.\n”); break;

default: printf( “Error %d unlocking ‘Sample Object’.\n”, rc ); break; }

Server Object API RWSObjectRead

Description This function reads information about a work object.

C Synopsis INT RWSObjectRead( POBJECTREC pObjectRec, PSZ pszKey ); Parameters pObjectRec This parameter points to the record into which you wish to read the object information. On entry, this record must contain the usRecSize and szName fields (the szName field specifies which object to read). On return, the rest of the structure contains the object information. pszKey This parameter is a pointer to a null-terminated string containing the key with which the object was created. Return values This function returns one of the following values: 0 (zero) The function was successful. E_RWS_NOT_ The object does not exist. EXISTS E_RWS_INVALID_K The key is invalid. EY 88 RemoteWare API Manual

Server Object API RWSObjectRead (Continued)

other A WIN32 error occurred; this value is the WIN32 error code.

Example INT rc; OBJECTREC ObjectRec;

// read the object ObjectRec.usRecSize = sizeof( OBJECTREC ); strcpy( ObjectRec.szName, “Sample Object” );

rc = RWSObjectRead( &ObjectRec, NULL );

switch ( rc ) { case 0: printf( “‘Sample Object’ read.\n” ); break;

case E_RWS_NOT_EXISTS: printf( “‘Sample Object’ does not exist.\n”); break;

default: printf( “Error %d reading ‘Sample Object’.\n”, rc ); break; }

Server Object API RWSObjectWrite

Description This function writes a work object’s information. To update a session work object, use RWSObjectWrite() with the locking functions as follows:

1 Lock the object with RWSObjectLock().

2 Read the object with RWSObjectRead().

3 Modify the object’s data structure.

4 Write the object with RWSObjectWrite().

5 Unlock the object with RWSObjectUnlock(). CHAPTER 3 / Server API Functions 89

Server Object API RWSObjectWrite (Continued)

C Synopsis INT RWSObjectWrite( PSZ pszCaller, POBJECTREC pObjectRec, PSZ pszKey ); Parameters pszCaller This parameter is a pointer to a null-terminated string that identifies your program to the RemoteWare for Windows NT Server. It can be any descriptive string; it need not be an 8.3 filename. The string you provide is used to log object calls to the RemoteWare Server’s Server Log. pObjectRec This parameter points to the record that you want to write. pszKey This parameter is a pointer to a null-terminated string containing the key with which the object created. Specify NULL if the object was not created with a key. Return values This function returns one of the following values: 0 (zero) The function was successful. E_RWS_NOT_ The object does not exist. EXISTS E_RWS_PARAM The pObjectRec information is invalid. E_RWS_INVALID_K The key is invalid. EY E_RWS_IN_USE The object is being edited elsewhere. other A WIN32 error occurred; this value is the WIN32 error code. 90 RemoteWare API Manual

Server Object API RWSObjectWrite (Continued)

Example INT rc; OBJECTREC ObjectRec;

/* ... */

rc = RWSObjectWrite( “t_object”, &ObjectRec, NULL);

switch ( rc ) { case 0: printf( “‘Sample Object’ written.\n” ); break;

default: printf( “Error %d writing ‘Sample Object’.\n”, rc ); break; }

Server Object API RWSObjectRename

Description This function renames a work object. Comments If you lock the object prior to performing the RENAME, be sure to use the object’s new name when performing the unlock.

C Synopsis INT RWSObjectRename( PSZ pszCaller, PSZ pszOldName, PSZ pszNewName, PSZ pszKey, BOOL fLock); Parameters pszCaller A pointer to a null-terminated string that identifies your program to the RemoteWare Server. It can be any descriptive string; it need not be an 8.3 filename. The string you provide is used to log object calls to the RemoteWare Server’s Server Log. pszOldName A pointer to a null-terminated string containing the original name of the object you want to rename. pszNewName A pointer to a null-terminated string containing the new name for the object. CHAPTER 3 / Server API Functions 91

Server Object API RWSObjectRename (Continued) pszKey A pointer to a null-terminated string containing the key with which the object was created. fLock This parameter should be TRUE if the object has not already been locked. If renaming multiple objects, you should first lock all of the objects, and then call this function using FALSE as the fLock parameter. Return values This function returns one of the following values: 0 (zero) The function was successful. E_RWS_NOT_ The object does not exist. EXISTS E_RWS_EXISTS An object with the new name already exists. E_RWS_PARAM The pObjectRec information is invalid. E_RWS_INVALID_K The key is invalid. EY E_RWS_IN_USE The object is being edited elsewhere. E_RWS_NO_ The object is assigned to a group that has its RENDEL WOF_NO_MEMBER_RENDEL flag set. other A WIN32 error occurred; this value is the WIN32 error code.

Example INT rc;

rc = RWSObjectRename( “t_object”, “Sample Object”, “Sample2 Object”, NULL, TRUE );

switch ( rc ) { case 0: printf( “‘Sample Object’ renamed.\n”); break;

case E_RWS_NOT_EXISTS: printf( “‘Sample Object’ does not exist.\n”); break; 92 RemoteWare API Manual

Server Object API RWSObjectRename (Continued)

Example case E_RWS_EXISTS: (Continued) printf( “‘Sample2 Object’ already exists.\n”); break;

default: printf( “Error %d renaming ‘Sample Object’.\n”, rc ); break; }

Server Object API RWSObjectAssign Description This function assigns a work object to a group. Comments You do not need to lock the member object prior to making this call. The member object and the group must have been created with the same key.

C Synopsis INT RWSObjectAssign( PSZ pszCaller, PSZ pszObjectGroup, PSZ pszMember, PSZ pszKey ); Parameters pszCaller A pointer to a null-terminated string that identifies your program to the RemoteWare for Windows NT Server. It can be any descriptive string; it need not be an 8.3 filename. The string you provide is used to log object calls to the RemoteWare Server’s Server Log. pszObjectGroup A pointer to a null-terminated string that identifies the group to which the object should be added. pszMember A pointer to a null-terminated string that identifies the object to add to the group. pszKey A pointer to a null-terminated string containing the key with which the object was created. Return values This function returns one of the following values: 0 (zero) The function was successful. CHAPTER 3 / Server API Functions 93

Server Object API RWSObjectAssign (Continued)

E_RWS_NOT_ The object does not exist. EXISTS E_RWS_INVALID_K The key is invalid. EY E_RWS_INVALID_O The owner of the group and the object are not the same WNER E_RWS_MSG_ An error occurred which was logged in the Message Log. LOGGED E_RWS_IN_USE The group is being edited elsewhere. other A WIN32 error occurred; this value is the WIN32 error code.

Example INT rc;

rc = RWSObjectAssign( “t_object”, “Sample Object Group”, “Sample Object”, NULL );

switch ( rc ) { case 0: printf( “‘Sample Object’ assigned.\n” ); break;

case E_RWS_NOT_EXISTS: printf( “‘Sample Object’ does not exist.\n” ); break;

default: printf( “Error %d assigning ‘Sample Object’.\n”, rc ); break; } 94 RemoteWare API Manual

Server Object API RWSObjectUnassign Description This function un assigns a work object from a group.

C Synopsis INT RWSObjectUnassign( PSZ pszCaller, PSZ pszObjectGroup, PSZ pszMember, PSZ pszKey ); Parameters pszCaller This parameter is a pointer to a null-terminated string that identifies your program to the RemoteWare for Windows NT Server. It can be any descriptive string; it need not be an 8.3 filename. The string you provide is used to log object calls to the RemoteWare Server’s Server Log. pszObjectGroup This parameter is a pointer to a null-terminated string that identifies the group from which the object should be removed. pszMember This parameter is a pointer to a null-terminated string that identifies the object to remove from the group. pszKey This parameter is a pointer to a null-terminated string containing the key with which the object was created. Return values This function returns one of the following values: 0 (zero) The function was successful. E_RWS_NOT_ The object does not exist. EXISTS E_RWS_INVALID_K The key is invalid. EY E_RWS_INVALID_O The owner of the group and the object are not the same WNER E_RWS_MSG_ An error occurred which was logged in the Message Log. LOGGED E_RWS_IN_USE The group is being edited elsewhere. other A WIN32 error occurred; this value is the WIN32 error code. CHAPTER 3 / Server API Functions 95

Server Object API RWSObjectUnassign (Continued)

Example rc = RWSObjectUnassign( “t_object”, “Sample Object Group”, “Sample Object”, NULL );

switch ( rc ) { case 0: printf( “‘Sample Object’ unassigned.\n” ); break;

case E_RWS_NOT_EXISTS: printf( “Object and group must both exist.\n” ); break;

default: printf( “Error %d unassigning ‘Sample Object’.\n”, rc ); break; }

Server Object API RWSObjectQueryObjects Description This function enumerates all of the objects defined on the RemoteWare for Windows NT Server, or various subsets thereof.

C Synopsis INT RWSObjectQueryObjects( POBJQUERYRECpObjectQueryRec ); Parameters pObjectQueryRec This parameter is a pointer to the record defining the object information. The record is of type OBJECTREC, which is described later in this section. OBJQUERYREC The OBJQUERYREC parameter is used as described in the pObjectQueryRec parameter above. 96 RemoteWare API Manual

Server Object API RWSObjectQueryObjects (Continued)

Structure of typedef struct _OBJQUERYREC OBJQUERYREC { // Fields to be filled before RWSObjectQuery // call:

USHORT usRecSize; // Size of record. VOID *pfCallBack ) ( struct _OBJQUERYREC * ); BYTE bFilterFlags; BYTE bTypeFilter; PSZ pszOwnerFilter; BYTE bMemberFilter; // Used by RWSObjectQueryMembers(). BOOL fStopQuery; // If set to TRUE no more callbacks will // be made. CHAR szUserData[ 64 ]; // Area for general use in passing info // to callback function.

// Fields filled in by RWSObjectQueryMembers():

PSZ pszObject; // Object name. BYTE bType; // Object type (see WOTY_* later). BYTE bMemberType; // Member type (used by // RWSObjectQueryMembers). PSZ pszObjectOwner; // Object owner. USHORT idObject; // Unique object id. LONG lLastModified; //Time the record was last written (in //seconds since 1970)

// Reserved fields:

CHAR szFill[ 64 ]; // For future fields. } OBJQUERYREC, *POBJQUERYREC; pfCallback The pfCallback member is the address of a function in your application that you want to have called each time an object matching your criteria is found. CHAPTER 3 / Server API Functions 97

Server Object API RWSObjectQueryObjects (Continued)

bFilterFlag The possible values for this member are:

Valid values

WOFLT_TYPE Filter using the value in bTypeFilter.

WOFLT_OWNER Filter using the value in pszOwnerFilter.

WOFLT_MEMBER Filter using the value in bMemberFilter. bTypeFilter The possible flags for this member are:

Valid flags

WOFLT_ESD Callback only for ESD objects.

WOFLT_WORKLIST Callback only for worklist objects.

WOFLT_GROUP Callback only for work object groups.

WOFLT_APPLICATION Callback only for application objects.

WOFLT_APPLICATION_GROUP Callback only for application object groups. bType The possible values returned are:

Values returned

WOTY_ESD Object is an ESD object.

WOTY_WORKLIST Object is a worklist object.

WOTY_GROUP Object is a work object group. 98 RemoteWare API Manual

Server Object API RWSObjectQueryObjects (Continued)

bType WOTY_APPLICATION (Continued) Object is an application object.

WOTY_APPLICATION_GROUP Object is an application object group. bMemberType WOTY_MEMBER_DIRECT Object is directly assigned to group.

WOTY_MEMBER_INDIRECT Object is indirectly assigned to group. Return values The function returns one of the following values: 0 (zero) The function was successful. E_RWS_PARAM One of the structure members was invalid. other A WIN32 error occurred. This value is the WIN32 error code. static VOID DoObjectQCallBackName( POBJQUERYRECpObjectQueryRec ){ PINT pcObjects;

printf( “%s\n”, pObjectQueryRec->pszObject ); pcObjects = (PINT) pObjectQueryRec->szUserData; (*pcObjects)++; } static VOID DoObjectQObjects( VOID ){ OBJQUERYREC ObjectQueryRec; INTrc; PINTpcObjects;

printf(“\nUnordered Object List”); printf(“\n======\n\n”);

// clear record

memset( &ObjectQueryRec, 0, sizeof( ObjectQueryRec ) );

// set callback function to display object names CHAPTER 3 / Server API Functions 99

Server Object API RWSObjectQueryObjects (Continued)

Example ObjectQueryRec.pfCallBack = (Continued) DoObjectQCallBackName;

// point to area DoObjectQCallBackName will // fill in

pcObjects = (PINT) ObjectQueryRec.szUserData; // get list of objects

rc = RWSObjectQueryObjects( &ObjectQueryRec ); switch ( rc ) { case 0: printf( “\n%d object(s).\n”, *pcObjects ); break;

default: printf( “\nError %d querying objects.\n”, rc ); break; } }

Server Object API RWSObjectQueryMembers

Description This function enumerates the work objects assigned to a particular group. Comments It is legitimate to call this API from within a callback. For example, your program could issue a call to RWSObjectQueryObjects(); within the callback function, each object group could initiate a new call to RWSObjectQueryMembers() to enumerate the members of that group.

C Synopsis INT RWSObjectQueryMembers( PSZ pszObjectGroup, POBJQUERYREC pObjectQueryRec ); 100 RemoteWare API Manual

Server Object API RWSObjectQueryMembers (Continued)

Parameters pszObjectGroup This parameter is a null-terminated string naming the group whose members you wish to enumerate. pObjectQueryRec This parameter is a pointer to a record that controls the enumeration. The record is identical in format to the record passed to RWSObjectQueryObjects(). Return values This function returns one of the following values: 0 (zero) The function was successful. E_RWS_PARAM One of the structure members was invalid. other A WIN32 error occurred; this value is the WIN32 error code.

Example static VOID DoObjectQCallBackName( POBJQUERYREC pObjectQueryRec ){ PINT pcObjects;

printf( “%s\n”, pObjectQueryRec->pszObject ); pcObjects = (PINT) pObjectQueryRec->szUserData; (*pcObjects)++; }

/* ... */ OBJQUERYREC ObjectQueryRec; INTrc; PINT pcObjects; PINT pcObjectGrps;

// clear record for object members memset( &ObjectQueryRec, 0, sizeof ( ObjectQueryRec ) );

// set callback function to display member names ObjectQueryRec.pfCallBack = DoObjectQCallBackName;

// point to area DoObjectQCallBackName will fill in pcObjects = (PINT) ObjectQueryRec.szUserData;

// get list of object group members rc = RWSObjectQueryMembers( “Sample Group”, &ObjectQueryRec ); CHAPTER 3 / Server API Functions 101

Server Object API RWSObjectQueryMembers (Continued)

Example switch ( rc ) { (Continued) case 0: printf( “\n%d object(s).\n”,*pcObjects ); break;

default: printf( “\nError %d querying object members.\n”, rc ); break; }

Server Schedule API function The RemoteWare Server Schedule API function, RWSScheduleSession(), lets you schedule a session to run on one or more Clients at a specified time. This function is contained in the RWSAPI.DLL file. You must execute programs using this function on the Server’s data drive. Used with other API functions, for example, you can build a worklist to update a database and schedule a session to execute this worklist on a specified set of Clients.

Server Schedule API RWSScheduleSession

Description This function lets you schedule a session to run on the specified Communication Client or Clients at a given time. Comments If you specified a group name, RWS_ALL_CLIENTS, or RWS_ALL_ASSIGNED, and one or more Clients is disabled, the RemoteWare Server API logs a message but this function does not return an error. This function may place additional error information in the Server Log.

C Synopsis INT RWSScheduleSession( PSZ pszSession, PSZ pszClientOrGrp, PSZ pszStartTime ); 102 RemoteWare API Manual

Server Schedule API RWSScheduleSession (Continued)

Parameters pszSession This parameter is a text string that specifies the name of the session to run. The session must be enabled before calling this function. pszClientOrGrp This parameter specifies the name of the RemoteWare Client, or the group of Clients, on which the session is to run.

Specify one of the following values:

Valid values

“Clientname” Use this format to specify a single Client.

“[grpname]” Use this format to specify the name of a group of Clients.

RWS_ALL_CLIENTS Use this value to run the session on all Clients on the system.

RWS_ALL_ASSIGNED Use this value to run the session on all assigned Clients. pszStartTime This parameter specifies the time, and optionally the date, at which the session should start. Specify one of the following:

Valid values

“hh:mm:ss” Use this format to start the session today at the specified time.

“mm/dd/yy hh:mm:ss” Use this format to run the session at the specified date and time.

RWS_NOW Use this value to run the session immediately. Return values The function returns one of the following values: 0 (zero) The function was successful. E_RWS_PARAM The value of pszSession, pszClientOrGrp, or pszStartTime was invalid. E_RWS_ No Clients are assigned to the group specified, or no Clients are NOCLIENTS assigned to the session if RWS_ALL_ASSIGNED was specified. CHAPTER 3 / Server API Functions 103

Server Schedule API RWSScheduleSession (Continued)

E_RWS_DISABLED The specified session, or the specified individual RemoteWare Client, is disabled. E_RWS_SCHED The session was not successfully submitted to the scheduler. other A WIN32 error occurred. This value is the WIN32 error code.

Example retval = RWSScheduleSession( “updatedb”, “[dbusers]”, “23:00:00” ); switch( retval ) { case 0: printf( “session scheduled.\n” ); break;

case E_RWS_PARAM: printf( “invalid session,group,or start time\n” ); break;

case E_RWS_NOCLIENTS: printf( “no Clients assigned to group “dbusers\n” ); break;

case E_RWS_DISABLED: // Should not happen since we specified a // group printf( “session or Client is disabled\n” ); break;

case E_RWS_SCHED: printf( “scheduler problem\n” ); break;

default: printf( “session not scheduled: error %d\n”, retval ); break; } 104 RemoteWare API Manual

Server Information API function The RemoteWare for Windows NT Server Information API function, RWSQuerySysInfo(), lets you retrieve information about the RemoteWare for Windows NT Server. The RWSAPI.DLL file contains this function. You must execute programs using this function on the Server’s data drive.

Server Information API RWSQuerySysInfo Description This function enumerates all of the objects defined on the RemoteWare for Windows NT Server, or various subsets thereof.

C Synopsis INT RWSQuerySysInfo( INT iQueryLevel, PVOID pvBuf, UINT uiBufSize ); Parameters iQueryLevel This parameter specifies the detail level of information needed from this query. It is provided for future compatibility. Valid values are RWS_QUERYLEVEL1 and RWS_QUERYLEVEL2. pvBuf This parameter is a pointer to the buffer that you want to receive the information. For RemoteWare Release 3.1, if you specify RWS_QUERYLEVEL1 in the iQueryLevel field, you should pass the address of a variable of type QUERYINFO1 (defined later in this section); if you specify RWS_QUERYLEVEL2 in the iQueryLevel field, you should pass the address of a variable of type QUERYINFO2 (defined later in this section). uiBufSize This parameter indicates the size of the buffer whose address you passed for pvBuf. QUERYINFO1 and The QUERYINFO1 and QUERYINFO2 parameters are used as QUERYINFO2 described in the pvBuf parameter above. CHAPTER 3 / Server API Functions 105

Server Information API RWSQuerySysInfo (Continued)

Structure of typedef struct _QUERYINFO1 QUERYINFO1 { CHAR szSystem[SYSTEMLGT]; // Cluster name. CHAR szServer[RWSERVERLGT]; // Server name. ULONG ulSerialNumber;// Server serial #. CHAR szVersion[RWVERSIONLGT]; // Server version. CHAR szReleaseDate[ 9 ]; // Server release date (mm-dd-yy). CHAR szFill[ 93 ]; // For future fields. } QUERYINFO1, *PQUERYINFO1;

Structure of typedef struct _QUERYINFO2 QUERYINFO2 { BOOL fIsServerRunning; // Is RemoteWare Server service // running. CHAR szExePath[MAX_PATH+1]; // Server executable path. CHAR szDataPath[MAX_PATH+1]; // Server data path. CHAR szFill[ 64 ]; // For future fields. } QUERYINFO2, *PQUERYINFO2; Return values The function returns one of the following values: 0 (zero) The function was successful. E_RWS_PARAM An invalid parameter was passed. other A WIN32 error occurred. This value is the WIN32 error code. 106 RemoteWare API Manual

Server Information API RWSQuerySysInfo (Continued)

Example QUERYINFO1 QueryInfo1Rec; INT rc;

rc = RWSQuerySysInfo( RWS_QUERYLEVEL1, &QueryInfo1Rec, sizeof( QUERYINFO1 ) );

if (rc) { printf( “\nQuerySysInfo failed, errcode %d\n”, rc ); } else { printf( “\n”, “System Name : %s\n”, “Server Name : %s\n”, “Serial Number: %lu\n”, “Version : %s\n”, “Release Date : %s\n”, QueryInfo1Rec.szSystem, QueryInfo1Rec.szServer, QueryInfo1Rec.ulSerialNumber, QueryInfo1Rec.szVersion, QueryInfo1Rec.szReleaseDate, } CHAPTER 3 / Server API Functions 107

Server Reset Security API function The RemoteWare for Windows NT Server Reset Security API function, RWSResetSecurity(), resets the fourth level of Client security on a RemoteWare Server. Reset Security API can be used to reset security for a particular Client or for all local defined Clients on the RemoteWare Server.

Server Reset Security API RWSResetSecurity Description This function resets the fourth level of Client security on a RemoteWare Server.

C Synopsis INT RWSResetSecurity ( PSZ pszClientName ;

Parameters pszClientName - This is a pointer to a null-terminated string that specifies the Client name. Set this to NULL if reset security on all defined Clients is desired. Return values The function returns 0 (zero) if successful. A WIN32 or RemoteWare Server error code is returned if an error occurs. 0 (zero) The function was successful.

Example PSZ pszClientName = “Sample Client” ;

if ( rc ) { printf(“RWSResetSecurity: error %d\n”’ rc) ; } else { printf(“RWSResetSecurity:OK\n”) ; 108 RemoteWare API Manual Chapter 4: 16-bit Windows and 32-bit OS/2 Client APIs

CHAPTER 4

4 16-bit Windows and 32-bit OS/2 Client APIs

This chapter describes the APIs for use with the RemoteWare 16-bit Windows Clients running under Windows 3.x, NT, or 95. You may also use the OS/2 version of the APIs to build applications for OS/2 Nodes. This chapter explains how to use the functions and interpret their return codes.

This chapter includes:

• General notes on using the Windows and OS/2 Client APIs

• Compiling and linking applications for Windows

• Compiling and linking applications for OS/2

• Error codes

• Client Configuration and Status API functions

• Client Transaction Pipe API functions

• Client Worklist API functions

• Client Dialing Directory API functions

• Client Object API functions 110 RemoteWare API Manual

General notes To use the 16-bit Client (Node) for Windows API, your program should contain an #include statement followed by #include . To use 16-bit Windows Client API functions, link with RWNWAPI.LIB, and run with RWNWAPI.DLL in your path. To use the 32-bit OS/2 Client API functions, link with RWNOAPI.LIB and run RWNOAPI.DLL in your path. When using some functions included in RWNAPI.H, you must include an appropriate #define statement (as described in the Comments under each function description in this chapter). The portion of the header file containing the constants, structures, and prototypes for those functions is conditionally included based on an #ifdef check.

Compiling and linking applications for Windows The 16-bit RemoteWare Client APIs for Windows have been tested for use with Microsoft Visual C++ version 1.52. To build a 16-bit Client application using the RemoteWare APIs, include the RWNWAPI.LIB file in your project. Use the following commands and flags when building 16-bit Windows applications with Microsoft Visual C++: cl -AL -G2sw -Zp -W3 -Ox -c test_api.c rc -v /r test_api link /Align:16 /NoDef /NoExt test_api.obj,, test_api, rwnwapi Llibcew libw, test_api ; rc -v test_api.res If the application you build does not behave as expected, check the following: • Verify you are using the correct version of your compiler. For example, confirm you are not trying to build 16-bit code with a 32-bit compiler. • Confirm you have the correct set of include files and libraries for your environment. You may have to generate an import library. See your compiler manual for more information on creating import libraries from a DLL without Object files or source. CHAPTER 4 / 16-bit Windows and 32-bit OS/2 Client APIs 111

Compiling and linking applications for OS/2 The RemoteWare Client APIs for OS/2 have been tested for use with Microsoft Visual Age 3.0. To build an OS/2 Client application using the RemoteWare APIs, include the RWNOAPI.LIB file in your project. Use the following commands and flags when building OS/2 applications with IBM Visual Age 3.0: icc -s: -sm -gm -c test_api.c rc -v /r test_api ilink inofree /Align:4 /NoDef /NoExt test_api.obj,, test_api, rwnwapi Llibcew libw, test_api ; rc -v test_api.res If the programs you create do not behave as expected, check the following: • Verify you are using the correct version of your compiler. For example, confirm you are not trying to build 16-bit code with a 32-bit compiler. • Confirm you have the correct set of include files and libraries for your environment. You may have to generate an import library. See your compiler manual for more information on creating import libraries from a DLL without Object files or source. 112 RemoteWare API Manual

Error codes The RemoteWare Client APIs return two types of error codes. If the error code is positive, it is generally a Windows or OS/2 error code that you can look up in most Windows or OS/2 technical references. If the error code is negative, it is often an error specific to RemoteWare. The following table lists the error codes defined for the RemoteWare 16-bit Windows and 32-bit OS/2 Clients. The function description also lists the error codes returned by that function. Table 13. Client API error codes Name Description

E_RWN_EOF The end of file was reached. E_RWN_PARAM An invalid parameter was supplied.

Client Configuration and Status API functions RemoteWare Client Configuration and Status APIs let you perform actions, request information, and make changes to the Client setup. The following table shows a summary of the Client Configuration and Status API functions: Table 14. Client Configuration and Status API functions Function name Description

RWNodeRequest Requests actions from the Client’s background task. RWNodeGetInfo Requests information from the Client’s background task. RWNodeReadData Requests information from the Client’s setup data configuration. RWNodeWriteData Makes changes to the Client’s setup data configuration. RWNodeQueryStatusText Retrieves the session status. CHAPTER 4 / 16-bit Windows and 32-bit OS/2 Client APIs 113

Windows and OS/2 Client Configuration and Status API RWNodeRequest

Description RWNodeRequest() lets you request services from the Client’s background task, such as dial out, abort session, release port, and others. This function returns a status word indicating the current state of the Client.

Uses for this function include the following:

• Add an option to an application that lets you dial up the RemoteWare Server. • Display the current RemoteWare Client status in your program. • Reinitialize a modem after using it, to leave the modem in a known state for other applications. Comments Client requests are queued to the background Client process. Your program must poll the status to determine when the Client has processed the request. For example, if the Client is dialing the phone, and you send the XR_CANCEL request to stop the connection, the return code most likely indicates the dialup is still in process. After calling RWNodeRequest() you should set up a delay loop, periodically requesting the Client status, until the Client indicates that the request was processed.

Also, if your program uses this function call, be sure to #define INCL_RWN_NODE prior to including RWNAPI.H. Warning For Clients running under Windows, you must release the Windows message queue in order for WINXNODE to run (since this is also a Windows program). Use a Windows timer message to set up the delay loop.

C Synopsis WORD status;

WORD RWNENTRY RWNodeRequest( WORD wRequest ); 114 RemoteWare API Manual

Windows and OS/2 Client Configuration and Status API RWNodeRequest (Continued)

Parameters wRequest This parameter specifies the service you want from the Client API. Except when specifying XR_STATUS or XR_CANCEL, the Client must be disconnected for the service to work.

Specify one of the following values:

Valid values

XR_STATUS Request only the Client status; no services requested. Status is always returned on every call to this function.

XR_REINIT Reinitialize the modem by sending the auto-answer string and re-open a released port.

XR_REMOVE Remove the background Client task from memory, drop the modem DTR, release the port, and turn off auto-answer.

XR_CONNECT1 Dial Server Phone #1.

XR_CONNECT2 Dial Server Phone #2.

XR_CANCEL If currently dialing, cancels the dialout. If connected, requests the Server to terminate the session and log “Remote user aborted session” in the Server Log. Interactive sessions cannot be aborted.

XR_ENABLE_AA Send the auto-answer string to the modem at the end of the session.

XR_DISABLE_AA Send the “no auto-answer” string to the modem at the end of the session (default).

XR_RELEASE_PORT Release the communications port. This allows other applications to use the port. You must use XR_REINIT to open the port again. CHAPTER 4 / 16-bit Windows and 32-bit OS/2 Client APIs 115

Windows and OS/2 Client Configuration and Status API RWNodeRequest (Continued) wRequest (Continued) XR_ENABLE_ESD Enable electronic software distribution for the next session.

XR_DISABLE_ESD Disable electronic software distribution for the next session. The Server logs “Remote user disabled ESD” in the Server Log. Return values RWNodeRequest() returns a 16-bit unsigned integer, which is a bit mask containing zero or more of the following status flags. XS_LOADED The background task is loaded. XS_AUTO_ Auto-answer is enabled. ANSWER XS_DIALING The Client is dialing one of the phone lines. XS_CONNECTING Connection to the Server is in progress. XS_PASSWORD The Client and Server are exchanging the password. XS_CONNECTED The Client is connected to the Server. XS_ The Client is disconnected. DISCONNECTED XS_ESD_ Electronic software distribution is disabled. DISABLED XS_PORT_ The communications port has been released. RELEASED XS_RESOURCE_ The requested resource is loaded and available. READY XS_COUNTER_ The two highest bits in this mask are assigned to the constant MASK XS_COUNTER_MASK. These bits are used as a counter to indicate that the kernel is functioning properly. If you are interested in changes in the current status, rather than the actual status, you must mask off the counter before comparing the previous and current status words since the counter bits are most likely different.

Use code similar to the following:

oldstatus &= ~XS_COUNTER_MASK; newstatus &= ~XS_COUNTER_MASK; if( oldstatus != newstatus ) /* it changed */ 116 RemoteWare API Manual

Windows and OS/2 Client Configuration and Status API RWNodeRequest (Continued)

XS_COUNTER_ If no flags are set (i.e., this function returns a zero), the Client MASK (Continued) background task is not loaded.

For Windows Clients, be careful not to stay inside a loop waiting for status to change. You should yield the processor so that the RemoteWare Client task can execute. In Windows, use a timer message to trigger your status checks, or call PeekMessage() between successive calls to RWNodeRequest().

If you are making a single call to get status information, these precautions are not necessary.

Example WORD status;

status = RWNodeRequest (XR_STATUS);

printf (“Status=%04x\n”,status); if (status == 0) printf (“Client is Not Loaded\n”); if (status & XS_LOADED) printf (“Client is Loaded\n”); if (status & XS_AUTO_ANSWER) printf (“Auto Answer Enabled\n”); if (status & XS_DIALING) printf (“Client is Dialing\n”); if (status & XS_CONNECTING) printf (“Client is Connecting\n”); if (status & XS_PASSWORD) printf (“Password Exchange\n”); if (status & XS_CONNECTED) printf (“Client is Connected\n”); if (status & XS_DISCONNECTED) printf (“Client is Disconnected\n”); if (status & XS_ESD_DISABLED) printf (“ESD is Disabled\n”); if (status & XS_PORT_RELEASED) printf (“Port is Released\n”); if (status & XS_RESOURCE_READY) printf (“Resource is Ready\n”); CHAPTER 4 / 16-bit Windows and 32-bit OS/2 Client APIs 117

Windows and OS/2 Client Configuration and Status API RWNodeGetInfo

Description This function requests information from the Client background task. Uses include:

• Determining whether the Client background task is loaded. • Determining the last session’s status. • Determining the current status of the session. See Also For related information, see “RWNodeWriteData” on page 125. Comments If your program uses this function call, be sure to #define INCL_RWN_NODE prior to including RWNAPI.H.

C Synopsis BOOL RWNENTRY RWNodeGetInfo( PXNODE_INFO pInfo, WORD cbInfo ); Parameters pInfo This parameter points to a buffer that contains the Client information structure. The structure is of type XNODE_INFO, defined later in this section. cbInfo This is a 16-bit unsigned integer representing the size of the XNODE_INFO structure. You will usually set this parameter to XNODE_INFO_SIZE. XNODE_INFO The XNODE_INFO parameter is used as described in the pInfo parameter above.

Structure of typedef struct XNODE_INFO_STR XNODE_INFO { WORD status; // Current status ULONG last_session; // Time of last session BYTE bSessStatus; // Last Modem/Session Status BYTE command; // Current session command ULONG file_size; // File size ULONG bytes_transfered; // Bytes Transferred 118 RemoteWare API Manual

Windows and OS/2 Client Configuration and Status API RWNodeGetInfo (Continued)

Structure of CHAR filename[PATH_LEN]; XNODE_INFO // File being sent/rcvd (Continued) BYTE node_drive; // Default Client Drive BYTE node_major; // Client Major Version number BYTE node_minor; // Client Minor Version number BYTE bResource ; // Current Client Resource BYTE bRscStatus; // Status of loaded resource WORD nRscError ; // Client Resource error ULONG StartTime ; // Session start time ULONG ConnectedSystem ; // Connected system serial # CHAR szPhone[PHONE_LEN] ; // Phone # or address called BYTE abReserved[3] ; // Reserved } XNODE_INFO; status The status member is a bit mask. For details, see the description of the RWNodeRequest() earlier in this chapter. last_session This member contains the starting time of the last session, expressed as the number of seconds since January 1, 1970. bSessStatus This member contains the session status. This member is valid only if the XS_DISCONNECTED flag is set in status. The session status is one of the following values.

Valid values

XS_SESS_NONE No modem status is available.

XS_SESS_SUCCESSFUL The session completed successfully. CHAPTER 4 / 16-bit Windows and 32-bit OS/2 Client APIs 119

Windows and OS/2 Client Configuration and Status API RWNodeGetInfo (Continued) bSessStatus XS_SESS_ABORTED (Continued) The session was aborted.

XS_SESS_TIMEOUT A timeout occurred while waiting for the RemoteWare Server.

XS_SESS_LOST_CONNECTION The transport lost the connection.

XS_SESS_PASSWORD_FAIL The Client password exchange failed.

XS_SESS_CANCELED The call was cancelled.

XS_SESS_NO_ANSWER The Server did not answer.

XS_SESS_RESOURCE_ERROR A resource error occurred.

XS_SESS_SERVER_DOWN The RemoteWare Server is down.

XS_SESS_SERVER_SUSPENDED The Server is suspended.

XS_SESS_SCHEDULER_OFF The Server Scheduler is off.

XS_SESS_NODE_DISABLED The Client is disabled.

XS_SESS_NODE_UNDEFINED The Client is undefined.

XS_SESS_NODEREG_DISABLED The RemoteWare Client’s Registration is disabled. 120 RemoteWare API Manual

Windows and OS/2 Client Configuration and Status API RWNodeGetInfo (Continued)

command The command member contains the current session command. This is valid only if the XS_CONNECTED flag is set in status. The command consists of one of the following values: Valid values XC_NONE No command is active. XC_SENDFILE The Client is sending a file. XC_RCVFILE The Client is receiving a file. XC_SWO Session Work Object is executing. If the command is XC_SENDFILE or XC_RCVFILE, the file_size, bytes_transfered, and filename members contain information about the file transfer in progress. node_drive, These members reflect the Client’s data drive and major/minor node_major, and version numbers, respectively. node_minor bResource This member reflects which node resource is presently loaded. Its value can change over time for those Client types which support multiple protocols (such as the Windows Client types). Valid values XRSC_ASYNC Asynchronous (via direct connect or modem). XRSC_X25 X.25. XRSC_NETBIOS NetBIOS. XRSC_TCPIP TCP/IP. XRSC_SPX SPX. XRSC_NONE No resource. CHAPTER 4 / 16-bit Windows and 32-bit OS/2 Client APIs 121

Windows and OS/2 Client Configuration and Status API RWNodeGetInfo (Continued) bRscStatus This member reflects the current status of the resource. The valid values are listed below:

Valid values

X_RSC_OK No errors, status OK.

XS_RSC_ERROR Error (see nRscError).

XS_RSC_LOADING Busy: Resource is loading.

XS_RSC_UNLOADING Busy: Resrouce is unloading.

XS_RSC_REINITING Busy: Resource is re-initializing.

XS_RSC_RELEASING Busy: Resource is realeasing.

XS_RSC_LOAD_FAILED Resource failed to load.

XS_RSC_OPEN_FAILED Resource failed to load. StartTime This member indicates the time that the current session started, expressed in seconds from January 1, 1970 GMT. It is only valid if its value is nonzero or if XS_CONNECTED is set. ConnectedSystem This member contains the serial number of the RemoteWare system to which the Client is presently connected. nRscError This member contains the most recent error from the resource identified in the bResource member. If the bRscStatus member is equal to XS_RSC_LOAD_FAILED, then the possible values for nRscError are the following.

Possible errors

XE_RSC_INTERNAL An internal error occurred. 122 RemoteWare API Manual

Windows and OS/2 Client Configuration and Status API RWNodeGetInfo (Continued)

nRscError TXE_RSC_NOT_AVAILABLE (Continued) The resource is not available.

XE_RSC_DLL_NOT_FOUND The resource’s DLL does not exist.

XE_RSC_INVALID_DLL The resource’s DLL is corrupt.

XE_RSC_NO_MEMORY Insufficient memory is available to load the resource. Return values This function returns one of the following values: TRUE The function was successful. FAL S E The Client background task was not loaded, or the value of cbInfo is greater than the actual size of the structure. If the value of cbInfo is less than the actual size of the structure, RWNodeGetInfo() will return the partial structure with the specified number of bytes, without an error.

Example XNODE_INFO xnode_info;

if (RWNodeGetInfo (&xnode_info, XNODE_INFO_SIZE)) { puts(“RWNodeGetInfo OK”); printf(“Client Version : %u.%u\n”, xnode_info.node_major, xnode_info.node_minor); printf(“Client Drive : %c\n”, xnode_info.node_drive); printf(“Client Status : %04x\n”, xnode_info.status); printf(“Modem Status : %x\n”, xnode_info.modem_status);} CHAPTER 4 / 16-bit Windows and 32-bit OS/2 Client APIs 123

Windows and OS/2 Client Configuration and Status API RWNodeReadData

Description This function lets your program read the Client setup data. RWNodeReadData() returns the same data that you can view using TEXTCOMM. Uses for this function include:

• Determining which communications port will be used for dialed connections. • Determining the scheduled inbound session time. Comments If your program uses this function call, be sure to #define INCL_RWN_NODE prior to including RWNAPI.H.

C Synopsis INT RWNENTRY RWNodeReadData( PXNODE_DATA pData; WORD cbData; ); Parameters pData This parameter contains a pointer to a buffer that contains the Client information structure. The structure is of type XNODE_DATA, which is defined later in this section. cbData This parameter is a 16-bit unsigned value that determines the size of the XNODE_DATA structure. You will usually set this parameter to XNODE_DATA_SIZE. XNODE_DATA The XNODE_DATA parameter is used as described in the two parameters above.

Structure of typedef struct xnode_data_str XNODE_DATA { CHAR name[NAME_LEN]; // Client Name (Read Only) CHAR password[PASSWORD_LEN]; // Client password CHAR port; // Port Number (0=com1, 1=com2, etc) WORD baud_rate; // Client port baud rate CHAR server_phone1[PHONE_LEN]; // Server phone number 1 CHAR server_phone2[PHONE_LEN]; // Server phone number 2 124 RemoteWare API Manual

Windows and OS/2 Client Configuration and Status API RWNodeReadData (Continued)

Structure of CHAR schedule_active; XNODE_DATA // Schedule Status (1 = active) (Continued) CHAR schedule_retrys; // Schedule Retrys (0 = None) ULONG schedule_time; // Schedule Time (seconds since 1/1/70) } XNODE_DATA; schedule_time This member indicates the scheduled starting date and time for the session, expressed as the number of seconds since January 1, 1970. Return values This function returns one of the following values: 0 (zero) The function was successful. E_RWS_EOF The end of file was reached. E_RWS_PARAM An invalid parameter was specified. other The function failed; the value returned is the Windows error code indicating the reason for the failure.

Example XNODE_DATA xnode_data; INT status;

status = RWNodeReadData (&xnode_data, XNODE_DATA_SIZE); if (status == 0) { puts (“RWNodeReadData OK”); printf (“Node Name: %s\n”, xnode_data.name); printf (“Password : %s\n”, xnode_data.password); printf (“Com Port : COM%d\n”, xnode_data.port+1); printf (“Data Rate: %d\n”, xnode_data.baud_rate); printf (“Phone #1 : %s\n”, xnode_data.server_phone1); printf (“Phone #2 : %s\n”, xnode_data.server_phone2);} else printf (“RWNodeReadData Failed Status=%d\n”, status); CHAPTER 4 / 16-bit Windows and 32-bit OS/2 Client APIs 125

Windows and OS/2 Client Configuration and Status API RWNodeWriteData

Description RWNodeWriteData() lets your program write changes to the RemoteWare Client setup data. Uses for this function include:

• Changing the Server phone number. • Changing the data rate of the modem communications port. Before calling this function, you must first call RWNodeReadData() to get the current Client setup data. Make your changes to the Client setup, then use RWNodeWriteData() to write the changes. See Also For additonal information, see “RWNodeReadData” on page 123. Comments If your program uses this function call, be sure to #define INCL_RWN_NODE prior to including RWNAPI.H.

C Synopsis INT RWNENTRY RWNodeWriteData( PXNODE_DATA pData; WORD cbData; ); Parameters pData This parameter contains a pointer to a buffer that contains the Client information structure. The structure is of type XNODE_DATA, which is defined later in this section. cbData This parameter is a 16-bit unsigned value that determines the size of the XNODE_DATA structure. You will usually set this parameter to XNODE_DATA_SIZE. XNODE_DATA The XNODE_DATA parameter is used as described in the two parameters above.

Structure of typedef struct xnode_data_str XNODE_DATA { CHAR name[NAME_LEN]; // Client Name (Read Only) CHAR password[PASSWORD_LEN]; // Client password CHAR port; // Port Number (0=com1, 1=com2, etc) WORD baud_rate; // Client port baud rate CHAR server_phone1[PHONE_LEN]; // Server phone number 1 126 RemoteWare API Manual

Windows and OS/2 Client Configuration and Status API RWNodeWriteData (Continued)

Structure of CHAR server_phone2[PHONE_LEN]; XNODE_DATA // Server phone number 2 (Continued) CHAR schedule_active; // Schedule Status (1 = active) CHAR schedule_retrys; // Schedule Retrys (0 = None) ULONG schedule_time; // Schedule Time (seconds since 1/1/70) } XNODE_DATA; schedule_time This member indicates the scheduled starting date and time for the session, expressed as the number of seconds since January 1, 1970. Return values This function returns one of the following values: 0 (zero) The function was successful. E_RWS_EOF The end of file was reached. E_RWS_PARAM An invalid parameter was specified. other The function failed; the value returned is the Windows error code indicating the reason for the failure.

Example XNODE_DATA xnode_data; INT status;

status = RWNodeWriteData (&xnode_data, XNODE_DATA_SIZE); if (status == 0) puts (“RWNodeWriteData OK”); else printf (“RWNodeWriteData Failed Status=%d\n”, status); CHAPTER 4 / 16-bit Windows and 32-bit OS/2 Client APIs 127

Windows and OS/2 Client Configuration and Status API RWNodeQueryStatusText

Description This function lets you translate a communications session’s status into a displayable string. Comments If your program uses this function call, be sure to #define INCL_RWN_STATUS prior to including RWNAPI.H.

C Synopsis RWNRET RWNodeQueryStatusText( UINT iInfoLevel, PRWNSTSINFO pStsInfo, PSZ pszText, PUINT pcchText ); Parameters iInfoLevel This parameter allows you to specify the type of information to return from the call.

Valid values

SQI_NODESTATUS Short description of the Client status.

SQI_SESSIONSTATUS Short description of the session status.

SQI_LONGSESSIONSTATUS Long description of the session status.

SQI_SESSERREXPLANATION Long description of the session error.

SQI_RESOURCENAME Description of the resource type.

SQI_RESOURCESTATUS Description of the current resource status. pStsInfo On entry into the function, this parameter contains the address of a variable of type RWNSTSINFO. pszText On entry, this parameter is the address of an array of characters into which you wish to receive the text. On return, the array contains the text specified by iInfoLevel. 128 RemoteWare API Manual

Windows and OS/2 Client Configuration and Status API RWNodeQueryStatusText (Continued)

pcchText On entry, this parameter is a pointer to a variable containing the total size of the buffer pointed to by pszText. On return, the variable is updated to contain the actual length of the text in the buffer. If you need to know how large a buffer to allocate for this call, you can make one call with *pcchText = 0 (or with pszText = NULL) and the function will update *pcchText with the size of the original error text. You can then allocate a buffer of this size and call again to retrieve the actual text. RWNSTSINFO The RWNSTSINFO parameter is used as described in the pStsInfo parameter above.

Structure of typedef struct _RWNSTSINFO { RWNSTSINFO UINT cb; // Size of this structure WORD wNodeStatus; BYTE bSessStatus; BYTE bResource; BYTE bRscStatus; WORD nRscError; } RWNSTSINFO, *PRWNSTSINFO; wNodeStatus The wNodeStatus member is valid only if iInfoLevel is equal to SQI_NODESTATUS.

Valid values

XS_LOADED Background task is loaded.

XS_AUTO_ANSWER Auto answer is enabled.

XS_DIALING Dialing a connection.

XS_CONNECTING Currently connecting.

XS_PASSWORD Exchanging passwords.

XS_CONNECTED Connection established. CHAPTER 4 / 16-bit Windows and 32-bit OS/2 Client APIs 129

Windows and OS/2 Client Configuration and Status API RWNodeQueryStatusText (Continued) wNodeStatus XS_DISCONNECTED (Continued) Currently disconnected.

XS_ESD_DISABLED ESD is disabled.

XS_PORT_RELEASED Comm port is released.

XS_RESOURCE_READY Resource is loaded and available. bSessStatus The bSessStatus member is valid only if iInfoLevel is equal to SQI_SESSIONSTATUS, SQI_LONGSESSIONSTATUS, or SQI_SESSERREXPLANATION.

Valid values

XS_SESS_NONE No modem status is available.

XS_SESS_SUCCESSFUL The session completed successfully.

XS_SESS_ABORTED The session was aborted.

XS_SESS_TIMEOUT A timeout occurred while waiting for the Server.

XS_SESS_LOST_CONNECTION The transport lost the connection.

XS_SESS_PASSWORD_FAIL The Client password exchange failed.

XS_SESS_CANCELED The call was canceled.

XS_SESS_NO_ANSWER The RemoteWare Server did not answer.

XS_SESS_RESOURCE_ERROR A resource error occurred. 130 RemoteWare API Manual

Windows and OS/2 Client Configuration and Status API RWNodeQueryStatusText (Continued)

bSessStatus XS_SESS_SERVER_DOWN (Continued) The RemoteWare Server is down.

XS_SESS_SERVER_SUSPENDED The RemoteWare Server is suspended.

XS_SESS_SCHEDULER_OFF The RemoteWare Server scheduler is off.

XS_SESS_NODE_DISABLED The RemoteWare Client is disabled.

XS_SESS_NODE_UNDEFINED The RemoteWare Client is undefined.

XS_SESS_NODEREG_DISABLED The RemoteWare Client’s Registration is disabled. bResource The bResource member is valid only if iInfoLevel is equal to SQI_SESSIONSTATUS, SQI_LONGSESSIONSTATUS, or SQI_SESSERREXPLANATION, or SQI_RESOURCENAME.

Valid values

XRSC_ASYNC Asynchronous, either via direct connect or modem.

XRSC_X25 X.25

XRSC_NETBIOS NetBIOS

XRSC_TCPIP TCP/IP

XRSC_SPX SPX

XRSC_NONE No resource. CHAPTER 4 / 16-bit Windows and 32-bit OS/2 Client APIs 131

Windows and OS/2 Client Configuration and Status API RWNodeQueryStatusText (Continued)

bRscStatus The bRscStatus member is valid only if iInfoLevel is equal to SQI_SESSIONSTATUS, SQI_LONGSESSIONSTATUS, or SQI_SESSERREXPLANATION.

Valid values

XS_RSC_OK No errors, status is OK.

XS_RSC_ERROR Error (see nRscError).

XS_RSC_LOADING Busy: Resource is loading.

XS_RSC_UNLOADING Busy: Resource is unloading.

XS_RSC_REINITING Busy: Resource is re-initializing.

XS_RSC_RELEASING Busy: Resource is releasing.

XS_RSC_LOAD_FAILED Resource failed to load.

XS_RSC_OPEN_FAILED Resource failed to unload. nRscError The nRscError member is a resource-specific value. For example, in the case of an async connection, the value corresponds to the return code from a Hayes-compatible modem. The nRscError member is needed only if iInfoLevel is equal to SQI_SESSIONSTATUS, SQI_LONGSESSIONSTATUS, or SQI_SESSERREXPLANATION.

If the bRscStatus member is equal to XS_RSC_LOAD_FAILED, then the possible values for nRscError include:

Valid values

XE_RSC_INTERNAL An internal error occurred

XE_RSC_NOT_AVAILABLE The resource is not available. 132 RemoteWare API Manual

Windows and OS/2 Client Configuration and Status API RWNodeQueryStatusText (Continued)

nRscError XE_RSC_DLL_NOT_FOUND (Continued) The resource’s DLL does not exist.

XE_RSC_INVALID_DLL The resource’s DLL is corrupt.

XE_RSC_NO_MEMORY Insufficient memory is available to load the resource. Return values This function returns 0 (zero) for successful completion or an error code otherwise

Example RWNSTSINFO statusArea; CHAR pszStatusText[ 80 ]; UINT uiTextSize = sizeof( pszStatusText );

statusArea.cb = sizeof( statusArea ); rc = RWNodeQueryStatusText( SQI_NODESTATUS, &statusArea, pszStatusText, &uiTextSize ); if ( rc ) { printf( “Error %d reading communications status\n”, rc ); }

Transaction Pipe API functions The Pipe APIs let a process at a RemoteWare Client perform client-server operations via the RemoteWare Transaction Pipe, much like using Named Pipes. The Transaction Pipe provides a reliable bi-directional, transport-independent communications path (similar to a virtual circuit) between a process on a RemoteWare Client and a process on a RemoteWare Server. This provides an alternative way to communicate with the Server without using a traditional session, and is ideal for communication over a Local Area Network (LAN). Transaction Pipe is an emulation of a named pipe via RemoteWare. RemoteWare acts as an agent between a RemoteWare Transaction Pipe Client program and a Named Pipe Server on a RemoteWare Server’s LAN. The Transaction Pipe Client API functions let a Client program open a pipe, send and receive messages through the pipe, and close the pipe when done. However, for a Client program to use these functions, the RemoteWare Server must be running a Named Pipe Server process to manage the pipe and pass messages with appropriate applications. CHAPTER 4 / 16-bit Windows and 32-bit OS/2 Client APIs 133

. Function Name Description

RWNPipeOpen Opens the connection to a Transaction Pipe. RWNPipeClose Closes the connection to a Transaction Pipe. RWNPipeRead Reads a message from an open Transaction Pipe. RWNPipeWrite Writes a message to an open Transaction Pipe.

Transaction Pipe Notification Types When you open a Transaction Pipe, you are given the option to have your application notified of activity on the transaction pipe via standard WinProc messages. When the Transaction Pipe notifies an application, the first message parameter will contain a notification type (defined later in this section) and the second message parameter will contain the handle of the affected pipe instance (type HRWNPIPE).

Value Description

RWPN_CALLING Client is calling Server. RWPN_CONNECTED Pipe has successfully connected. RWPN_DISCONNECTED Pipe has disconnected (normally). RWPN_BROKEN Pipe (or underlying connection) was abnormally terminated. RWPN_MESSAGE Application message has been sent to your program and is waiting to be read. RWPN_LOADING Client is loading. RWPN_UNLOADING Client is unloading. RWPN_REINITIALIZING Client is reinitializing. RWPN_CONNECTING Waiting for pipe connection.

Transaction Pipe Error Codes If an error occurs in a Transaction Pipe function, the return value will be one of the error codes listed in the following table.

Name Description

E_PIPE_NODE_NOT_LOAD The RemoteWare Client has not been loaded. ED E_PIPE_NOT_AVAILABLE The connection to the Server failed. 134 RemoteWare API Manual

Name Description

E_PIPE_NOT_FOUND The connection to the Server succeeded but the open named pipe failed. E_PIPE_BUSY The connection to the Server succeeded but the named pipe Server didn’t accept the request. E_PIPE_CONNECTING Still waiting for connection to the RemoteWare Server or Transaction Pipe Server. E_PIPE_INVALID_HDDIR The hdd value you supplied is not valid. E_PIPE_BUFFER_FULL Insufficient space remains in the buffer to write the currently defined message. Write a smaller message or wait for previously buffered messages to be retrieved by the Server. E_PIPE_TRANSPORT_ERRO The transport resource failed. R E_PIPE_INVALID_HANDLE The specified HRWNPIPE value is invalid. E_PIPE_INVALID_ A supplied parameter is invalid. PARAMETER E_PIPE_BROKEN The Transaction Pipe (or the underlying connection) was abnormally terminated. E_PIPE_INSUFFICIENT_ Insufficient space remains in the buffer to write the currently defined BUFFER message. Write a smaller message or wait for previously buffered messages to be retrieved by the Server. E_PIPE_BAD_PIPE The pipe state is invalid. E_PIPE_NO_DATA A pipe close is in progress. E_PIPE_NOT_CONNECTED The network connection does not exist. E_PIPE_MORE_DATA More data is available. E_PIPE_TIMEOUT The pipe connection has timed out. E_PIPE_TOOMANY Too many pipes are currently open. Eight is the maximum number of pipe connections allowed to be opened at once for RemoteWare. other The function failed. The value returned is the Windows error code indicating the reason for the failure. CHAPTER 4 / 16-bit Windows and 32-bit OS/2 Client APIs 135

Windows and OS/2 Client Transaction Pipe API RWNPipeOpen

Description This function opens the connection to a Transaction Pipe. Comments If your program uses this function call, be sure to #define INCL_RWN_PIPE prior to including RWNAPI.H.

C Synopsis RWNRET RWNENTRY RWNPipeOpen( PHRWNPIPE phrwp, PSZ pszPipeName, PVOID pvMsg, UINT cbMsg, ULONG fulOptions, PRWNPOPEN prwpo ); Parameters phrwp This is a pointer to a variable of type HRWNPIPE that will receive the pipe handle upon successful opening of the Transaction Pipe. pszPipeName This is a pointer to a null-terminated string (maximum size of CCHMAXNAME) that specifies the name of the Transaction Pipe Server to connect with. Transaction Pipe Server names typically take the form \\computername\pipe\pipename. pvMsg This parameter contains a pointer to the Transaction Pipe message buffer, which can contain an initial message (such as initial application data). cbMsg This parameter indicates the number of bytes of the message buffer to be written to the pipe. fulOptions This parameter is for future options. Always pass 0L (zero). prwpo This parameter contains a pointer to a buffer that contains the RWNPOPEN structure, which is defined later in this section. RWNPOPEN The RWNPOPEN parameter is used as described in the prwpo parameter above. 136 RemoteWare API Manual

Windows and OS/2 Client Transaction Pipe API RWNPipeOpen (Continued)

Structure of typedef struct _rwnpopen RWNOPEN { ULONG cb ; // size (in bytes) of this structure. ULONG cbMaxInBuf ; // size (in bytes) of message input // buffer; see RWNPipeRead(). ULONG cbMaxOutBuf ; // size (in bytes) of message output // buffer; see RNWPipeWrite(). ULONG cmsTimeout ; // count in milliseconds to wait // for Server (ALWAYS SET TO 0; // not yet implemented). HWND hwnd ; // window handle to notify ULONG uWndMsg ; // notification window message HDDIR hdd ; // handle of the Dialing Directory entry // to use } RWNPOPEN, FAR * PRWNPOPEN ; Return values This function returns one of the following values: E_PIPE_OK The request was successfully acknowledged.

Note:Important: A return value of E_PIPE_OK means the request to open a pipe has been successfully acknowledged, but it does not mean that the pipe has actually been opened. The Server may have to finish other tasks before actually attempting to open the requested pipe. At that point, either you will begin to receive pipe messages, or you will receive an error message if the open attempt fails. other The function failed. The value returned is an error code indicating the reason for the failure. For descriptions, see “Transaction Pipe Error Codes” on page 133. CHAPTER 4 / 16-bit Windows and 32-bit OS/2 Client APIs 137

Windows and OS/2 Client Transaction Pipe API RWNPipeOpen (Continued)

Example HRWNPIPE hPipe; RWNPOPEN PipeOpenStruct; RWNRET rc;

PipeOpenStruct.cb=sizeof(RWNPOPEN); PipeOpenStruct.cbMaxInBuf=1024; PipeOpenStruct.cbMaxOutBuf=1024; PipeOpenStruct.cmsTimeout=0; // No timeout PipeOpenStruct.hwnd = NULL; PipeOpenStruct.uWndMsg = 0L; PipeOpenStruct.hdd = DEFAULT_DIALDIR_ENTRY;

rc=RWNPipeOpen( &hPipe, (PSZ)”\\\\.\\pipe\\mypipe”, NULL, 0, 0L, &PipeOpenStruct);

Windows and OS/2 Client Transaction Pipe API RWNPipeClose

Description This function closes the connection to a Transaction Pipe that was opened using RWNPipeOpen(). Comments If your program uses this function call, be sure to #define INCL_RWN_PIPE prior to including RWNAPI.H.

C Synopsis RWNRET RWNENTRY RWNPipeClose( HRWNPIPE hrwp, ULONG fulOptions, ); Parameters hrwp This variable initially received the pipe handle from the call to RWNPipeOpen() and identifies the pipe to be closed. fulOptions This parameter is for future options. Always pass 0L (zero). Return values This function returns one of the following values: E_PIPE_OK The function was successful. 138 RemoteWare API Manual

Windows and OS/2 Client Transaction Pipe API RWNPipeClose (Continued)

other The function failed. The value returned is an error code indicating the reason for the failure. For descriptions, see “Transaction Pipe Error Codes” on page 133.

Example HRWNPIPE hPipe;

RWNPipeClose(hPipe,0L);

Windows and OS/2 Client Transaction Pipe API RWNPipeRead

Description This function reads a message from a Transaction Pipe (which was opened using RWNPipeOpen). The message is read from the pipe’s internal input message buffer (of the size specified by cbMaxInBuf in the RWNPipeOpen() call) and is written to the buffer pointed to by pvMsg in the RWNPipeRead() call (with the size specified in cbMsg). The actual number of bytes copied is returned in pcbActual. Comments If your program uses this function call, be sure to #define INCL_RWN_PIPE prior to including RWNAPI.H.

C Synopsis RWNRET RWNENTRY RWNPipeRead( HRWNPIPE hrwp, PVOID pvMsg, UINT cbMsg, PUINT pcbActual, ULONG ulTimeout ); Parameters hrwp This variable initially received the pipe handle from the call to RWNPipeOpen() and identifies the pipe to read from. pvMsg This parameter contains a pointer to the buffer to which the incoming message should be copied. cbMsg This parameter indicates the number of bytes in the buffer pointed to by pvMsg. pcbActual This is a pointer to an unsigned integer. On entry, the integer should be the number of bytes you wish to read. On return, the integer contains the number of bytes actually read. ulTimeout This parameter indicates the number of milliseconds to wait for the Server. CHAPTER 4 / 16-bit Windows and 32-bit OS/2 Client APIs 139

Windows and OS/2 Client Transaction Pipe API RWNPipeRead (Continued)

Return values This function returns one of the following values: E_PIPE_OK The function was successful. other The function failed. The value returned is an error code indicating the reason for the failure. For descriptions, see “Transaction Pipe Error Codes” on page 133.

Example #define BUFFER_SIZE 1024

char pBuffer[BUFFER_SIZE]; UINT cbActual; RWNRET rc;

rc=RWNPipeRead(hPipe,(PVOID)pBuffer,(UINT)BUFFER_ SIZE,&cbActual,0L);

Windows and OS/2 Client Transaction Pipe API RWNPipeWrite

Description This function writes a message to a Transaction Pipe (which was opened using RWNPipeOpen). The message to be written should be stored in the buffer pointed to by pvMsg in the RWNPipeWrite() call (with the message size specified in cbMsg). The message in that buffer is written to the pipe’s internal output message buffer (which is of the size specified by cbMaxOutBuf in the RWNPipeOpen() call used to open the pipe). Comments If your program uses this function call, be sure to #define INCL_RWN_PIPE prior to including RWNAPI.H.

C Synopsis RWNRET RWNENTRY RWNPipeWrite( HRWNPIPE hrwp, PVOID pvMsg, UINT cbMsg, ); Parameters hrwp This variable initially receives the pipe handle from RWNPipeOpen() and identifies the pipe to write to. pvMsg Contains the pointer to the message buffer that holds the message to be written. 140 RemoteWare API Manual

Windows and OS/2 Client Transaction Pipe API RWNPipeWrite (Continued)

cbMsg Indicates the number of bytes of the message buffer to be written to the pipe. Return values This function returns one of the following values: E_PIPE_OK The function was successful. other The function failed. The value returned is an error code indicating the reason for the failure. For descriptions, see “Transaction Pipe Error Codes” on page 133.

Example #define BUFFER_SIZE 1024 char pBuffer[BUFFER_SIZE]; UINT uiLength; RWNRET rc; strcpy(pBuffer,”Text to be sent to named pipe via RemoteWare Server”); uiLength = (UINT)strlen(pBuffer); rc=RWNPipeWrite(hPipe,(PVOID)pBuffer,uiLength); CHAPTER 4 / 16-bit Windows and 32-bit OS/2 Client APIs 141

Client Worklist API functions The Client Worklist APIs let you build a worklist on the Client. This worklist may be transferred and eventually executed on the Server. Worklist APIs allow you to: • Enable the Client user to execute fixed or custom units of work via worklists. • Transfer and manipulate files on either the Server or the Client. • Perform commands on the Server just as if they were executed from a worklist on the Server. The following table shows a summary of the Client Worklist APIs. Table 15. Client Worklist API functions Function name Description

RWNAddWorklistRecord Adds a worklist event to end of an existing worklist Performs operations on an opened worklist file. RWNWorklistOpen Opens a worklist file. RWNWorklistAction Performs operations on an opened worklist file. RWNWorklistClose Closes an opened worklist file. 142 RemoteWare API Manual

Windows and OS/2 Client Worklist API RWNAddWorklistRecord

Description This function adds a worklist event to the end of the specified worklist. If the worklist file does not exist, this function creates the file. Use this function to build a worklist within your application.

Note: You must transfer your worklist to the Server before the worklist can be used. You can use a session worklist to do this, for example, by including the following events: GET MYWRKLST.EVF &WORKLIST MYWRKLST.EVF See Also For more information on creating and using worklists, see Chapter 7. Comments If your program uses this function call, be sure to #define INCL_RWN_WORKLIST prior to including RWNAPI.H.

C Synopsis INT RWNENTRY RWNAddWorklistRecord( PSZ pszWorklistFile, SHORT sCommand, PSZ pszParam1, PSZ pszParam2, BYTE bWhere, BYTE bWhen, ULONG ulOptions ); Parameters This parameter is a string, specifying the name of the worklist file. pszWorklistFile This parameter is the worklist event. sCommand This parameter is the worklist event. pszParam1 This is the first of two data parameters that can be passed with the worklist event. pszParam2 This is the second of two data parameters that can be passed with the worklist event. CHAPTER 4 / 16-bit Windows and 32-bit OS/2 Client APIs 143

Windows and OS/2 Client Worklist API RWNAddWorklistRecord (Continued) bWhere This parameter determines where the worklist event is executed.

Valid values

WL_ON_SERVER Execute this event on the Server.

WL_ON_NODE Execute this event on the Client.

Note: Some worklist events run only on the Server; others run only on the Client. The worklist event fails during a session if you specify the wrong value for one of these events. bWhen This parameter determines when the worklist event is executed.

Valid values

WL_BEFORE Execute before communications session.

WL_DURING Execute during communications session.

WL_AFTER Execute after communications session. ulOptions This parameter is a bit mask that lets you specify one or more options for this worklist event. Return values This function returns one of the following values: 0 (zero) The function was successful. other The function failed; the value returned is the DOS error code indicating the reason for the failure. 144 RemoteWare API Manual

Windows and OS/2 Client Worklist API RWNAddWorklistRecord (Continued)

Example INT retval;

retval = RWNAddWorklistRecord( “mywrklst.evf”, WL_GETFILE, “julyrpt.dat”, “report.dat”, WL_ON_NODE, WL_DURING, WL_CRITICAL );

if( retval ) printf( “add to worklist failed: error %d\n”, retval );

Windows and OS/2 Client Worklist API RWNWorklistOpen Description This functionopens a worklist file in preparation for use by RWNWorklistAction(). See Also For information on creating and using worklists, see Chapter 7. Comments If your program uses this function call, be sure to #define INCL_RWN_WORKLIST prior to including RWNAPI.H.

C Synopsis INT RWNENTRY RWNWorklistOpen( PRWHFILE pfh, PSZ pszWorklistFile ); Parameters This parameter is a string, specifying the name of the worklist file. pfh This is a pointer to a variable of type RWHFILE, which receives the file handle upon successful opening of the worklist file. pszWorklistFile This null-terminated string specifies the worklist file’s name. Typically worklist filenames take the form \\WORKLIST\\.EVF. Return values This function returns 0 (zero) if successful or a DOS/Windows error code if an error occurs. CHAPTER 4 / 16-bit Windows and 32-bit OS/2 Client APIs 145

Windows and OS/2 Client Worklist API RWNWorklistOpen (Continued)

Example RWHFILE fhWorklistHandle; INT rc;

rc = RWNWorklistOpen( &fhWorklistHandle, “\\worklist\\workfile.evf” ); if ( rc ) { printf( “Error %d opening worklist file\n”, rc ); exit(); }

Windows and OS/2 Client Worklist API RWNWorklistAction

Description This function performs operations on a worklist file opened by RWNWorklistOpen(). Comments If your program uses this function call, be sure to #define INCL_RWN_WORKLIST prior to including RWNAPI.H.

C Synopsis INT RWNENTRY RWNWorklistAction( RWHFILE fh, UINT iAction, PRWWORKLIST pWorklistRec, PUINT puiReadWriteCount ); Parameters fh This variable contains the file handle which was provided by RWNWorklistOpen(). 146 RemoteWare API Manual

Windows and OS/2 Client Worklist API RWNWorklistAction (Continued)

iAction This integer specifies what type of action to take on the file. Specify one of the following values:

Valid values

WLA_READ Read a worklist event.

WLA_WRITE Write a worklist event.

WLA_DELETE Mark a worklist event as deleted. WLA_APPEND Append an event to the end of the worklist. pWorklistRec This is a pointer to a variable (or an array of variables) of type RWWORKLIST. For read or write operations, the number of array elements should be equal to the value of puiCount, as described later in this section. puiReadWriteCount This is a pointer to an unsigned integer. On entry, the integer should be the number of records you wish to read or write. On return, the integer contains the number of records actually read or written. RWWORKLIST The RWWORKLIST parameter is used as described in the pWorklistRec parameter above. CHAPTER 4 / 16-bit Windows and 32-bit OS/2 Client APIs 147

Windows and OS/2 Client Worklist API RWNWorklistAction (Continued)

Structure of typedef struct _RWWORKLIST RWWORKLIST { USHORT cb; // Structure size SHORT iRecordNumber; // Worklist record number SHORT sCommand; // Worklist command BYTE bWhere; // On Server or on Client BYTE bWhen; // Before/during/after session ULONG ulOptions; // described later in this section LONG lUserContext; // user defined context field USHORT usReferenceCount; // user defined reference field CHAR szParam1[ WLPARAMLGT ]; // first command parameter CHAR szParam2[ WLPARAMLGT ]; // second command parameter BYTE bReserved[116]; // reserved for future use } RWWORKLIST, *PRWWORKLIST; sCommand The possible command values for the sCommand parameter are listed below:

Valid values

WL_SENDFILE Send a file to the Client.

WL_GETFILE Get a file from the Client.

WL_RENAMEFILE Rename a file.

WL_DELETEFILE Delete a file. 148 RemoteWare API Manual

Windows and OS/2 Client Worklist API RWNWorklistAction (Continued)

sCommand WL_COPYFILE (Continued) Copy a file.

WL_APPENDFILE Append one file to another.

WL_FILESTAT Check if file exists.

WL_DIRECTORY Pipe directory listing to a file.

WL_CHECKDISK Check disk statistics.

WL_MAKEDIR Make a directory.

WL_REMOVEDIR Remove a directory.

WL_SETTIME Set Client time.

WL_EXECUTE Execute another program.

WL_WORKLIST Insert a worklist.

WL_NOTIFY Notify another process.

WL_REBOOT_NODE Reboot Client at end of session.

WL_WORKQUEUE Execute a workqueue.

WL_WAIT Wait for file or timeout.

WL_ASCII_APPEND Append with ^Z check.

WL_USER_ALARM Set user alarm. CHAPTER 4 / 16-bit Windows and 32-bit OS/2 Client APIs 149

Windows and OS/2 Client Worklist API RWNWorklistAction (Continued) sCommand WL_END_SESSION (Continued) End session gracefully.

WL_IF_TRUE If previous event is true then...

WL_IF_FALSE If previous event is false then...

WL_ELSE_IF Else do the following...

WL_END_IF End of IF block.

WL_REPEAT_IF_TRUE Repeat if previous event true.

WL_REPEAT_IF_FALSE Repeat if previous event false.

WL_END_REPEAT End repeat block.

WL_EXCEPTION Exception worklist.

WL_GROUP_TEST Test if Client is in specific group.

WL_COMMENT Add comment text.

WL_SET_VARIABLE Set environment variable’s value.

WL_TEST_VARIABLE Test environment variable.

WL_CHECK_FILE Check file date/time/size. 150 RemoteWare API Manual

Windows and OS/2 Client Worklist API RWNWorklistAction (Continued)

ulOptions The possible command values for the sCommand parameter are listed below:

Valid values

WL_NO_OVERWRITE Do not overwrite an existing file.

WL_UPDATEFILE Send only if file has different date, time, or size.

WL_SAFE_SEND Send using temporary files.

WL_CRITICAL Critical event.

WL_DELETE_AFTER Delete file if successful.

WL_CRITICAL_RETRY Critical event with retries.

WL_NO_COMPRESS Do not apply compression.

WL_NOT_NEEDED Not required for successful completion.

WL_CONDITIONAL_TRUE Conditional execute if TRUE.

WL_CONDITIONAL_FALSE Conditional execute if FALSE.

WL_INCREMENTAL_UPDATE Incrementally update file.

WL_SEND_NEWER Update only if file is newer. CHAPTER 4 / 16-bit Windows and 32-bit OS/2 Client APIs 151

Windows and OS/2 Client Worklist API RWNWorklistAction (Continued)

Return values The function returns 0 (zero) if successful, or a DOS/Windows error code if an error occurs. E_PIPE_OK The request was successfully acknowledged.

Note: A return value of E_PIPE_OK means the request to open a pipe has been successfully acknowledged, but it does not mean that the pipe has actually been opened. The Server may have to finish other tasks before actually attempting to open the requested pipe. At that point, either you will begin to receive pipe messages, or you will receive an error message if the open attempt fails. other The function failed. The value returned is an error code indicating the reason for the failure.

Example RWHFILE fhWorklistHandle; INT rc; RWWORKLIST wlRecord; UINT uiCount = 1;

wlRecord.cb = sizeof( wlRecord ); wlRecord.lRecordNumber = 0;

rc = RWNWorklistAction( fhWorklistHandle, &wlRecord, WLA_READ, &uiCount ); if (rc){ printf( “Error %d reading event from worklist file\n”,rc ); exit(); } 152 RemoteWare API Manual

Windows and OS/2 Client Worklist API RWNWorklistClose Description RWNWorklistClose() closes a worklist file which was opened by RWSWorklistOpen(). Comments If your program uses this function call, be sure to #define INCL_RWN_WORKLIST prior to including RWNAPI.H.

C Synopsis INT RWNENTRY RWNWorklistClose( RWHFILE fh, BOOL fCompressFile ); Parameters fh This variable initially received the file handle from the call to RWSWorklistOpen(). fCompressFile This boolean flag indicates whether worklist records which are tagged as deleted should be physically removed from the file. If TRUE, the file is compressed to remove deleted records. If FALSE, deleted records remain in the file with a mark to indicate that they have been deleted. Return values This function returns 0 (zero) if successful or a DOS/Windows error code if an error occurs.

Example RWHFILE fhWorklistHandle; INT rc;

rc = RWNWorklistClose( fhWorklistHandle, TRUE ); if (rc){ printf( “Error %d closing worklist file\n”, rc ); exit(); } CHAPTER 4 / 16-bit Windows and 32-bit OS/2 Client APIs 153

Client Dialing Directory API functions Client Dialing Directory APIs let you call a Server from the Dialing Directory and display the Dialing Directory dialog box. Use these functions to give your applications a “look and feel” that is similar to the RemoteWare user interfaces. The following table lists the Client Dialing Directory API functions. Table 16. Client Dialing Directory API functions Function name Description

RWNodeDialDirConnect Calls the Server using a specified dialing directory entry. RWNodeDialDirDialog Displays the standard Dialing Directory dialog box.

Windows and OS/2 Client Dialing Directory API RWNNodeDialDirConnect

Description This function calls the RemoteWare Server using the specified Dialing Directory entry. Comments If your program uses this function call, be sure to #define INCL_RWN_DIALDIR_ENTRY prior to including RWNAPI.H.

C Synopsis INT RWNENTRY RWNodeDialDirConnect( HDDIR hdd ); Parameters hdd This parameter specifies the handle of the Dialing Directory entry to use. The values are user-defined IDs; values above 255 are reserved entries defined by the network administrator. Specify HDDIR_DEFAULT to use the currently-selected entry in the Dialing Directory. Return values This function returns 0 (zero) if successful; any other value signifies an error.

Example INT rc;

rc = RWNodeDialDirConnect( DEFAULT_DIALDIR_ENTRY); 154 RemoteWare API Manual

Windows and OS/2 Client Dialing Directory API RWNodeDialDirDialog Description This function displays the standard Dialing Directory dialog box. Comments If your program uses this function call, be sure to #define INCL_RWN_DIALDIR_ENTRY prior to including RWNAPI.H.

C Synopsis INT RWNENTRY RWNodeDialDirDialog( HWND hwnd ); Parameters hwnd The handle of the owner window. Return values This function returns 0 (zero) if successful; any other value signifies an error.

Example INT rc;

rc = RWNodeDialDirDialog( hwndParent );

Client Object API functions Client Work Object APIs let you retrieve information about work objects. Work objects represent individual units of work to be performed during a communications session. With these reusable building blocks, your applications can easily adapt to meet varying communication requirements. The following table lists the Client Object API functions. Table 17. Client Object API functions Function name Description

RWNObjectQueryInfo Gets work object information. RWNObjectQueryObjects Enumerates objects on a specific Server. CHAPTER 4 / 16-bit Windows and 32-bit OS/2 Client APIs 155

Windows and OS/2 Client Object API RWNObjectQueryInfo

Description RWNObjectQueryInfo() gets information about a work object. Comments If your program uses this function call, be sure to #define INCL_RWN_OBJECT prior to including RWNAPI.H.

C Synopsis INT RWNENTRY RWNObjectQueryInfo( ULONG ulSerialNumber, PSZ pszObjectName, PRWNOBJINFO pObjInfoRec, INT cbObjInfoRec ); Parameters ulSerialNumber The serial number of the Server which owns the work object. pszObjectName The name of the object to query. pObjInfoRec Address of the object information record. cbObjInfoRec Size of the object information record in bytes. RRWNOBJINFO The structure of the object information record is as follows:

Structure of typedef struct _rwnobjinfo { RWNOBJINFO LONG flFlags; // values defined in this section. CHAR szName[ CCHRWNOBJNAME ]; // object’s name BYTE bStatus; // 0=disabled, 1=enabled BYTE bType; // values defined in this section. BYTE bExecution; // values defined in this section. BYTE abNodeTypes[ WONT_MAX ]; // values defined in this section. BYTE bPriority; // 0=lowest, 255=highest INT idObject; // unique object identifier ULONGulTimeStamp; // time object was created

RWNAPPINFOAppInfoRec; // valid only for app objects } RWNOBJINFO; 156 RemoteWare API Manual

Windows and OS/2 Client Object API RWNObjectQueryInfo (Continued)

flFlags This is a bitmask consisting of one or more of the following values.

Valid values

WOF_READONLY_ASN The session, Client, and user assignments cannot be modified.

WOF_READONLY_MEMBERS Member assignments cannot be modified.

WOF_READONLY_EVENTS Events cannot be modified. bType This member has one of the following values:

Valid values

WOTY_ESD ESD work object.

WOTY_WORKLIST Worklist work object.

WOTY_GROUP Group object.

WOTY_APPLICATION Application object.

WOTY_APPLICATION_GROUP Application group object. bExecution This member uses one of the following values:

Valid values

WOEX_DEFAULT The object normally runs unless otherwise requested.

WOEX_FORCED The object runs unconditionally.

WOEX_REQUESTABLE The object normally does not run unless otherwise requested. CHAPTER 4 / 16-bit Windows and 32-bit OS/2 Client APIs 157

Windows and OS/2 Client Object API RWNObjectQueryInfo (Continued) abNodeTypes WONT_ANY The object runs on any Client type.

WONT_DOS_NODE The object runs on DOS Clients.

WONT_OS2_NODE The object runs on OS/2 Clients.

WONT_SERVER_NODE The object runs on Server Clients.

WONT_VAX_NODE The object runs on VAX Clients.

WONT_UNIX_NODE The object runs on UNIX Clients.

WONT_XENIX_NODE The object runs on XENIX Clients.

WONT_4690_NODE The object runs on 4690 Clients.

WONT_NB_DOS_NODE The object runs on DOS Clients using NetBIOS.

WONT_AIX_NODE The object runs on AIX Clients.

WONT_MAC_NODE The object runs on Macintosh Clients.

WONT_WINDOWS_NODE The object runs on Windows Clients.

WONT_ATT_NODE The object runs on AT&T UNIX Clients. abNodeTypes WONT_ANY The object runs on any Client type.

WONT_DOS_NODE The object runs on DOS Clients.

WONT_OS2_NODE The object runs on OS/2 Clients. 158 RemoteWare API Manual

Windows and OS/2 Client Object API RWNObjectQueryInfo (Continued)

abNodeTypes WONT_SERVER_NODE (Continued) The object runs on Server Clients.

WONT_VAX_NODE The object runs on VAX Clients.

WONT_UNIX_NODE The object runs on UNIX Clients.

WONT_XENIX_NODE The object runs on XENIX Clients.

WONT_4690_NODE The object runs on 4690 Clients.

WONT_NB_DOS_NODE The object runs on DOS Clients using NetBIOS.

WONT_AIX_NODE The object runs on AIX Clients.

WONT_MAC_NODE The object runs on Macintosh Clients.

WONT_WINDOWS_NODE The object runs on Windows Clients.

WONT_ATT_NODE The object runs on AT&T UNIX Clients. Return values The function returns 0 (zero) if successful, or a DOS/Windows error code if an error occurs.

Example INT rc; ULONG ulServerSerialNumber; OBJINFOREC objInfo;

rc = RWNObjectQueryInfo( ulServerSerialNumber, “Sales ESD”, &objInfo, sizeof(objInfo) ); CHAPTER 4 / 16-bit Windows and 32-bit OS/2 Client APIs 159

Windows and OS/2 Client Object API RWNObjectQueryObject

Description Enumerates objects associated with a particular Server (specified by Server Serial Number). Comments If your program uses this function call, be sure to #define INCL_RWN_OBJECT prior to including RWNAPI.H.

C Synopsis INT RWNENTRY RWNObjectQueryObjects( ULONG ulSerialNumber, PRWNOBJQUERY pObjQueryRec, INT cbObjQueryRec ); Parameters ulSerialNumber The serial number of the Server which owns the work object. pObjQueryRec Address of the object query record of type RWNOBJQUERY. The structure of this record is described later in this section. cbObjQueryRec Size of the object query record in bytes. RWNOBJQUERY The object query structure is defined as follows:

Structure of typedef struct _RWNOBJQUERY RWNOBJQUERY { // Fields to be filled in by caller before // calling RWNObjectQueryObjects:

PFRWNOBJQCALLBACK pfCallBack ; INT fFlags; char *pszFilterUser; char *pszFilterAppGrp; BOOL fStopQuery; CHAR szUserData[ 64 ];

// Fields filled in by RWNObjectQueryObjects: RWNOBJINFO ObjInfoRec; // Object information.

// Reserved fields CHAR szFill[ 64 ]; // For future fields.

} RWNOBJQUERY ; Members of The members of RWNOBJQUERY are as follows: RWNOBJQUERY pfCallBack On entry, specify the callback function you want to invoke for each object found. 160 RemoteWare API Manual

Windows and OS/2 Client Object API RWNObjectQueryObject (Continued)

fFlags Specify which objects to query and how much information to return for each object.

Valid values

RWNOF_ALLOBJECTS If set, then all objects defined on the Server will be returned.

RWNOF_NODEOBJECTS If set, only those objects assigned to the Client will be returned.

RWNOF_APPINFO AppInfoRec field in the ObjInfoRec field will be filled for application objects when set.

RWNOF_EXPANDAPPGRPS When set, the members of any application groups will be returned instead of the application group.

RWNOF_DESKTOP Only the desktop assigned to the specified user will be returned when set. pszFilterUser If specified, only work objects assigned to this user name will produce a callback. pszFilterAppGrp If specified, only work objects assigned to this application group will produce a callback. This field may be used in combination with the pszFilterUser field. fStopQuery During a callback, you should set this field to TRUE if you want to end the search, or FALSE if you want to continue receiving callbacks for more objects. szUserData For your use; it will not be modified by the call. ObjInfoRec Returns the object information in each callback. Return values The function returns 0 (zero) if successful, or a DOS/Windows error code if an error occurs. CHAPTER 4 / 16-bit Windows and 32-bit OS/2 Client APIs 161

Windows and OS/2 Client Object API RWNObjectQueryObject (Continued)

Example VOID CALLBACK _export QueryCallback( RWNOBJQUERY FAR * lpObjQuery ) { SendMessage( hwndLB, LB_ADDSTRING, 0, (LONG) (LPSTR) lpObjQuery-> ObjInfoRec.szName );}

BOOL FAR PASCAL QueryDlg( HWND hDlg ) { INT rc; ULONG ulServerSerialNumber; RWNOBJQUERY objQuery;

/* ... */

objQuery.pfCallBack = (PFRWNOBJQCALLBACK) QueryCallback; objQuery.fFlags = RWNOF_ALLOBJECTS; rc = RWNObjectQueryObjects( ulServerSerialNumber, &objQuery, sizeof(objQuery) );

/* ... */

}

16-bit Object API RWNWorkObjectSelect This function is no longer available. 162 RemoteWare API Manual Chapter X: Chapter Title <-- Apply “chapter hidden” style

CHAPTER 5

5 DOS Client APIs

The RemoteWare Client for DOS (called the DOS Client in this guide) contains all of the DOS Client API calls for the DOS programming environment. This chapter explains how to use the functions and interpret their return codes. It also presents the functions, their parameters, relevant comments, and examples.

This chapter includes:

• General notes on using DOS Client API functions

• Compiling and linking applications

• DOS Client Error codes

• DOS Client Configuration and Status APIs 164 RemoteWare API Manual

General notes To use the RemoteWare Client (Node) for DOS API, your program should contain an #include statement. To use DOS Client API functions in an application, link the application with the appropriate one of the following libraries: Table 18. DOS Client API functions Library to link Model

CNODEAPI.LIB Compact model LNODEAPI.LIB Large model MNODEAPI.LIB Medium model SNODEAPI.LIB Small model When using some functions included in RWNAPI.H, you must be sure to include an appropriate #define statement (as described in the Comments under each function descrip-tion in this chapter). The portion of the header file containing the constants, structures, and prototypes for those functions is conditionally included based on an #ifdef check.

Compiling and linking applications The RemoteWare DOS Client APIs have been tested for use with Microsoft Visual C++ version 1.52. To build a DOS Client application using the RemoteWare APIs, include the RWNWAPI.LIB file in your project. Use the following commands and flags when building DOS applications with Microsoft Visual C++: cl /nologo /Gs /G2 /W3 /AL /Ox /D "NDEBUG" /D "_DOS" /D "RW#" /I "..\include" /FR /c TEST_API.C link /NOLOGO /NOD ?NOE /STACK:5120 ?ONERROR:NOEXE .obj, TEST_API.EXE, nul,..\lib\lnodeapi.lib+oldname+llibce,; If the application you build does not behave as expected, check the following: • Verify you are using the correct version of your compiler. For example, confirm you are not trying to build 16-bit DOS code with a 32-bit compiler. • Confirm you have the correct set of include files and libraries for your environment. You may have to generate an import library. See your compiler manual for more infor-mation on how to create import libraries from a DLL without Object files or source. CHAPTER 5 / DOS Client APIs 165

Error codes The DOS Client APIs return two types of error codes. A positive error code generally indicates a DOS error code that you can look up in most DOS technical references. A negative error code is often an error specific to RemoteWare. The following table displays the error codes defined for the RemoteWare Client. The function description also lists the error codes returned by that function. Table 19. DOS Client API error codes Name Description

E_RWN_EOF The end of file was reached. E_RWN_PARAM An invalid parameter was supplied.

DOS Client Configuration and Status API functions RemoteWare DOS Client Configuration and Status APIs let you perform actions, request information, and make changes to the Client setup. The DOS Client Configuration and Status API functions are: Table 20. DOS Client Configuration and Status API functions Function name Description

RWNodeRequest Requests actions from the Client’s background task. RWNodeGetInfo Requests information from the Client’s background task. 166 RemoteWare API Manual

DOS Client Configuration and Status API RWNodeRequest

Description RWNodeRequest() lets you request services from the Client’s background task, such as dial out, abort session, release port, and others. This function returns a status word indicating the current state of the Client.

Uses for this function include the following:

• Add an option to an application that lets you dial up the RemoteWare Server. • Display the current RemoteWare Client status in your program. • Re-initialize a modem after using it to leave the modem in a known state for other applications. Comments If your program uses this function call, be sure to #define INCL_RWN_NODE prior to including RWNAPI.H.

C Synopsis WORD status;

WORD RWNENTRY RWNodeRequest( WORD wRequest ); Parameters wRequest This parameter specifies the service you want from the Client API. Except when specifying XR_STATUS or XR_CANCEL, the Client must be disconnected for the service to work.

Specify one of the following values:

Valid values

XR_STATUS Request only the Client status; no services requested. Status is always returned on every call to this function.

XR_REINIT Reinitialize the modem by sending the auto-answer string and re-open a released port.

XR_REMOVE Remove the background Client task from memory, drop the modem DTR, release the port, and turn off auto-answer. CHAPTER 5 / DOS Client APIs 167

DOS Client Configuration and Status API RWNodeRequest (Continued) wRequest (Continued) XR_CONNECT1 Dial Server Phone #1.

XR_CONNECT2 Dial Server Phone #2.

XR_CANCEL If currently dialing, cancels the dialout. If connected, requests the Server to terminate the session and log “Remote user aborted session” in the Server Log. Interactive sessions cannot be aborted.

XR_ENABLE_AA Send the auto-answer string to the modem at the end of the session.

XR_DISABLE_AA Send the “no auto-answer” string to the modem at the end of the session (default).

XR_RELEASE_PORT Release the communications port. This allows other applications to use the port. You must use XR_REINIT to open the port again.

XR_ENABLE_ESD Enable electronic software distribution for the next session.

XR_DISABLE_ESD Disable electronic software distribution for the next session. The Server logs “Remote user disabled ESD” in the Server Log. Return values RWNodeRequest() returns a 16-bit unsigned integer, which is a bit mask containing zero or more of the following status flags. XS_LOADED The background task is loaded. XS_AUTO_ Auto-answer is enabled. ANSWER XS_DIALING The Client is dialing one of the phone lines. XS_CONNECTING Connection to the Server is in progress. XS_PASSWORD The Client and Server are exchanging the password. XS_CONNECTED The Client is connected to the Server. XS_ The Client is disconnected. DISCONNECTED 168 RemoteWare API Manual

DOS Client Configuration and Status API RWNodeRequest (Continued)

XS_ESD_ Electronic software distribution is disabled. DISABLED XS_PORT_ The communications port has been released. RELEASED XS_RESOURCE_ The requested resource is loaded and available. READY XS_COUNTER_ The two highest bits in this mask are assigned to the constant MASK XS_COUNTER_MASK. These bits are used as a counter to indicate that the kernel is functioning properly. If you are interested in changes in the current status, rather than the actual status, you must mask off the counter before comparing the previous and current status words since the counter bits are most likely different.

Use code similar to the following:

oldstatus &= ~XS_COUNTER_MASK; newstatus &= ~XS_COUNTER_MASK; if( oldstatus != newstatus ) /* it changed */ If no flags are set (i.e., this function returns a zero), the Client background task is not loaded.

Example WORD status;

status = RWNodeRequest (XR_STATUS);

printf (“Status=%04x\n”,status); if (status == 0) printf (“Client is Not Loaded\n”); if (status & XS_LOADED) printf (“Client is Loaded\n”); if (status & XS_AUTO_ANSWER) printf (“Auto Answer Enabled\n”); if (status & XS_DIALING) printf (“Client is Dialing\n”); if (status & XS_CONNECTING) printf (“Client is Connecting\n”); if (status & XS_PASSWORD) printf (“Password Exchange\n”); CHAPTER 5 / DOS Client APIs 169

DOS Client Configuration and Status API RWNodeRequest (Continued)

Example if (status & XS_CONNECTED) printf (“Client is (Continued) Connected\n”); if (status & XS_DISCONNECTED) printf (“Client is Disconnected\n”); if (status & XS_ESD_DISABLED) printf (“ESD is Disabled\n”); if (status & XS_PORT_RELEASED) printf (“Port is Released\n”); if (status & XS_RESOURCE_READY) printf (“Resource is Ready\n”);

DOS Client Configuration and Status API RWNodeGetInfo

Description This function requests information from the Client background task. Uses include:

• Determining whether the Client background task is loaded. • Determining the last session’s status. • Determining the current status of the session. Comments If your program uses this function call, be sure to #define INCL_RWN_NODE prior to including RWNAPI.H.

C Synopsis BOOL RWNENTRY RWNodeGetInfo( PXNODE_INFO pInfo, WORD cbInfo ); Parameters pInfo This parameter points to a buffer that contains the Client information structure. The structure is of type XNODE_INFO, defined later in this section. cbInfo This is a 16-bit unsigned integer representing the size of the XNODE_INFO structure. You will usually set this parameter to XNODE_INFO_SIZE. XNODE_INFO The XNODE_INFO parameter is used as described in the pInfo parameter above. 170 RemoteWare API Manual

DOS Client Configuration and Status API RWNodeGetInfo (Continued)

Structure of typedef struct XNODE_INFO_STR XNODE_INFO { WORD status; // Current status ULONG last_session; // Time of last session BYTE bSessStatus; // Last Modem/Session Status BYTE command; // Current session command ULONG file_size; // File size ULONG bytes_transfered; // Bytes Transferred CHAR filename[PATH_LEN]; // File being sent/rcvd BYTE node_drive; // Default Client Drive BYTE node_major; // Client Major Version number BYTE node_minor; // Client Minor Version number BYTE bResource ; // Current Client Resource BYTE bRscStatus; // Status of loaded resource WORD nRscError ; // Client Resource error ULONG StartTime ; // Session start time ULONG ConnectedSystem ; // Connected system serial # CHAR szPhone[PHONE_LEN] ; // Phone # or address called BYTE abReserved[3] ; // Reserved } XNODE_INFO; status The status member is a bit mask. For details, see “RWNodeRequest” on page 166. last_session This member contains the starting time of the last session, expressed as the number of seconds since January 1, 1970. CHAPTER 5 / DOS Client APIs 171

DOS Client Configuration and Status API RWNodeGetInfo (Continued) bSessStatus This member contains the session status. This member is valid only if the XS_DISCONNECTED flag is set in status. The session status is one of the following values.

Valid values

XS_SESS_NONE No modem status is available.

XS_SESS_SUCCESSFUL The session completed successfully.

XS_SESS_ABORTED The session was aborted.

XS_SESS_TIMEOUT A timeout occurred while waiting for the RemoteWare Server.

XS_SESS_LOST_CONNECTION The transport lost the connection.

XS_SESS_PASSWORD_FAIL The Client password exchange failed.

XS_SESS_CANCELED The call was cancelled.

XS_SESS_NO_ANSWER The Server did not answer.

XS_SESS_RESOURCE_ERROR A resource error occurred.

XS_SESS_SERVER_DOWN The RemoteWare Server is down.

XS_SESS_SERVER_SUSPENDED The Server is suspended.

XS_SESS_SCHEDULER_OFF The Server Scheduler is off.

XS_SESS_NODE_DISABLED The Client is disabled. 172 RemoteWare API Manual

DOS Client Configuration and Status API RWNodeGetInfo (Continued)

bSessStatus XS_SESS_NODE_UNDEFINED (Continued) The Client is undefined.

XS_SESS_NODEREG_DISABLED The RemoteWare Client’s Registration is disabled. command The command member contains the current session command. This is valid only if the XS_CONNECTED flag is set in status. The command consists of one of the following values:.

Valid values

XC_NONE No command is active.

XC_SENDFILE The Client is sending a file.

XC_RCVFILE The Client is receiving a file.

XC_SWO Session Work Object is executing.

If the command is XC_SENDFILE or XC_RCVFILE, the file_size, bytes_transfered, and filename members contain information about the file transfer in progress. node_drive, These members reflect the Client’s data drive and major/minor node_major, and version numbers, respectively. node_minor bResource This member reflects which node resource is presently loaded. Its value can change over time for those Client types which support multiple protocols (such as the Windows Client types).

Valid values

XRSC_ASYNC Asynchronous (via direct connect or modem).

XRSC_X25 X.25.

XRSC_NETBIOS NetBIOS. CHAPTER 5 / DOS Client APIs 173

DOS Client Configuration and Status API RWNodeGetInfo (Continued) bResource XRSC_TCPIP (Continued) TCP/IP.

XRSC_SPX SPX.

XRSC_NONE No resource. bRscStatus This member reflects the current status of the resource. The valid values are listed below:

Valid values

X_RSC_OK No errors, status OK.

XS_RSC_ERROR Error (see nRscError).

XS_RSC_LOADING Busy: Resource is loading.

XS_RSC_UNLOADING Busy: Resrouce is unloading.

XS_RSC_REINITING Busy: Resource is re-initializing.

XS_RSC_RELEASING Busy: Resource is realeasing.

XS_RSC_LOAD_FAILED Resource failed to load.

XS_RSC_OPEN_FAILED Resource failed to load. StartTime This member indicates the time that the current session started, expressed in seconds from January 1, 1970 GMT. It is only valid if its value is nonzero or if XS_CONNECTED is set. ConnectedSystem This member contains the serial number of the RemoteWare system to which the Client is presently connected. 174 RemoteWare API Manual

DOS Client Configuration and Status API RWNodeGetInfo (Continued)

nRscError This member contains the most recent error from the resource identified in the bResource member. If the bRscStatus member is equal to XS_RSC_LOAD_FAILED, then the possible values for nRscError are the following.

Possible errors for nRscError

XE_RSC_INTERNAL An internal error occurred

XE_RSC_NOT_AVAILABLE The resource is not available.

XE_RSC_DLL_NOT_FOUND The resource’s DLL does not exist.

XE_RSC_INVALID_DLL The resource’s DLL is corrupt.

XE_RSC_NO_MEMORY Insufficient memory is available to load the resource. Return values The function returns one of the following values: TRUE The function was successful. FAL S E The Client background task was not loaded, or the value of cbInfo is greater than the actual size of the structure. If the value of cbInfo is less than the actual size of the structure, RWNodeGetInfo() will return the partial structure with the specified number of bytes, without an error.

Example XNODE_INFO xnode_info;

if (RWNodeGetInfo (&xnode_info, XNODE_INFO_SIZE)) { puts(“RWNodeGetInfo OK”); printf(“Client Version : %u.%u\n”, xnode_info.node_major, xnode_info.node_minor); printf(“Client Drive : %c\n”, xnode_info.node_drive); printf(“Client Status : %04x\n”, xnode_info.status); printf(“Modem Status : %x\n”, xnode_info.modem_status);} Chapter 7: Worklist Events

CHAPTER 6

6 Worklist Events

This chapter describes the events you can use to build a worklist. This chapter includes:

• Using worklists

• Worklist default files and paths

• File transfer events

• Operating system events

• Session control events

• RemoteWare Server events

Each Worklist event type is also discussed in detail in the RemoteWare Server Reference Manual. 176 RemoteWare API Manual

Using worklists Worklists have several uses: • If you have a series of commands that sessions or application programs execute often, you can create a worklist to keep that list in a file, and then execute the commands by inserting the worklist. The worklist can signal your program through a Windows queue if necessary. • Application programs that run on the RemoteWare Client for Windows can have some indirect control over a session by building a worklist, which the RemoteWare Server can GET and perform via the insert WORKLIST event. You can build worklists using the Session Editor or Server worklist API functions on the RemoteWare Server, or by using the RWNAddWorklistRecord() function on a Windows Client.

Client vs. Server worklist APIs Corresponding Worklist functions exist in both the 16- and 32-bit Windows Clients and the Server APIs. However, the names of some events, parameters, and return codes differ slightly. Specifically, the word “Client” is substituted in the Server APIs everywhere that the word “Node” is used in the Client APIs (for example, the “Where” parameter ON_CLIENT in the Server API is equivalent to the ON_NODE parameter in the Client API). In all cases, any events, parameters, and return codes with names that differ in this way still have the same meaning. Note: For simplicity, this chapter discusses all topics from the perspective of the Client API. For the Server API, substitute “Client” for “Node” in events, parameters, and return codes.

Communicating between worklists and programs The worklist can send information to your program. While your program cannot send information back to worklists, the program can directly control their behavior by building worklists as needed. There are several ways to send information to your program:

NOTIFY event By using the WL_NOTIFY worklist event, the worklist can signal your program. For example, you can use the RWSNotifyWait() function to wait for a worklist to signal your program. This technique may prove useful for notifying your program of a completed file transfer. CHAPTER 6 / Worklist Events 177

Pipes If you are writing your application to run on the RemoteWare Server, you can use pipes. A pipe system is more complex than the other methods, but allows your program to communicate with other computers over a Local Area Network (LAN). The following sample code shows how you can use pipes in code written for your RemoteWare Server. This program runs as a Pipe Server process on your RemoteWare Server and waits for another program to send a NOTIFY event to the pipe named \pipe\testpipe.

/* Test Named Pipe Server * * This program waits for a Notify via a Named Pipe from a * RemoteWare session for a particular Client. Once * received, the pipe command is printed. */

#include #include #include

#define TEST_PIPE “\\\\.\\pipe\\testpipe” #define MAX_COMMAND_LENGTH 256 void main(int argc,char *argv[]) { int sts; HANDLE hPipe; char command[MAX_COMMAND_LENGTH]; DWORD bytes;

printf(“Test Pipe Server Started\n”);

/* create the pipe */ if ((hPipe = CreateNamedPipe( TEST_PIPE, // pipe name PIPE_ACCESS_DUPLEX, // read/write mode PIPE_TYPE_MESSAGE | PIPE_READMODE_MESSAGE, // message mode 1, // one instance MAX_COMMAND_LENGTH, // output buffer size MAX_COMMAND_LENGTH, // input buffer size 5000, // 5 second timeout NULL)) == INVALID_HANDLE_VALUE) { printf(“CreateNamedPipe failed status=%lu\n”, GetLastError()); return; }

for(;;) 178 RemoteWare API Manual

{ /* wait for notify event */ if (!ConnectNamedPipe(hPipe,NULL)) { printf(“ConnectNamedPipe failed status %lu\n”, GetLastError()); return; }

/* read the notify text from the pipe */ if (!ReadFile (hPipe,command,MAX_COMMAND_LENGTH,&bytes,NULL)) { printf(“ReadFile failed status %lu\n”,GetLastError()); return; }

sts=0;

if (!WriteFile(hPipe,&sts,sizeof(int),&bytes,NULL)) { printf(“WriteFile failed status %lu\n”,GetLastError()); return; }

printf(“Command received: %s\n”,command);

/*** wait for client to finish ***/

while (PeekNamedPipe(hPipe,NULL,0,NULL,NULL,NULL)) Sleep(500L);

DisconnectNamedPipe(hPipe); }

CloseHandle(hPipe); } CHAPTER 6 / Worklist Events 179

Worklist default files and paths The RemoteWare Server stores worklist files under the \WORKLIST directory. Typically, worklist files have an extension of .EVF (event file). When specifying a RemoteWare Server directory name as a parameter to a worklist event, you can often use NULL to indicate the directory \node\, where is the name of the Client connected during this session. Server file names specified with no path are also automatically assigned the path \node\. If no drive name is specified for directories or files, the default drive is assumed. When specifying a RemoteWare Client directory name as a parameter to a worklist event, you can often use NULL to indicate the default directory defined in the Client profile. Client file names specified with no path are also automatically assigned the path of the default directory defined in the Client profile. If no drive name is specified for directories or files, the default drive is assumed. If you want to prevent the RemoteWare Client or Server from adding the default drive or path to a file or directory name, enclose the name in quotes. This is called a literal. For example: "path\file.ext" You can also use literals to preserve mixed-cased names. This is important for case- sensitive file systems. 180 RemoteWare API Manual

File transfer events File transfer events transfer one or more files from the Client to the Server, or from the Server to the Client. The file transfer events are summarized in the following table: Table 21. File transfer events Function name Description

WL_GETFILE Sends a file from the Client to the Server. WL_GETDIR Sends files matching the wild card from the Client to the Server. WL_SENDFILE Sends a file from the Server to the Client. WL_SENDDIR Sends files matching the wild card from the Server to the Client. WL_CHECK_SENDFILE Combines the Check File and Send File events into a single event. Compares files on the Server and Client by timestamp and size (Check File). Sends files from the Server to the Client (Send File).

File Transfer Event WL_GETFILE

Description This event retrieves a file from the RemoteWare Client and copies it to the specified RemoteWare Server file name.

Equivalent Session GET file from Client Editor Command Parameter1 This is a zero-terminated text string that specifies the Server path and file name where the file is to be stored. Parameter2 This is a zero-terminated text string that specifies the Client path and name of the file to retrieve from the Client. Where Use WL_ON_NODE for all WL_GETFILE events. Specifying WL_ON_SERVER results in an error. When Use WL_DURING for all WL_GETFILE events. CHAPTER 6 / Worklist Events 181

File Transfer Event WL_GETFILE (Continued)

Options The following options are valid for this event:

WL_NO_OVERWRITE Sends the file to the RemoteWare Server only if the file name does not exist on the Server.

WL_UPDATEFILE Sends the file to the Server only if the Client file has a different date, time, or size.

WL_SEND_NEWER Sends the file to the Server only if the Client file is newer or does not exist on the Server.

WL_SAFE_SEND Sends the file to a temporary file on the Server to prevent data loss during an unsuccessful transfer (the Server renames the file after a successful transfer).

WL_NO_COMPRESS Send the file without compression during the transfer.

WL_CRITICAL Ends the session if the file transfer failed. Critical events with a “no execute” status do not end the session.

WL_CRITICAL_RETRY If this critical event fails, and the session has retries enabled, the Server will reschedule the session. You must also specify WL_CRITICAL for this option to have any effect.

WL_NOT_NEEDED If this option is specified, a completed session may be marked “successful” even if this event fails.

WL_DELETE_AFTER Deletes the Client file after a successful transfer.

Options WL_CONDITIONAL_TRUE (Continued) Executes the event only if the previous event was successful.

WL_CONDITIONAL_FALSE Executes the event only if the previous event failed or did not execute (“no execute” status). 182 RemoteWare API Manual

File Transfer Event WL_GETDIR

Description This event retrieves the specified Client files and stores the files in the specified Server directory. Use this event to retrieve several files of the same name or extension (for example, DOCS.* or *.DAT).

Equivalent Session GET DIRectory files from Client Editor Command Parameter1 This is a zero-terminated text string that specifies the Server directory name. For example, \NODE\MYNODE places the retrieved files in the MYNODE directory. To specify the Client’s directory (\node\), use NULL. Parameter2 This is a zero-terminated text string that specifies the Client path and wild card. This event retrieves all files from the Client that match the wild card specification. Where Use WL_ON_NODE for all WL_GETDIR events. Specifying WL_ON_SERVER results in an error. When Use WL_DURING for all WL_GETDIR events. Options The following options are valid for this event:

WL_NO_OVERWRITE Sends the file to the RemoteWare Server only if the filename does not exist on the Server.

WL_UPDATEFILE Sends the file to the Server only if the Client file has a different date, time, or size. CHAPTER 6 / Worklist Events 183

File Transfer Event WL_GETDIR (Continued)

Options (Continued) WL_SEND_NEWER Sends the file to the Server only if the Client file is newer or does not exist on the Server.

WL_SAFE_SEND Sends the file to a temporary file on the Server to prevent data loss during an unsuccessful transfer (the Server renames the file after a successful transfer).

WL_NO_COMPRESS Send the file without compression during the transfer.

WL_CRITICAL Ends the session if the file transfer failed. Critical events with a “no execute” status do not end the session.

WL_CRITICAL_RETRY If this critical event fails, and the session has retries enabled, the Server will reschedule the session. You must also specify WL_CRITICAL for this option to have any effect.

WL_NOT_NEEDED If this option is specified, a completed session may be marked “successful” even if this event fails.

WL_DELETE_AFTER Deletes the Client file after a successful transfer.

WL_CONDITIONAL_TRUE Executes the event only if the previous event was successful.

WL_CONDITIONAL_FALSE Executes the event only if the previous event failed or did not execute (“no execute” status).

File Transfer Event WL_SENDFILE

Description This event sends the specified Server file to the Client.

Equivalent Session SEND file to Client Editor Command Parameter1 This is a zero-terminated text string that specifies the Server path and file name of the file you want to send to the Client. 184 RemoteWare API Manual

File Transfer Event WL_SENDFILE (Continued)

Parameter2 This is a zero-terminated text string that specifies the Client path and file name where the file is to be stored. Where Use WL_ON_NODE for all WL_SENDFILE events. Specifying WL_ON_SERVER results in an error. When Use WL_DURING for all WL_SENDFILE events. Options The following options are valid for this event:

WL_NO_OVERWRITE Sends the file to the RemoteWare Client only if the file does not exist on the RemoteWare Client.

WL_UPDATEFILE Sends the file to the RemoteWare Client only if the RemoteWare Server file has a different date, time, or size.

WL_SEND_NEWER Sends the file to the Server only if the Client file is newer or does not exist on the Server.

WL_SAFE_SEND Sends the file to a temporary file on the Client to prevent data loss during an unsuccessful transfer (the Client renames the file after a successful transfer).

WL_NO_COMPRESS Sends the file without compression during the transfer.

WL_CRITICAL Ends the session if the file transfer failed. Critical events with a “no execute” status do not end the session.

WL_CRITICAL_RETRY If this critical event fails, and the session has retries enabled, the Server will reschedule the session. You must also specify WL_CRITICAL for this option to have any effect.

WL_NOT_NEEDED If this option is specified, a completed session may be marked “successful” even if this event fails.

WL_DELETE_AFTER Deletes the Server file after a successful transfer. CHAPTER 6 / Worklist Events 185

File Transfer Event WL_SENDFILE (Continued)

Options WL_CONDITIONAL_TRUE (Continued) Executes the event only if the previous event was successful.

WL_CONDITIONAL_FALSE Executes the event only if the previous event failed or did not execute (“no execute” status).

File Transfer Event WL_SENDDIR

Description This event sends the specified Server files to the specified Client directory. Use this event to transfer a group of files with the same name or extension (for example, ACCT.* or *.DOC)

Equivalent Session DIRectory files to Client Editor Command Parameter1 This is a zero-terminated text string that specifies the Server path and wild card. The RemoteWare Server sends all files matching the wild card to the Client. Parameter2 This is a zero-terminated text string that specifies the Client directory where the files are to be stored. Where Use WL_ON_NODE for all WL_SENDDIR events. Specifying WL_ON_SERVER results in an error. When Use WL_DURING for all WL_SENDDIR events. Options The following options are valid for this event:

WL_NO_OVERWRITE Sends the file to the RemoteWare Client only if the file does not exist on the RemoteWare Client.

WL_UPDATEFILE Sends the file to the RemoteWare Client only if the RemoteWare Server file has a different date, time, or size.

WL_SEND_NEWER Sends the file to the Server only if the Client file is newer or does not exist on the Server. 186 RemoteWare API Manual

File Transfer Event WL_SENDDIR (Continued)

Options (Continued) WL_SAFE_SEND Sends each file to a temporary file on the Client to prevent data loss during an unsuccessful transfer (the Client renames the file after a successful transfer).

WL_NO_COMPRESS Sends the file without compression during the transfer.

WL_CRITICAL Ends the session if the file transfer failed. Critical events with a “no execute” status do not end the session.

WL_CRITICAL_RETRY If this critical event fails, and the session has retries enabled, the Server will reschedule the session. You must also specify WL_CRITICAL for this option to have any effect.

WL_NOT_NEEDED If this option is specified, a completed session may be marked “successful” even if this event fails.

WL_DELETE_AFTER Deletes the Server file after a successful transfer.

WL_CONDITIONAL_TRUE Executes the event only if the previous event was successful.

WL_CONDITIONAL_FALSE Executes the event only if the previous event failed or did not execute (“no execute” status).

File Transfer Event WL_CHECK_SENDFILE

Description Combines the Check File and Send File events into a single event. Compares files on the Server and Client by timestamp and size (Check File). Sends files from the Server to the Client (Send File).

Equivalent Session CHECK SEND file(s) to Client Editor Command Parameter1 Server filename. NULL terminated string. Parameter2 Client filename. NULL terminated string. CHAPTER 6 / Worklist Events 187

File Transfer Event WL_CHECK_SENDFILE (Continued)

Parmeter3 Client destination filename, wildcard, or directory. Null terminated string. Where WL_ON_CLIENT When WL_DURING Options The following options are valid for this event:

WL_NO_OVERWRITE Will not copy over an existing file if the name matches that of the destination file.

WL_SAFE_SEND Does not create a destination file until it has been successfully transferred to the RemoteWare Client.

WL_UPDATEFILE Only transfer files with different sizes or dates.

WL_SEND_NEWER Will only send the file if the file on the Server is newer than the file on the Client.

WL_DELETE_AFTER Delete the source (Server) file after the file has been transferred successfully.

WL_NO_COMPRESS Do not use data compression when transferring file.

WL_NOT_NEEDED If this option is specified, a completed session may be marked “successful” even if this event fails.

WL_WO_CRITICAL Ends the work object if the event fails. Critical events with a “no execute”status do not end the session.

WL_CRITICAL Ends the session if the event fails. Critical events with a “no execute” status do not end the session. 188 RemoteWare API Manual

File Transfer Event WL_CHECK_SENDFILE (Continued)

Options WL_CRITICAL_RETRY (Continued) If this critical event fails and the session has retries enabled, the Server will reschedule the session. You must also specify WL_CRITICAL for this option to have any effect.

WL_CONDITIONAL_TRUE Executes the event only if the previous event was successful.

WL_CONDITIONAL_FALSE Executes the event only if the previous event failed or did not execute (“no execute”status).

WL_MAKEPATH Create the necessary destination directories when transferring the file.

WL_INCLSUBDIR If a directory is being transferred, transfer all subdirectories as well.

WL_DURING This event is only valid during a communcation session with a RemoteWare Client. CHAPTER 6 / Worklist Events 189

Operating system events Operating system events execute system-level commands on either the Server or the Client. Operating system events are summarized in the following table: Table 22. Operating system events Function name Description

WL_APPENDFILE Append one binary file to another. WL_ASCII_APPEND Append one ASCII file to another. WL_CHECKDISK Checks the available space on a local, network, or remote drive. WL_CHECKFILE Compares the time, date and size for a Server file and Client file. WL_COPYFILE Copy files on the Server or the same Client (does not transfer the files). WL_DELETEFILE Delete the specified files. WL_DIRECTORY Copies a directory listing to a file. WL_EXECUTE Runs the specified program. WL_FILESTAT Checks to see if the specified file exists. WL_MAKEDIR Creates a new directory. WL_REBOOT_NODE Reboots the Client at the end of a session. WL_REMOVEDIR Deletes an empty directory. WL_RENAMEFILE Changes the name of a file. WL_SETTIME Resets the Client's clock to match the Server's clock. WL_WAIT Wait a certain amount of time for the specified file to exist. WL_CREATE_REG_KEY Creates a registry key. WL_DELETE_REG_KEY Deletes a registry key. WL_DELETE_REG_VALUE Deletes a registry value, but not the registry key. WL_GET_REGISTRY Retrieves a registry value. WL_SET_FILE_ATTRIB Sets the attributes on a file. WL_SET_REGISTRY Sets a registry value. 190 RemoteWare API Manual

Operating System Event WL_APPENDFILE

Description This event adds the contents of one file to the end of another file. Use this command to combine binary files.

Equivalent Session APPEND file(s) to another Editor Command Parameter1 This is a zero-terminated text string that specifies the path and file name of the source file (the file that is added to the end of the other file). Parameter2 This is a zero-terminated text string that specifies either the path and name of the destination file, or a path and wildcard specification for appending multiple files. Where Use WL_ON_NODE or WL_ON_SERVER. When If Where is set to WL_ON_SERVER, then WL_BEFORE, WL_DURING, or WL_AFTER is valid. If Where is set to WL_ON_NODE, then only WL_DURING is valid. Options The following options are valid for this event:

WL_CRITICAL Ends the session if the file transfer failed. Critical events with a “no execute” status do not end the session.

WL_CRITICAL_RETRY If this critical event fails, and the session has retries enabled, the Server will reschedule the session. You must also specify WL_CRITICAL for this option to have any effect.

WL_NOT_NEEDED If this option is specified, a completed session may be marked “successful” even if this event fails.

WL_DELETE_AFTER Deletes the source file after a successful transfer.

WL_CONDITIONAL_TRUE Executes the event only if the previous event was successful.

WL_CONDITIONAL_FALSE Executes the event only if the previous event failed or did not execute (“no execute” status). CHAPTER 6 / Worklist Events 191

Operating System Event WL_ASCII_APPEND

Description This event adds the contents of one file to the end of another file. Use this command to combine binary files.

Equivalent Session APPEND file(s) to another Editor Command Parameter1 This is a zero-terminated text string that specifies the path and file name of the source file (the file that is added to the end of the other file). Parameter2 This is a zero-terminated text string that specifies either the path and name of the destination file, or a path and wildcard specification for appending multiple files. Where Use WL_ON_NODE or WL_ON_SERVER. When If Where is set to WL_ON_SERVER, then WL_BEFORE, WL_DURING, or WL_AFTER is valid. If Where is set to WL_ON_NODE, then only WL_DURING is valid. Options The following options are valid for this event:

WL_CRITICAL Ends the session if the file transfer failed. Critical events with a “no execute” status do not end the session.

WL_CRITICAL_RETRY If this critical event fails, and the session has retries enabled, the Server will reschedule the session. You must also specify WL_CRITICAL for this option to have any effect.

WL_NOT_NEEDED If this option is specified, a completed session may be marked “successful” even if this event fails.

WL_DELETE_AFTER Deletes the Client file after a successful transfer.

WL_CONDITIONAL_TRUE Executes the event only if the previous event was successful.

WL_CONDITIONAL_FALSE Executes the event only if the previous event failed or did not execute (“no execute” status). 192 RemoteWare API Manual

Operating System Event WL_CHECKDISK Description This event determines the available storage space on a local, network, or remote drive.

Equivalent Session CHECK DISK drive Editor Command Parameter1 This is a zero-terminated text string that specifies the drive letter of the drive to check, where a colon “:” is optional. If this parameter is NULL, then the default Server Data or Client Install drive is assumed. Parameter2 NULL Where Use WL_ON_NODE or WL_ON_SERVER. When If Where is set to WL_ON_SERVER, then WL_BEFORE, WL_DURING, or WL_AFTER is valid. If Where is set to WL_ON_NODE, then only WL_DURING is valid. Options The following options are valid for this event:

WL_CRITICAL Ends the session if the file transfer failed. Critical events with a “no execute” status do not end the session.

WL_CRITICAL_RETRY If this critical event fails, and the session has retries enabled, the Server will reschedule the session. You must also specify WL_CRITICAL for this option to have any effect.

WL_NOT_NEEDED If this option is specified, a completed session may be marked “successful” even if this event fails.

WL_CONDITIONAL_TRUE Executes the event only if the previous event was successful.

WL_CONDITIONAL_FALSE Executes the event only if the previous event failed or did not execute (“no execute” status). CHAPTER 6 / Worklist Events 193

Operating System Event WL_CHECKFILE Description This event compares the time, date and size for a RemoteWare Server file and RemoteWare Client file. It is often used to test the version of a file before a transfer event.

Equivalent Session CHECK FILE ServerFile ClientFile Editor Command Parameter1 This is a zero-terminated text string that specifies the Server path and file name of the file you want to check against. Parameter2 This is a zero-terminated text string that specifies the Client path and file name where the file to be checked is stored. Where Use WL_ON_NODE for all WL_CHECKFILE events. Specifying WL_ON_SERVER results in an error. When Use WL_DURING for all WL_CHECKFILE events. 194 RemoteWare API Manual

Operating System Event WL_CHECKFILE (Continued)

Options The following options are valid for this event:

WL_NO_OVERWRITE Sends the file to the RemoteWare Client only if the file does not exist on the RemoteWare Client.

WL_UPDATEFILE Sends the file to the RemoteWare Client only if the RemoteWare Server file has a different date, time, or size.

WL_SAFE_SEND Sends the file to a temporary file on the Client to prevent data loss during an unsuccessful transfer (the Client renames the file after a successful transfer).

WL_NO_COMPRESS Sends the file without compression during the transfer.

WL_CRITICAL Ends the session if the file transfer failed. Critical events with a “no execute” status do not end the session.

WL_CRITICAL_RETRY If this critical event fails, and the session has retries enabled, the Server will reschedule the session. You must also specify WL_CRITICAL for this option to have any effect.

WL_NOT_NEEDED If this option is specified, a completed session may be marked “successful” even if this event fails.

WL_DELETE_AFTER Deletes the Server file after a successful transfer.

WL_CONDITIONAL_TRUE Executes the event only if the previous event was successful.

WL_CONDITIONAL_FALSE Executes the event only if the previous event failed or did not execute (“no execute” status). CHAPTER 6 / Worklist Events 195

Operating System Event WL_COPYFILE Description This event copies the specified file or files in the source directory to the destination directory.

Equivalent Session COPY file(s) Editor Command Parameter1 This is a zero-terminated text string that specifies the path and file name of the file to copy, or a path and wildcard of multiple files to copy. Parameter2 This is a zero-terminated text string that specifies the file name, directory, or wildcard where the files are to be copied. Where Use WL_ON_NODE or WL_ON_SERVER. When If Where is set to WL_ON_SERVER, then WL_BEFORE, WL_DURING, or WL_AFTER is valid. If Where is set to WL_ON_NODE, then only WL_DURING is valid. Options The following options are valid for this event:

WL_CRITICAL Ends the session if the file transfer failed. Critical events with a “no execute” status do not end the session.

WL_CRITICAL_RETRY If this critical event fails, and the session has retries enabled, the Server will reschedule the session. You must also specify WL_CRITICAL for this option to have any effect.

WL_NOT_NEEDED If this option is specified, a completed session may be marked “successful” even if this event fails.

WL_CONDITIONAL_TRUE Executes the event only if the previous event was successful.

WL_CONDITIONAL_FALSE Executes the event only if the previous event failed or did not execute (“no execute” status). 196 RemoteWare API Manual

Operating System Event WL_DELETEFILE Description This event deletes the specified file or files.

Equivalent Session DELETE file(s) Editor Command Parameter1 This is a zero-terminated text string that specifies the path and file name of a single file to delete, or the path and wildcard of multiple files to delete. Parameter2 NULL Where Use WL_ON_NODE or WL_ON_SERVER. When If Where is set to WL_ON_SERVER, then WL_BEFORE, WL_DURING, or WL_AFTER is valid. If Where is set to WL_ON_NODE, then only WL_DURING is valid. Options The following options are valid for this event:

WL_CRITICAL Ends the session if the file transfer failed. Critical events with a “no execute” status do not end the session.

WL_CRITICAL_RETRY If this critical event fails, and the session has retries enabled, the Server will reschedule the session. You must also specify WL_CRITICAL for this option to have any effect.

WL_NOT_NEEDED If this option is specified, a completed session may be marked “successful” even if this event fails.

WL_CONDITIONAL_TRUE Executes the event only if the previous event was successful.

WL_CONDITIONAL_FALSE Executes the event only if the previous event failed or did not execute (“no execute” status). CHAPTER 6 / Worklist Events 197

Operating System Event WL_DIRECTORY Description This event copies a listing of the specified directory to a file. If the directory is empty or does not exist, this event fails.

Also, this event uses the local directory command (for example, DIR for DOS) to generate the directory listing.

Equivalent Session DIRectory listing Editor Command Parameter1 This is a zero-terminated text string that specifies the path and file name where the directory listing is to be stored. Parameter2 This is a zero-terminated text string that specifies the Client path and wildcard of the files to list. Where Use WL_ON_NODE or WL_ON_SERVER. When If Where is set to WL_ON_SERVER, then WL_BEFORE, WL_DURING, or WL_AFTER is valid. If Where is set to WL_ON_NODE, then only WL_DURING is valid. Options The following options are valid for this event:

WL_CRITICAL Ends the session if the file transfer failed. Critical events with a “no execute” status do not end the session.

WL_CRITICAL_RETRY If this critical event fails, and the session has retries enabled, the Server will reschedule the session. You must also specify WL_CRITICAL for this option to have any effect.

WL_NOT_NEEDED If this option is specified, a completed session may be marked “successful” even if this event fails.

WL_CONDITIONAL_TRUE Executes the event only if the previous event was successful.

WL_CONDITIONAL_FALSE Executes the event only if the previous event failed or did not execute (“no execute” status). 198 RemoteWare API Manual

Operating System Event WL_EXECUTE Description This event executes the specified command line to run an application program. This event does not track the status of the program.

Also, this event does not apply to DOS Clients since these systems do not have multitasking capabilities.

Equivalent Session EXECUTE program Editor Command Parameter1 This is a zero-terminated text string that specifies the program’s startup command, including options, arguments, or parameters.

If you run this event from the Server, you can use the placeholder as a command line parameter; this event substitutes the Client name and passes it to the program. Parameter2 NULL Where Use WL_ON_NODE or WL_ON_SERVER. When If Where is set to WL_ON_SERVER, then WL_BEFORE, WL_DURING, or WL_AFTER is valid. If Where is set to WL_ON_NODE, then only WL_DURING is valid. Options The following options are valid for this event:

WL_NOT_NEEDED If this option is specified, a completed session may be marked “successful” even if this event fails.

WL_CONDITIONAL_TRUE Executes the event only if the previous event was successful.

WL_CONDITIONAL_FALSE Executes the event only if the previous event failed or did not execute (“no execute” status). CHAPTER 6 / Worklist Events 199

Operating System Event WL_FILESTAT Description This event checks to see whether the specified file exists on the Client or the Server.

Equivalent Session get FILE STATUS Editor Command Parameter1 This is a zero-terminated text string that specifies the path and file name of the file to check. Parameter2 NULL Where Use WL_ON_NODE or WL_ON_SERVER. When If Where is set to WL_ON_SERVER, then WL_BEFORE, WL_DURING, or WL_AFTER is valid. If Where is set to WL_ON_NODE, then only WL_DURING is valid. Options The following options are valid for this event:

WL_CRITICAL Ends the session if the file transfer failed. Critical events with a “no execute” status do not end the session.

WL_CRITICAL_RETRY If this critical event fails, and the session has retries enabled, the Server will reschedule the session. You must also specify WL_CRITICAL for this option to have any effect.

WL_NOT_NEEDED If this option is specified, a completed session may be marked “successful” even if this event fails.

WL_CONDITIONAL_TRUE Executes the event only if the previous event was successful.

WL_CONDITIONAL_FALSE Executes the event only if the previous event failed or did not execute (“no execute” status). 200 RemoteWare API Manual

Operating System Event WL_MAKEDIR Description This event creates a new directory on the Client or Server.

Equivalent Session MAKE DIRectory Editor Command Parameter1 This is a zero-terminated text string that specifies the path and name of the new directory. Parameter2 NULL Where Use WL_ON_NODE or WL_ON_SERVER. When If Where is set to WL_ON_SERVER, then WL_BEFORE, WL_DURING, or WL_AFTER is valid. If Where is set to WL_ON_NODE, then only WL_DURING is valid. Options The following options are valid for this event:

WL_CRITICAL Ends the session if the file transfer failed. Critical events with a “no execute” status do not end the session.

WL_CRITICAL_RETRY If this critical event fails, and the session has retries enabled, the Server will reschedule the session. You must also specify WL_CRITICAL for this option to have any effect.

WL_NOT_NEEDED If this option is specified, a completed session may be marked “successful” even if this event fails.

WL_CONDITIONAL_TRUE Executes the event only if the previous event was successful.

WL_CONDITIONAL_FALSE Executes the event only if the previous event failed or did not execute (“no execute” status). CHAPTER 6 / Worklist Events 201

Operating System Event WL_REBOOT_NODE Description This event reboots the Client after disconnecting from the RemoteWare Server.

Note: This event does not apply to OS/2 or Windows 3.x Clients.

Equivalent Session REBOOT Client at the end of session Editor Command Parameter1 NULL Parameter2 NULL Where Use WL_ON_NODE for all WL_REBOOT_NODE events. Specifying WL_ON_SERVER results in an error. When Use WL_DURING for all WL_REBOOT_NODE events. Options The following options are valid for this event:

WL_NOT_NEEDED If this option is specified, a completed session may be marked “successful” even if this event fails.

WL_CONDITIONAL_TRUE Executes the event only if the previous event was successful.

WL_CONDITIONAL_FALSE Executes the event only if the previous event failed or did not execute (“no execute” status).

Operating System Event WL_REMOVEDIR Description This event deletes an empty directory on the Client or Server.

Equivalent Session REMOVE DIRectory Editor Command Parameter1 This is a zero-terminated text string that specifies the name of the directory to be deleted. Parameter2 NULL Where Use WL_ON_NODE or WL_ON_SERVER. 202 RemoteWare API Manual

Operating System Event WL_REMOVEDIR (Continued)

When If Where is set to WL_ON_SERVER, then WL_BEFORE, WL_DURING, or WL_AFTER is valid. If Where is set to WL_ON_NODE, then only WL_DURING is valid. Options The following options are valid for this event:

WL_CRITICAL Ends the session if the file transfer failed. Critical events with a “no execute” status do not end the session.

WL_CRITICAL_RETRY If this critical event fails, and the session has retries enabled, the Server will reschedule the session. You must also specify WL_CRITICAL for this option to have any effect.

WL_NOT_NEEDED If this option is specified, a completed session may be marked “successful” even if this event fails.

WL_CONDITIONAL_TRUE Executes the event only if the previous event was successful.

WL_CONDITIONAL_FALSE Executes the event only if the previous event failed or did not execute (“no execute” status).

Operating System Event WL_RENAMEFILE Description This event changes the name of a file or group of files on the Client or the Server.

Equivalent Session RENAME file(s) Editor Command Parameter1 This is a zero-terminated text string that specifies the path and file name of the file you want to rename, or the path and wildcard to specify multiple files. Parameter2 This is a zero-terminated text string that specifies the path and new file name, or path and wildcard. If you specify a wildcard in Parameter2, you must also specify a wildcard in Parameter1. Where Use WL_ON_NODE or WL_ON_SERVER. CHAPTER 6 / Worklist Events 203

Operating System Event WL_RENAMEFILE (Continued)

When If Where is set to WL_ON_SERVER, then WL_BEFORE, WL_DURING, or WL_AFTER is valid. If Where is set to WL_ON_NODE, then only WL_DURING is valid. Options The following options are valid for this event:

WL_CRITICAL Ends the session if the file transfer failed. Critical events with a “no execute” status do not end the session.

WL_CRITICAL_RETRY If this critical event fails, and the session has retries enabled, the Server will reschedule the session. You must also specify WL_CRITICAL for this option to have any effect.

WL_NOT_NEEDED If this option is specified, a completed session may be marked “successful” even if this event fails.

WL_CONDITIONAL_TRUE Executes the event only if the previous event was successful.

WL_CONDITIONAL_FALSE Executes the event only if the previous event failed or did not execute (“no execute” status).

Operating System Event WL_SETTIME Description This event resets the Client clock to match the clock on the RemoteWare Server.

Equivalent Session SET Client TIME Editor Command Parameter1 NULL Parameter2 NULL Where Use WL_ON_NODE for all WL_SETTIME events. Specifying WL_ON_SERVER results in an error. When Use WL_DURING for all WL_SETTIME events. 204 RemoteWare API Manual

Operating System Event WL_WAIT Description This event waits for a file to exist within a specified amount of time. If the file is found, the event is successful. If the wait timer expires, the event fails. In any case, the worklist continues to the next event.

If you are writing data to the file that a worklist is waiting for, your program should write the data to a temporary file and rename the file when complete. This prevents problems with incomplete files.

Equivalent Session WAIT for file to exist Editor Command Parameter1 This is a zero-terminated text string that specifies the path and name of the file you want to wait for. Parameter2 This is a zero-terminated string that specifies the time, in seconds, you want to wait before timing out. Where Use WL_ON_NODE or WL_ON_SERVER. When If Where is set to WL_ON_SERVER, then WL_BEFORE, WL_DURING, or WL_AFTER is valid. If Where is set to WL_ON_NODE, then only WL_DURING is valid. Options The following options are valid for this event:

WL_CRITICAL Ends the session if the file transfer failed. Critical events with a “no execute” status do not end the session.

WL_CRITICAL_RETRY If this critical event fails, and the session has retries enabled, the Server will reschedule the session. You must also specify WL_CRITICAL for this option to have any effect.

WL_NOT_NEEDED If this option is specified, a completed session may be marked “successful” even if this event fails.

WL_DELETE_AFTER Deletes the Server file after a successful transfer.

WL_CONDITIONAL_TRUE Executes the event only if the previous event was successful.

WL_CONDITIONAL_FALSE Executes the event only if the previous event failed or did not execute (“no execute” status). CHAPTER 6 / Worklist Events 205

Operating System Event WL_CREATE_REG_KEY

Description This event creates a registry key.

Equivalent Session CREATE REGISTRY KEY Editor Command Parameter1 Registry key name. NULL terminated string.

Example: “HKEY_CURRENT_USER\Key” Where WL_ON_SERVER, WL_ON_CLIENT When WL_BEFORE, WL_DURING, WL_AFTER Options The following options are valid for this event:

WL_NOT_NEEDED If this option is specified, a completed session may be marked “successful” even if this event fails.

WL_WO_CRITICAL Ends the work object if the event fails. Critical events with a “no execute” status do not end the session.

WL_CRITICAL Ends the session if the event fails. Critical events with a “no execute” status do not end the session.

WL_CRITICAL_RETRY If this critical event fails and the session has retries enabled, the Server will reschedule the session. You must also specify WL_CRITICAL for this option to have any effect.

WL_CONDITIONAL_TRUE Executes the event only if the previous event was successful.

WL_CONDITIONAL_FALSE Executes the event only if the previous event failed or did not execute (“no execute” status).

WL_MAKEPATH Create the necessary registry keys and subkeys.

WL_BEFORE, WL_DURING, WL_AFTER If this event will be used in a Process Only session, use WL_BEFORE. 206 RemoteWare API Manual

Operating System Event WL_DELETE_REG_KEY

Description This event deletes a registry key.

Equivalent Session DELETE REGISTRY KEY Editor Command Parameter1 Registry key name. NULL terminated string.

Example: “HKEY_CURRENT_USER\Key” Where WL_ON_SERVER, WL_ON_CLIENT When WL_BEFORE, WL_DURING, WL_AFTER Options The following options are valid for this event:

WL_NOT_NEEDED If this option is specified, a completed session may be marked “successful” even if this event fails.

WL_WO_CRITICAL Ends the work object if the event fails. Critical events with a “no execute” status do not end the session.

WL_CRITICAL Ends the session if the event fails. Critical events with a “no execute” status do not end the session.

WL_CRITICAL_RETRY If this critical event fails and the session has retries enabled, the Server will reschedule the session. You must also specify WL_CRITICAL for this option to have any effect.

WL_CONDITIONAL_TRUE Executes the event only if the previous event was successful.

WL_CONDITIONAL_FALSE Executes the event only if the previous event failed or did not execute (“no execute” status).

WL_BEFORE, WL_DURING, WL_AFTER If this event will be used in a Process Only session, use WL_BEFORE. CHAPTER 6 / Worklist Events 207

Operating System Event WL_DELETE_REG_VALUE

Description This event deletes a registry value, but not the registry key.

Equivalent Session DELETE REGISTRY VALUE Editor Command Parameter1 Registry value to delete. NULL terminated string.

Example: “HKEY_CURRENT_USER\Key\Value” Where WL_ON_SERVER, WL_ON_CLIENT When WL_BEFORE, WL_DURING, WL_AFTER Options The following options are valid for this event:

WL_NOT_NEEDED If this option is specified, a completed session may be marked “successful” even if this event fails.

WL_WO_CRITICAL Ends the work object if the event fails. Critical events with a “no execute” status do not end the session.

WL_CRITICAL Ends the session if the event fails. Critical events with a “no execute” status do not end the session.

WL_CRITICAL_RETRY If this critical event fails and the session has retries enabled, the Server will reschedule the session. You must also specify WL_CRITICAL for this option to have any effect.

WL_CONDITIONAL_TRUE Executes the event only if the previous event was successful.

WL_CONDITIONAL_FALSE Executes the event only if the previous event failed or did not execute (“no execute” status).

WL_BEFORE, WL_DURING, WL_AFTER If this event will be used in a Process Only session, use WL_BEFORE. 208 RemoteWare API Manual

Operating System Event WL_GET_REGISTRY

Description This event retrieves a registry value.

Equivalent Session GET REGISTRY Editor Command Parameter1 RemoteWare session variable to store the retrieved registry value. NULL terminated string.

Example: <%RegistryValue>” Parameter2 Registry value to be retrieved. NULL terminated string.

Example: “HKEY_CURRENT_USER\Key\Value” Where WL_ON_SERVER, WL_ON_CLIENT When WL_BEFORE, WL_DURING, WL_AFTER Options The following options are valid for this event:

WL_NOT_NEEDED If this option is specified, a completed session may be marked “successful” even if this event fails.

WL_WO_CRITICAL Ends the work object if the event fails. Critical events with a “no execute” status do not end the session.

WL_CRITICAL Ends the session if the event fails. Critical events with a “no execute” status do not end the session.

WL_CRITICAL_RETRY If this critical event fails and the session has retries enabled, the Server will reschedule the session. You must also specify WL_CRITICAL for this option to have any effect.

WL_CONDITIONAL_TRUE Executes the event only if the previous event was successful.

WL_CONDITIONAL_FALSE Executes the event only if the previous event failed or did not execute (“no execute” status).

WL_BEFORE, WL_DURING, WL_AFTER If this event will be used in a Process Only session, use WL_BEFORE. CHAPTER 6 / Worklist Events 209

Operating System Event WL_SET_FILE_ATTRIB

Description This event sets the attributes on a file.

Equivalent Session SET file ATTRIButes Editor Command Parameter1 Filename. NULL terminated string. Parameter2 The file attributes to be set. The following are valid values:

WL_ATTRIB_RO WL_ATTRIB_HIDDEN WL_ATTRIB_SYSTEM WL_ATTRIB_NORMAL WL_ATTRIB_ARCHIVE

If the file exists on a UNIX Operating System, the following attributes are also valid:

WL_ATTRIB_WREAD WL_ATTRIB_WWRITE WL_ATTRIB_WEXECUTE WL_ATTRIB_GREAD WL_ATTRIB_GWRITE WL_ATTRIB_GEXECUTE WL_ATTRIB_UREAD WL_ATTRIB_UWRITE WL_ATTRIB_UEXECUTE

Multiple attributes may be set at once, must be separated by a space. Where WL_ON_SERVER, WL_ON_CLIENT When WL_BEFORE, WL_DURING, WL_AFTER Options The following options are valid for this event:

WL_NOT_NEEDED If this option is specified, a completed session may be marked “successful” even if this event fails.

WL_WO_CRITICAL Ends the work object if the event fails. Critical events with a “no execute” status do not end the session. 210 RemoteWare API Manual

Operating System Event WL_SET_FILE_ATTRIB (Continued)

Options WL_CRITICAL (Continued) Ends the session if the event fails. Critical events with a “no execute” status do not end the session.

WL_CRITICAL_RETRY If this critical event fails and the session has retries enabled, the Server will reschedule the session. You must also specify WL_CRITICAL for this option to have any effect.

WL_CONDITIONAL_TRUE Executes the event only if the previous event was successful.

WL_CONDITIONAL_FALSE Executes the event only if the previous event failed or did not execute (“no execute” status).

WL_INCLSUBDIR If a directory is being transferred, transfer all subdirectories as well.

WL_BEFORE, WL_DURING, WL_AFTER If this event will be used in a Process Only session, use WL_BEFORE.

Operating System Event WL_SET_REGISTRY

Description This event sets a registry value.

Equivalent Session SET REGISTRY key VALUE Editor Command Parameter1 Registry key. NULL terminated string.

Example: “HKEY_CURRENT_USER\Key\Value” Parameter2 Variable or Value. NULL terminated string.

Examples: <%RegistryValue> or “XcelleNet” Parameter3 Value type. NULL terminated string, valid values are STRING or DWORD. Where WL_ON_SERVER, WL_ON_CLIENT When WL_BEFORE, WL_DURING, WL_AFTER CHAPTER 6 / Worklist Events 211

Operating System Event WL_SET_REGISTRY (Continued)

Options The following options are valid for this event:

WL_NOT_NEEDED If this option is specified, a completed session may be marked “successful” even if this event fails.

WL_WO_CRITICAL Ends the work object if the event fails. Critical events with a “no execute” status do not end the session.

WL_CRITICAL Ends the session if the event fails. Critical events with a “no execute” status do not end the session.

WL_CRITICAL_RETRY If this critical event fails and the session has retries enabled, the Server will reschedule the session. You must also specify WL_CRITICAL for this option to have any effect.

WL_CONDITIONAL_TRUE Executes the event only if the previous event was successful.

WL_CONDITIONAL_FALSE Executes the event only if the previous event failed or did not execute (“no execute” status).

WL_MAKEPATH Create the necessary destination directories when transferring the file.

WL_BEFORE, WL_DURING, WL_AFTER If this event will be used in a Process Only session, use WL_BEFORE. 212 RemoteWare API Manual

Session control events Session control events consist of conditional statements and events that override set parameters. Session control events are summarized in the following table: Table 23. Session control events Function name Description

WL_COMMENT Adds a non-executing comment to the session. WL_ELSE_IF Specifies a group of events to execute if the IF condition is not satisfied. WL_END_IF Specifies the end of an IF...ELSE IF...END IF block. WL_QUOTA Begins a Quota block. WL_END_QUOTA Ends a quota block of events. WL_END_REPEAT Specifies the end of a REPEAT IF... block. WL_END_SESSION Stops a session and disconnects the RemoteWare Client. WL_END_WORKOBJ Terminates the currently executing RemoteWare work object. WL_IF_TRUE Specifies a group of events to execute if the previous event was successful. WL_IF_FALSE Specifies a group of events to execute if the previous event was not successful (either “failed” or “no execute”). WL_REPEAT_IF_TRUE Specifies a group of events to repeat as long as a particular event is successful. WL_REPEAT_IF_FALSE Specifies a group of events to repeat as long as a particular event is not successful (either “failed” or “no execute”). WL_READ_VAR_FILE Reads a value from an INI (variable) text file. WL_WRITE_VAR_FILE Writes a value to an INI (variable) text file. WL_DELETE_VAR_FILE Deletes a variable from an INI (variable) text file. WL_GROUP_TEST Tests if a Client belongs to a particular group. WL_SET_VARIABLE Creates a user defined variable for use elsewhere in a session. WL_TEST_VARIABLE Compares a predefined or user defined variable against a known value. CHAPTER 6 / Worklist Events 213

Session Control Event WL_COMMENT Description This event lets you add comments to a session. The comment does not affect the execution of the session.

Equivalent Session COMMENT Editor Command Parameter1 This is a zero-terminated text string that specifies the text to be displayed in the session event list. The comment string can up to 251 characters long. The session event list displays only the first line of the comment. Parameter2 NULL Where NULL (Comments are not executed.) When NULL (Comments are not executed.)

Session Control Event WL_ELSE_IF Description This conditional event begins a block of events to execute if the preceding IF condition is not satisfied.

Equivalent Session ELSE IF Editor Command Parameter1 NULL Parameter2 NULL Where NULL (Comments are not executed.) When NULL (Comments are not executed.) 214 RemoteWare API Manual

Session Control Event WL_END_IF Description This is a conditional event that marks the end of an IF...ELSE IF...END IF block.

Equivalent Session END IF Editor Command Parameter1 NULL Parameter2 NULL Where NULL (Comments are not executed.) When NULL (Comments are not executed.)

Operating System Event WL_QUOTA

Description This event begins a Quota block.

Equivalent Session Begin QUOTA block Editor Command Parameter1 Data limit in kilobytes. Parameter2 Time limit. Where WL_ON_SERVER When WL_BEFORE, WL_DURING, WL_AFTER CHAPTER 6 / Worklist Events 215

Operating System Event WL_QUOTA (Continued)

Options The following options are valid for this event:

WL_NOT_NEEDED If this option is specified, a completed session may be marked “successful” even if this event fails.

WL_WO_CRITICAL Ends the work object if the event fails. Critical events with a “no execute” status do not end the session.

WL_CRITICAL Ends the session if the event fails. Critical events with a “no execute” status do not end the session.

WL_CRITICAL_RETRY If this critical event fails and the session has retries enabled, the Server will reschedule the session. You must also specify WL_CRITICAL for this option to have any effect.

Options WL_CONDITIONAL_TRUE (Continued) Executes the event only if the previous event was successful.

WL_CONDITIONAL_FALSE Executes the event only if the previous event failed or did not execute (“no execute” status).

WL_BEFORE, WL_DURING, WL_AFTER If this event will be used in a Process Only session, use WL_BEFORE.

Operating System Event WL_END_QUOTA

Description This event ends a Quota block of events.

Equivalent Session END QUOTA block Editor Command Parameter1 N/A Where N/A When N/A 216 RemoteWare API Manual

Session Control Event WL_END_REPEAT Description This event marks the end of a REPEAT IF... block.

Note: All events in a Repeat block must be During events.

Equivalent Session REPEAT IF Editor Command Parameter1 NULL Parameter2 NULL Where NULL (Not executed.) When NULL (Not executed.)

Session Control Event WL_END_SESSION Description This event stops the session and disconnects the communications line.

Sessions that end with WL_END_SESSION are considered either successful or complete.

Equivalent Session END SESSION Editor Command Parameter1 NULL Parameter2 NULL Where Use WL_ON_SERVER for all WL_END_SESSION events. Specifying WL_ON_NODE results in an error. When WL_BEFORE, WL_DURING, or WL_AFTER is valid. However, if this worklist will be used in a Process Only session, use WL_BEFORE. CHAPTER 6 / Worklist Events 217

Session Control Event WL_END_SESSION (Continued)

Options The following options are valid for this event:

WL_NOT_NEEDED If this option is specified, a completed session may be marked “successful” even if this event fails.

WL_CONDITIONAL_TRUE Executes the event only if the previous event was successful.

WL_CONDITIONAL_FALSE Executes the event only if the previous event failed or did not execute (“no execute” status)

Session Control Event WL_END_WORKOBJ Description This event terminates the currently executing RemoteWare work object.

Equivalent Session END WORK OBJect Editor Command Parameter1 N/A Where WL_ON_SERVER When WL_BEFORE, WL_DURING, WL_AFTER . 218 RemoteWare API Manual

Session Control Event WL_END_WORKOBJ (Continued)

Options The following options are valid for this event:

WL_NOT_NEEDED If this option is specified, a completed session may be marked “successful” even if this event fails.

WL_CONDITIONAL_TRUE Executes the event only if the previous event was successful.

WL_CONDITIONAL_FALSE Executes the event only if the previous event failed or did not execute (“no execute” status)

WL_BEFORE, WL_DURING, WL_AFTER If this event will be used in a Process Only session, use WL_BEFORE.

Session Control Event WL_IF_TRUE Description This event specifies a group of events to execute if the previous event was TRUE. This is useful for executing multiple events based on the result of an event. A block of events begins with the WL_IF_TRUE and ends with a WL_END_IF.

Equivalent Session IF previous event TRUE Editor Command Parameter1 NULL Parameter2 NULL Where NULL (Not executed.) When NULL (Not executed.) CHAPTER 6 / Worklist Events 219

Session Control Event WL_IF_FALSE Description This event specifies a group of events to execute if the previous event was FALSE. This is useful for executing multiple events based on the result of an event. A block of events begins with the WL_IF_FALSE and ends with a WL_END_IF.

Equivalent Session IF previous event FALSE Editor Command Parameter1 NULL Parameter2 NULL Where NULL (Not executed.) When NULL (Not executed.)

Session Control Event WL_REPEAT_IF_TRUE Description This event conditionally repeats a group of events. This is useful for repeating multiple events until a particular event fails.

The Repeat block begins with the WL_REPEAT_IF_TRUE and ends with a WL_END_REPEAT. If the previous event is TRUE, the entire block of events is executed at least once. After each pass through the Repeat block, the result of the last event in the block determines if the loop repeats or control moves to the next event after the WL_END_REPEAT. However, the loop will also be terminated (after completing the current pass through the block) if any one of three optional limits is reached. These optional limits are an execution timeout, an inactivity timeout, and a maximum number of repeats.

Note: All events in the Repeat block must be During events.

Equivalent Session REPeat IF previous event TRUE Editor Command 220 RemoteWare API Manual

Session Control Event WL_REPEAT_IF_TRUE (Continued)

Special To add a WL_REPEAT_IF_TRUE event with the 16-bit Client API, Consideration use the RWNWorklistAction() function. Before calling the function, assign appropriate values to the szParam1, szParam1, and usReferenceCount members of the RWWORKLIST structure (as described below).

Note: You cannot add a WL_REPEAT_IF_TRUE event with the 16-bit Client API using the RWNWorklistAdd() function (because that function does not use the RWWORKLIST structure). usReferenceCount This is the maximum number of times to execute the repeat loop, assigned as an integer from 0 to 99, where 0 signifies no limit on the number of repeats. szParam1 This the maximum time to execute the Repeat loop before timing out (i.e., the Execution Timeout value). This is a zero-terminated string that specifies the time in seconds. For example, 2:30 (2 minutes, 30 seconds) is 150 seconds, which would be assigned as the string “150”. Valid values are from “0” to “3599”, where “0” signifies no execution timeout. szParam2 This is the maximum period of inactivity that can occur in the Repeat loop before timing out (i.e. the Inactivity Timeout value). This is a zero-terminated string that specifies the time in seconds. For example, 2:30 (2 minutes, 30 seconds) is 150 seconds, which would be assigned as the string “150”. Valid values are from “0” to “3599”, where “0” signifies no inactivity timeout. Where NULL (Not executed.) When NULL (Not executed.) CHAPTER 6 / Worklist Events 221

Session Control Event WL_REPEAT_IF_FALSE Description This event conditionally repeats a group of events. This is useful for repeating multiple events until a particular event succeeds.

A Repeat block begins with WL_REPEAT_IF_FALSE and ends with WL_END_REPEAT. If the previous event is FALSE, the entire block of events is executed at least once. After each pass through the Repeat block, the result of the last event in the block determines if the loop repeats or control moves to the next event after the WL_END_REPEAT. However, the loop will also be terminated (after completeing the current pass through the block) if any one of three optional limits is reached. These optional limits are an execution timeout, an inactivity timeout, and a maximum number of repeats.

Note: All events in the Repeat block must be During events.

Equivalent Session REPeat IF previous event FALSE Editor Command Special To add a WL_REPEAT_IF_FALSE event with the 16-bit Client API, Consideration use the RWNWorklistAction() function. Before calling the function, assign appropriate values to the szParam1, szParam1, and usReferenceCount members of the RWWORKLIST structure (as described below).

Note: You cannot add a WL_REPEAT_IF_FALSE event with the 16-bit Client API using the RWNWorklistAdd() function (because that function does not use the RWWORKLIST structure). usReferenceCount This is the maximum number of times to execute the repeat loop, assigned as an integer from 0 to 99, where 0 signifies no limit on the number of repeats. szParam1 This the maximum time to execute the Repeat loop before timing out (i.e. the Execution Timeout value). This is a zero-terminated string that specifies the time in seconds. For example, 2:30 (2 minutes, 30 seconds) is 150 seconds, which would be assigned as the string “150”. Valid values range from “0” to “3599”, where “0” signifies no execution timeout. szParam2 This is the maximum period of inactivity that can occur in the Repeat loop before timing out (i.e. the Inactivity Timeout value). This is a zero-terminated string that specifies the time in seconds. For example, 2:30 (2 minutes, 30 seconds) is 150 seconds, which would be assigned as the string “150”. Valid values range from “0” to “3599”, where “0” signifies no inactivity timeout. 222 RemoteWare API Manual

Session Control Event WL_REPEAT_IF_FALSE (Continued)

Where NULL (Not executed.) When NULL (Not executed.)

Operating System Event WL_READ_VAR_FILE

Description This event reads a value from an INI (variable) text file.

Equivalent Session READ INI FILE Editor Command Parameter1 Filename. NULL terminated string. Parameter2 User variable name. NULL terminated string.

Example: <%[Section].VariableName> Where WL_ON_SERVER, WL_ON_CLIENT When WL_BEFORE, WL_DURING, WL_AFTER Options The following options are valid for this event:

WL_NOT_NEEDED If this option is specified, a completed session may be marked “successful” even if this event fails.

WL_WO_CRITICAL Ends the work object if the event fails. Critical events with a “no execute” status do not end the session.

WL_CRITICAL Ends the session if the event fails. Critical events with a “no execute” status do not end the session. CHAPTER 6 / Worklist Events 223

Operating System Event WL_READ_VAR_FILE (Continued)

Options WL_CRITICAL_RETRY (Continued) If this critical event fails and the session has retries enabled, the Server will reschedule the session. You must also specify WL_CRITICAL for this option to have any effect.

WL_CONDITIONAL_TRUE Executes the event only if the previous event was successful.

WL_CONDITIONAL_FALSE Executes the event only if the previous event failed or did not execute (“no execute” status).

WL_BEFORE, WL_DURING, WL_AFTER If this event will be used in a Process Only session, use WL_BEFORE.

Operating System Event WL_WRITE_VAR_FILE

Description This event writes a value from an INI (variable) text file.

Equivalent Session WRITE INI FILE Editor Command Parameter1 Filename. NULL terminated string. Parameter2 User variable name. NULL terminated string.

Example: <%[Section].VariableName> Where WL_ON_SERVER, WL_ON_CLIENT When WL_BEFORE, WL_DURING, WL_AFTER Options The following options are valid for this event:

WL_NOT_NEEDED If this option is specified, a completed session may be marked “successful” even if this event fails.

WL_WO_CRITICAL Ends the work object if the event fails. Critical events with a “no execute” status do not end the session. 224 RemoteWare API Manual

Operating System Event WL_WRITE_VAR_FILE (Continued)

Options WL_CRITICAL (Continued) Ends the session if the event fails. Critical events with a “no execute” status do not end the session.

WL_CRITICAL_RETRY If this critical event fails and the session has retries enabled, the Server will reschedule the session. You must also specify WL_CRITICAL for this option to have any effect.

WL_CONDITIONAL_TRUE Executes the event only if the previous event was successful.

WL_CONDITIONAL_FALSE Executes the event only if the previous event failed or did not execute (“no execute” status).

WL_BEFORE, WL_DURING, WL_AFTER If this event will be used in a Process Only session, use WL_BEFORE.

Operating System Event WL_DELETE_VAR_FILE

Description This event deletes a variable from an INI (variable) text file.

Equivalent Session DELETE INI FILE Editor Command Parameter1 Filename. NULL terminated string. Parameter2 User variable name. NULL terminated string.

Example: <%[Section].VariableName> or “Main.Dir” Where WL_ON_SERVER, WL_ON_CLIENT When WL_BEFORE, WL_DURING, WL_AFTER CHAPTER 6 / Worklist Events 225

Operating System Event WL_DELETE_VAR_FILE (Continued)

Options The following options are valid for this event:

WL_NOT_NEEDED If this option is specified, a completed session may be marked “successful” even if this event fails.

WL_WO_CRITICAL Ends the work object if the event fails. Critical events with a “no execute” status do not end the session.

WL_CRITICAL Ends the session if the event fails. Critical events with a “no execute” status do not end the session.

WL_CRITICAL_RETRY If this critical event fails and the session has retries enabled, the Server will reschedule the session. You must also specify WL_CRITICAL for this option to have any effect.

WL_CONDITIONAL_TRUE Executes the event only if the previous event was successful.

WL_CONDITIONAL_FALSE Executes the event only if the previous event failed or did not execute (“no execute” status).

WL_BEFORE, WL_DURING, WL_AFTER If this event will be used in a Process Only session, use WL_BEFORE.

Session Control Event WL_GROUP_TEST Description This event tests if a Client belongs to a particular group.

Equivalent Session TEST if Client is in GROUP Editor Command Parameter1 Group Name. NULL terminated string. Parameter2 N/A Where WL_ON_SERVER 226 RemoteWare API Manual

Session Control Event WL_GROUP_TEST (Continued)

When WL_BEFORE, WL_DURING, WL_AFTER Options The following options are valid for this event:

WL_NOT_NEEDED If this option is specified, a completed session may be marked “successful” even if this event fails.

WL_WO_CRITICAL Ends the work object if the event fails. Critical events with a “no execute” status do not end the session.

WL_CRITICAL Ends the session if the event fails. Critical events with a “no execute” status do not end the session.

WL_CRITICAL_RETRY If this critical event fails and the session has retries enabled, the Server will reschedule the session. You must also specify WL_CRITICAL for this option to have any effect.

WL_CONDITIONAL_TRUE Executes the event only if the previous event was successful.

WL_CONDITIONAL_FALSE Executes the event only if the previous event failed or did not execute (“no execute” status).

WL_BEFORE, WL_DURING, WL_AFTER If this event will be used in a Process Only session, use WL_BEFORE.

Session Control Event WL_SET_VARIABLE Description This event creates a user defined variable for use elsewhere in a session, including other Workobjects. For more details, see the RemoteWare Server Reference Manual.

Equivalent Session SET VARiable Editor Command CHAPTER 6 / Worklist Events 227

Session Control Event WL_SET_VARIABLE (Continued)

Parameter1 This is a zero-terminated text string that specifies the variable name, which can be up to 257 characters long. This name must be unique for all workobjects in a session. Parameter2 This is a zero-terminated text string that specifies the value to be compared against the named variable. This can be one or more variables and/or text elements, or the path and file name of a file that contains a value (an indirect assignment). When using a file for indirect assignment, precede the path and file name with "@", such as @C:\Q2.TXT. Where Use WL_ON_SERVER for all WL_SET_VARIABLE events. Specifying WL_ON_NODE results in an error. When WL_BEFORE, WL_DURING, or WL_AFTER is valid. However, if this worklist will be used in a Process Only session, use WL_BEFORE. Options The following options are valid for this event: WL_CRITICAL Ends the session if the file transfer failed. Critical events with a “no execute” status do not end the session. WL_CRITICAL_RETRY If this critical event fails, and the session has retries enabled, the Server will reschedule the session. You must also specify WL_CRITICAL for this option to have any effect. WL_NOT_NEEDED If this option is specified, a completed session may be marked “successful” even if this event fails. WL_CONDITIONAL_TRUE Executes the event only if the previous event was successful. WL_CONDITIONAL_FALSE Executes the event only if the previous event failed or did not execute (“no execute” status). 228 RemoteWare API Manual

Session Control Event WL_TEST_VARIABLE Description This event compares predefined or user defined variable against a known value. For more details, see the RemoteWare Server Reference Manual.

Equivalent Session TEST VARiable Editor Command Parameter1 This is a zero-terminated text string that specifies the name of the variable to be tested, which can be up to 257 characters long. Parameter2 This is a zero-terminated text string that specifies the value to be compared against the named variable. This can be one or more variables and/or text elements. Where Use WL_ON_SERVER for all WL_TEST_VARIABLE events. Specifying WL_ON_NODE results in an error. When WL_BEFORE, WL_DURING, or WL_AFTER is valid. However, if this worklist will be used in a Process Only session, use WL_BEFORE. Options The following options are valid for this event:

WL_CRITICAL Ends the session if the file transfer failed. Critical events with a “no execute” status do not end the session.

WL_CRITICAL_RETRY If this critical event fails, and the session has retries enabled, the Server will reschedule the session. You must also specify WL_CRITICAL for this option to have any effect.

hWL_NOT_NEEDED If this option is specified, a completed session may be marked “successful” even if this event fails.

WL_CONDITIONAL_TRUE Executes the event only if the previous event was successful.

WL_CONDITIONAL_FALSE Executes the event only if the previous event failed or did not execute (“no execute” status). CHAPTER 6 / Worklist Events 229

Server events RemoteWare Server events trigger actions on the Server. Server events are summarized in the following table: Table 24. Server events Function name Description

WL_EXCEPTION Defines an exception worklist that is executed after a Client session fails. WL_NOTIFY Sends a message to a Server process through the specified WIN32 named queue or named pipe. WL_USER_ALARM Generates a customized user alarm, placing text in the Server Log. WL_WORKLIST Inserts a worklist into the current session worklist. WL_XCHG_MSGQUE Exchanges messages between the Server and Client. WL_UNASSIGN Unassigns a work object or a session from the Client.

Server Event WL_EXCEPTION Description This event defines an exception worklist that is executed after a client session fails (except for a Server reboot or Scheduler Overrun).

Equivalent Session EXCEPTION worklist Editor Command Parameter1 This is a zero-terminated text string that specifies the path and name of the worklist file.

If you want to specify an “indirect file,” which contains the actual worklist file to insert, use the at “@” sign, as in the example @filename.ext. Parameter2 NULL Where Use WL_ON_SERVER for all WL_EXCEPTION events. Specifying WL_ON_NODE results in an error. When Use WL_DURING for all WL_EXCEPTION events. 230 RemoteWare API Manual

Server Event WL_NOTIFY Description This event sends a message to a WIN32 server process, through either a WIN32 queue or named pipe. Your program can respond to WL_NOTIFY events by using the RWSNotifyWait() function.

Equivalent Session NOTIFY WinNT server Editor Command Parameter1 This is a zero-terminated text string that specifies the WIN32 queue or named pipe used to send the NOTIFY signal. Parameter2 This is a zero-terminated text string containing the text you want to send to the process. You can use the , , , ,

, and placeholders to insert the RemoteWare Client name, current date, current time, month, day, and year, respectively. To send just the Client name, use NULL.

You can insert the contents of a file by using the “@” sign, as in the example @filename.ext. Where Use WL_ON_SERVER for all WL_NOTIFY events. Specifying WL_ON_NODE results in an error. When WL_BEFORE, WL_DURING, or WL_AFTER is valid. However, if this worklist will be used in a Process Only session, use WL_BEFORE. Options The following options are valid for this event:

WL_CRITICAL Ends the session if the file transfer failed. Critical events with a “no execute” status do not end the session.

WL_CRITICAL_RETRY If this critical event fails, and the session has retries enabled, the Server will reschedule the session. You must also specify WL_CRITICAL for this option to have any effect.

WL_NOT_NEEDED If this option is specified, a completed session may be marked “successful” even if this event fails.

WL_CONDITIONAL_TRUE Executes the event only if the previous event was successful.

WL_CONDITIONAL_FALSE Executes the event only if the previous event failed or did not execute (“no execute” status). CHAPTER 6 / Worklist Events 231

Server Event WL_USER_ALARM Description This event generates a customized user alarm that displays the specified message in the Server Log.

Equivalent Session USER defined ALARM Editor Command Parameter1 This is a zero-terminated text string that specifies the alarm text to be displayed in the Server Log.

You can insert the contents of a file by using the “@” sign, as in the example @filename.ext. Parameter2 NULL Where Use WL_ON_SERVER for all WL_USER_ALARM events. Specifying WL_ON_NODE results in an error. When WL_BEFORE, WL_DURING, or WL_AFTER is valid. However, if this worklist will be used in a Process Only session, use WL_BEFORE. Options The following options are valid for this event: WL_CRITICAL Ends the session if the file transfer failed. Critical events with a “no execute” status do not end the session. WL_CRITICAL_RETRY If this critical event fails, and the session has retries enabled, the Server will reschedule the session. You must also specify WL_CRITICAL for this option to have any effect. WL_NOT_NEEDED If this option is specified, a completed session may be marked “successful” even if this event fails. WL_CONDITIONAL_TRUE Executes the event only if the previous event was successful. WL_CONDITIONAL_FALSE Executes the event only if the previous event failed or did not execute (“no execute” status). 232 RemoteWare API Manual

Server Event WL_WORKLIST Description This event inserts and executes the specified worklist into the current session worklist. The Server automatically cleans up worklists and sends the results to the Session History Log.

Equivalent Session insert WORKLIST Editor Command Parameter1 This is a zero-terminated text string that specifies the path and name of the worklist file. If you want to specify an “indirect file,” that contains the actual worklist file to insert, use the “@” sign before the file name, as in the example @filename.ext. Parameter2 NULL Where Use WL_ON_SERVER for all WL_WORKLIST events. Specifying WL_ON_NODE results in an error. When WL_BEFORE, WL_DURING, or WL_AFTER is valid. However, if this worklist will be used in a Process Only session, use WL_BEFORE. Options The following options are valid for this event:

WL_CRITICAL Ends the session if the file transfer failed. Critical events with a “no execute” status do not end the session.

WL_CRITICAL_RETRY If this critical event fails, and the session has retries enabled, the Server will reschedule the session. You must also specify WL_CRITICAL for this option to have any effect.

WL_NOT_NEEDED If this option is specified, a completed session may be marked “successful” even if this event fails.

WL_CONDITIONAL_TRUE Executes the event only if the previous event was successful.

WL_CONDITIONAL_FALSE Executes the event only if the previous event failed or did not execute (“no execute” status). CHAPTER 6 / Worklist Events 233

Operating System Event WL_XCHG_MSGQUE

Description This event exchanges messages between the Server and Client.

Equivalent Session MESSAGE EXCHANGE Editor Command Parameter1 N/A Parameter2 N/A Where WL_ON_CLIENT When WL_DURING Options The following options are valid for this event:

WL_NOT_NEEDED If this option is specified, a completed session may be marked “successful” even if this event fails.

WL_WO_CRITICAL Ends the work object if the event fails. Critical events with a “no execute” status do not end the session.

WL_CRITICAL Ends the session if the event fails. Critical events with a “no execute” status do not end the session.

WL_CRITICAL_RETRY If this critical event fails and the session has retries enabled, the Server will reschedule the session. You must also specify WL_CRITICAL for this option to have any effect.

WL_CONDITIONAL_TRUE Executes the event only if the previous event was successful.

WL_CONDITIONAL_FALSE Executes the event only if the previous event failed or did not execute (“no execute” status).

WL_DURING 234 RemoteWare API Manual

Operating System Event WL_UNASSIGN

Description This event unassigns a work object or session from the Client.

Equivalent Session UNASSIGN from client Editor Command Parameter1 NULL terminated string, valid values are WORKOBJECT or SESSION. Parameter2 N/A Where WL_ON_SERVER When WL_BEFORE, WL_DURING, WL_AFTER Options The following options are valid for this event:

WL_NOT_NEEDED If this option is specified, a completed session may be marked “successful” even if this event fails.

WL_CONDITIONAL_TRUE Executes the event only if the previous event was successful.

WL_CONDITIONAL_FALSE Executes the event only if the previous event failed or did not execute (“no execute” status).

WL_BEFORE, WL_DURING, WL_AFTER If this event will be used in a Process Only session, use WL_BEFORE. : Win32 COM Object Client APIs

CHAPTER 7

7 Win32 COM Object Client APIs

The RemoteWare Win32 Client APIs are a collection of Component Object Model (COM) objects that allow you to write programs that interact with XcelleNet's RemoteWare Client software. Since the APIs utilize COM, you can use any Windows 9x/NT development language that supports the COM structure. This includes Visual Basic, Delphi, C/C++, Java, and many others. The API DLL is automatically installed and registered when you install the RemoteWare 32-bit and OS/2 Client API.

This chapter includes:

• Win32 COM Object Client APIs overview

• Interface Definition Language (IDL)

• Error handling

• Win32 Client API structure

• IRWClient API methods

• IRWClientInfo API methods

• IRWClientDialingEntry API methods

• IRWClientSessionStatus API methods

• IRWClientTextExplanation API methods

• IRWClientDialingDirectory API methods

• IRWClientSessionResultLog API methods 236 RemoteWare API Manual

• IRWClientStatus API methods

• IRWClientWOSelection API methods

• IRWClientDialingEntryCollection API methods

• IRWClientInfoCollection API methods

• IXWorklist API methods

• IRWClientStatusEvents API methods

• Enumerations and structures

• Client ActiveX Controls CHAPTER 7 / Win32 COM Object Client APIs 237

Overview of Win32 COM OBJECT Client APIs The RemoteWare Win32 Client APIs are a collection of COM objects you can use to write programs to interact with XcelleNet's RemoteWare Client software. The Win32 Client APIs include: • The RemoteWare Client API Dynamic Link Library (DLL) • A Microsoft Visual Basic Example • Various C/C++ header files The examples included in this chapter and in the RemoteWare 32-bit and OS/2 Client API utilize most the of the API methods and should provide you with a firm understanding of the use and power of the RemoteWare Win32 Client APIs.

Interface Definition Language (IDL) Although similar to other chapters in this guide, this chapter differs in its presentation of APIs. Specifically, this chapter references IDL (Interface Definition Language) rather than specific Visual C or Visual Basic statements. Since each development language uses different syntax and notation, you need to interpet the IDL (Interface Definition Language) Synopsis for the particular language you are using. For example, if you are using C or C++ and choose to use the native/raw format of the COM method, your implementation may appear as: HRESULT hr = get_ClientName( ppName ); In Microsoft Visual C++ 5.0+, an alternative, simpler syntax may be used. In this enhanced format, methods are wrapped for ease of use and error handling is accomplished using exceptions. If you choose this syntax, the implementation of the method may appear as: try { _bstr_t tmp = pClient->GetClientName(); } catch ( const _com_error e ) { // Error handling } 238 RemoteWare API Manual

If you are using Microsoft’s Visual Basic or Visual Basic Sript, the format of the method would appear as: Dim ClientNameString As String Dim Client as As IRWClient ClientNameString = Client.ClientName The examples included in this guide are written using Microsoft’s enhanced format. Smart pointers and exception handling are also used to provide a simpler and easier to understand example.

Error handling Each of the RemoteWare API methods return a Win32 HRESULT code indicating the success of the method. A value of S_OK indicates success, while a value of E_FAIL indicates an error. When E_FAIL is returned, an error text string is also set and may be retrieved. Retrieving this error text is dependent upon the programming language and the implementation of the RemoteWare API interfaces being used. If you are programming in C/C++ and using the raw COM method calls, retrieving the error text requires a bit of work on the part of the programmer. Error information must be retrieved by querying the ISupportInfoError interface. For more information, please consult by your C/C++ languange documentation. The following is an sample function that can be used to retrieve the error text string for the IRWClient interface: // ------// ErrorMessage // -Obtains Error Information from the IErrorInfo interface. // ------void ErrorMessage( IRWClient FAR* pRWClient ) { IErrorInfo FAR* perrinfo; BSTR bstrDesc; HRESULT hr; ISupportErrorInfo FAR* psupporterrinfo; TCHAR szError[STR_LEN]; hr = pRWClient->QueryInterface(IID_ISupportErrorInfo, (LPVOID FAR*)&psupporterrinfo); if (FAILED(hr)) { MessageBox(NULL, TEXT("QueryInterface(IID_ISupportErrorInfo)"), szError, MB_OK); return; } hr = psupporterrinfo->InterfaceSupportsErrorInfo( __uuidof(IRWClient) ); if (hr != NOERROR) { psupporterrinfo->Release(); return; CHAPTER 7 / Win32 COM Object Client APIs 239

} psupporterrinfo->Release(); // In this example only the error description is obtained and // displayed. See the IErrorInfo interface for other information // that is available. hr = GetErrorInfo(0, &perrinfo); if (FAILED(hr)) return; hr = perrinfo->GetDescription(&bstrDesc); if (FAILED(hr)) { perrinfo->Release(); return; } MessageBox(NULL, FROM_OLE_STRING(bstrDesc), szError, MB_OK); SysFreeString(bstrDesc); } If you are programming in Microsoft's Visual C/C++ and using their enhanced COM method calls, retrieving the error text is a somewhat easier exercise. In this case, the method calls throw an exception of type _com_error. This exception simplifies the retrieval of the error code and any associated text string. The following is an example function used to retrieve the error text string for the IRWClient interface. // ------// ErrorMessage // -Obtains Error Information from the _com_error exception. // ------void ErrorMessage(const _com_error& e) { CString Msg; CString Description; CString Error("Caught COM exception %02lX\n%s"); HRESULT hr = e.Error(); switch (hr) { case E_FAIL: { Description = (char*)e.Description(); break; } default: { LPVOID lpMsgBuf; FormatMessage( FORMAT_MESSAGE_ALLOCATE_BUFFER | FORMAT_MESSAGE_FROM_SYSTEM | FORMAT_MESSAGE_IGNORE_INSERTS, NULL, hr, MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT), (LPTSTR) &lpMsgBuf, 0, 240 RemoteWare API Manual

NULL ); Msg.Format(Error, hr, Description); AfxMessageBox(Msg); }API Object Overview Msg.Format(Error, hr, Description); AfxMessageBox(Msg); }

Win32 Client API structure The RemoteWare Win32 Client APIs consist of the following three creatable objects and four noncreatable objects:

RWClient Object Access Client functionality and retrieve status. This object is creatable. The interfaces include: • IRWClient • IRWClientSessionStatus • IRWClientTextExplanation • IRWClientDialingDirectory • IRWClientSessionResultLog • [default] IRWClientStatus • [default, source] dispinterface _RWClientStatusEvents

EnumRWClientInfo Object Enumerate installed Clients. This object is creatable. The interface includes: • IRWClientInfoCollection

XWorkList Object Create, alter, or read worklist files. This object is creatable. The interface includes: •IXWorkList

RWClientInfo Object Information concerning the installed Client. This object is not creatable and must be retrieved from an object of type RWClientInfoCollection. The interface includes: • IRWClientInfo CHAPTER 7 / Win32 COM Object Client APIs 241

RWClientDialingEntry Object Information concerning a Client dialing directory entry. This object is not creatable and must be retrieved from an object of type RWClientDialingEntry or RWClientDialingDirectory. The interface includes: • IRW ClientDialingEntry

IRWClientDialingEntryCollection Object List of Client dialing directory entries. This object is not creatable and must be retrieved from an object of type RWClientDialingDirectory. The interface includes: • IRWClientDialingEntryCollection

RWClientWOSelection Object Selects work objects to be executed during a session. This object is not creatable and must be retrieved from an object of type RWClientDialingEntry. The interface includes: • IRWClientWOSelection 242 RemoteWare API Manual

IRWClient API Methods The IRWClient Interface is the foundation of the RemoteWare Client API. It implements the basic Client functionality and is often the most frequently used interface. The IRWClient Interface implements the RWClient coclass and is a user creatable interface.

Overview

• Implements coclass: RWClient. • Creatable? Yes. The following table summarizes the IRWClient API methods: Table 25. IRWClient API methods Method Name Description

ClientName Gets the RemoteWare Client Name. ClientName Sets the RemoteWare Client Name. InstallPath Gets the RemoteWare installation path. ClientID Gets the RemoteWare installation path. Version Gets the RemoteWare major and minor version numbers. ClientStatus Gets the RemoteWare Client’s current status. Alerts Gets the RemoteWare Client’s current alerts. DefaultResource Gets a COM interface pointer to the RemoteWare Client’s default resource (dialing entry). DefaultResource Sets the RemoteWare Client’s default resource (dialing entry). ResourceStatus Get the current status of the RemoteWare Client’s current resource. PendingOperations Gets the commands issued to the RemoteWare Client, but have not been processed yet. PlayLastSessionOnNameChange Gets the PlayLastSessionOnNameChange flag for the RemoteWare Client. PlayLastSessionOnNameChange Sets the PlayLastSessionOnNameChange flag for the RemoteWare Client. Load Loads the RemoteWare kernel. Unload Unloads the RemoteWare kernel. Connect Connects to the RemoteWare Server using the current resource (dialing directory entry). CHAPTER 7 / Win32 COM Object Client APIs 243

Table 25. IRWClient API methods (Continued) Method Name Description

Initialize Establishes or re-establishes a link with the RemoteWare kernel to monitor activity. ReleasePort Releases the port for the selected RemoteWare Client. Cancel Cancels the current connection (or connection request). ApplyESD Applies any pending ESD (Electronic Software Distribution). RefreshAlerts Manually forces an update of the RemoteWare Client’s alert status.

Win32 IRWClient API ClientName Description Gets the RemoteWare Client Name.

IDL Synopsis [propget] HRESULT ClientName( [out, retval] BSTR* ppName ); Parameters [out, retval] ppName The name of the RemoteWare Client. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Example try { IRWClientPtr pClient; pClient.CreateInstance( __uuidof(RWClient) ); _bstr_t tmp = pClient->GetClientName(); } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "General Error" ); } 244 RemoteWare API Manual

Win32 IRWClient API ClientName Description Sets the RemoteWare Client Name. The named Client should be installed on the current system.

IDL Synopsis [propput] HRESULT ClientName( [in] BSTR ppName ); Parameters [in] ppName The name of the RemoteWare Client. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Example try { IRWClientPtr pClient; pClient.CreateInstance( __uuidof(RWClient) ); _bstr_t tmp(“Client1”); pClient->PutClientName(tmp); } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "General Error" ); } CHAPTER 7 / Win32 COM Object Client APIs 245

Win32 IRWClient API InstallPath Description Gets the RemoteWare installation path.

IDL Synopsis [propget] HRESULT InstallPath( [out, retval] BSTR* ppPath );

Parameters [out, retval] ppPath The install path of the RemoteWare Client. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Example try { Cstring szDisplay; IRWClientPtr pClient; pClient.CreateInstance( __uuidof(RWClient) ); szDisplay.FormatMessage("Client Installation Path: %1!s!\n", (LPCTSTR)pClient->GetInstallPath()); MessageBox((LPCTSTR)szDisplay, "Client INFO", MB_OK); } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "General Error" ); } 246 RemoteWare API Manual

Win32 IRWClient API ClientID Description Gets the RemoteWare installation path.

IDL Synopsis [propget] HRESULT CLientID( [out, retval] long* piD );

Parameters [out, retval] pID The ID of the RemoteWare Client. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. Example try { Cstring szDisplay; IRWClientPtr pClient;

pClient.CreateInstance( __uuidof(RWClient) ); szDisplay.FormatMessage("Client Client ID: %1!d!\n", (LPCTSTR)pClient->GetClientID()); MessageBox((LPCTSTR)szDisplay, "Client INFO", MB_OK); } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "General Error" ); } CHAPTER 7 / Win32 COM Object Client APIs 247

Win32 IRWClient API Version Description Gets the RemoteWare major and minor version numbers.

IDL Synopsis [propget] HRESULT Version( [out] long* pMajorVersion, [out] long* pMinorVersion ); Parameters [out] pMajorVersion The major version number of the kernel. [out] pMinorVersion The minor version number of the kernel. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Example try { Cstring szDisplay; long lMajor, lMinor; IRWClientPtr pClient; pClient.CreateInstance( __uuidof(RWClient) ); pClient->GetVersion(&lMajor, &lMinor); szDisplay.FormatMessage("Client Version: %1!d!.%2!d!\n", lMajor, lMinor); MessageBox((LPCTSTR)szDisplay, "Client INFO", MB_OK); } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "General Error" ); } 248 RemoteWare API Manual

Win32 IRWClient API ClientStatus Description Gets the RemoteWare Client’s current status.

IDL Synopsis [propget] HRESULT ClientStatus( [out, retval] long* pStatusMask ); Parameters [out, retval] A bit mask describing the current Client Status. For valid bit mask pStatusMask values for the RWC_Status_e enumeration, see “Enumerations and Structures” on page 418. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Example try { IRWClientPtr pClient; pClient.CreateInstance( __uuidof(RWClient) ); long lStatus = m_pClient->GetClientStatus(); if ((lStatus & RWCS_LOADED) == 0) { pClient->Load(); } if ((lStatus & RWCS_RESOURCE_READY) == 0) { MessageBox("Waiting for client to be ready!","Waiting...", MB_OK); } else { pClient->Connect(); } } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "General Error" ); } CHAPTER 7 / Win32 COM Object Client APIs 249

Win32 IRWClient API Alerts Description Gets the RemoteWare Client’s current alerts.

IDL Synopsis [propget] HRESULT Alerts( [out, retval] long* pAlertmask ); Parameters [out, retval] pAlertMask A bit mask describing the current Client Alerts. For information on the RWC_Alert_e enumeration, see “Enumerations and Structures” on page 418. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Example try { IRWClientPtr pClient; pClient.CreateInstance( __uuidof(RWClient) ); IRWClientTextExplanationPtr pText = pClient; ... // Get Alert Mask CListBox* pAlertBox = (CListBox*) GetDlgItem( IDC_ALERTMASK ); pAlertBox->ResetContent(); RWC_Alert_e AlertArray[5] = { RWCA_RESOURCEERROR, RWCA_ESDAVAILABLE, RWCA_ESDDISABLED, RWCA_AUTOANSWEROFF, RWCA_CLIENTNOTIFICATION }; long AlertMask = pClient->GetAlerts(); for( int i = 0; i < 5; i++ ) { if ( (AlertMask & AlertArray[i] ) != 0 ) pAlertBox->AddString( pText ->GetAlertExplanation( AlertArray[i] ) ); } ... } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "General Error" ); } 250 RemoteWare API Manual

Win32 IRWClient API DefaultResource Description Gets a COM interface pointer to the RemoteWare Client’s default resource (dialing entry).

IDL Synopsis [propget] HRESULT DefaultResource( [out, retval] IRWClientDialingEntry** ppEntry ); Parameters [out, retval] ppEntry A interface pointer to the default dialing entry. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Example try { IRWClientPtr pClient; long lStatus = 0L; pClient.CreateInstance( __uuidof(RWClient) ); _bstr_t tmp = pClient->GetClientName(); if (tmp.length() > 0) { IRWClientDialingEntryPtr pEntry; pEntry = pClient->GetDefaultResource(); SetDlgItemText( IDC_DEFAULT_RESOURCE, pEntry->GetName() ); } } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "General Error" ); }

Win32 IRWClient API DefaultResource Description Sets the RemoteWare Client’s default resource (dialing entry). CHAPTER 7 / Win32 COM Object Client APIs 251

Win32 IRWClient API DefaultResource (Continued)

IDL Synopsis [propget] HRESULT DefaultResource( [in] BSTR ppEntry ); Parameters [in] ppEntry The name of the default resource. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Example try { CListBox* pList = (CListBox*) GetDlgItem( IDC_ENTRIES ); IRWClientPtr pClient; long lStatus = 0L; pClient.CreateInstance( __uuidof(RWClient) ); CString strSel; pList->GetText( pList->GetCurSel(), strSel ); _bstr_t selected( strSel ); pClient->PutDefaultResource( selected ); } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "General Error" ); } 252 RemoteWare API Manual

Win32 IRWClient API ResourceStatus Description Get the current status of the RemoteWare Client’s current resource.

IDL Synopsis [propput] HRESULT ResourceStatus ( [out] long* pResourceError, [out] RWC_ResourceStatus_e* pStatus, [out, retval] RWC_ResourceType_e* pType ); Parameters [out] pResourceError The error code for the resource. [out] pStatus An enumeration indicating the status of the resource. [out, retval] pType An enumeration indicating the type of resource. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Example try { RWC_ResourceStatus_e Status; long Error; IRWClientPtr pClient; pClient.CreateInstance( __uuidof(RWClient) ); RWC_ResourceType_e Type; Type = pClient->GetResourceStatus( &Error, &Status ); IRWClientTextExplanationPtr pText = pClient; SetDlgItemText( IDC_ERROR, pText->GetResourceError( Type, Error ) ); SetDlgItemText( IDC_TYPE, pText->GetResourceName( Type ) ); ... } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "General Error" ); } CHAPTER 7 / Win32 COM Object Client APIs 253

Win32 IRWClient API PendingOperations

Description Gets the commands that have been issued to the RemoteWare Client, but that have not been processed yet.

IDL Synopsis [propget] HRESULT PendingOperations( [out, retval] long* pPendingOperationsMask ); Parameters [out, retval] A bit mask describing the current pending operations for the pPendingOperations RemoteWare Client. Mask Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Example try { IRWClientPtr pClient; CListBox* pOpBox = (CListBox*) GetDlgItem( IDC_OPERATIONMASK ); pClient.CreateInstance( __uuidof(RWClient) ); RWC_PendingOperation_e OpArray[10] = { RWCO_NONE, RWCO_REINIT, RWCO_UNLOAD, RWCO_CONNECT, RWCO_CANCEL, RWCO_ENABLEAA, RWCO_DISABLEAA, RWCO_RELEASEPORT, RWCO_EANBLEESD, RWCO_DISABLEESD }; CString OpStrings[10] = { "RWCO_NONE", "RWCO_REINIT", "RWCO_UNLOAD", "RWCO_CONNECT", "RWCO_CANCEL", "RWCO_ENABLEAA", "RWCO_DISABLEAA", "RWCO_RELEASEPORT", "RWCO_EANBLEESD", "RWCO_DISABLEESD" }; long OpMask = pClient ->GetPendingOperations(); for( int i = 0; i < 10; i++ ) { if ( ( OpMask & OpArray[i] ) != 0 ) pOpBox->AddString( OpStrings[i] ); } } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "General Error" ); } 254 RemoteWare API Manual

Win32 IRWClient API PlayLastSessionOnNameChange Description Gets the PlayLastSessionOnNameChange flag for the RemoteWare Client. If set, then the last session (or the current session up to the current state) will be replayed when the object’s ClientName property is set.

IDL Synopsis [propget] HRESULT PlayLastSessionOnNameChange( [out, retval] VARIANT_BOOL* pPlaySession ); Parameters [out, retval] A VARIANT_BOOL indicating the status of the pPlaySession PlayLastSessionOnNameChange flag. If VARIANT_TRUE the last RemoteWare session will be replayed; if VARIANT_FALSE the last session will not be replayed. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Example try { IRWClientPtr pClient; pClient.CreateInstance( __uuidof(RWClient) ); if ( pClient->GetPlayLastSessionOnNameChange == VARIANT_TRUE ) { AfxMessageBox( "Client will replay last session on name change" ); } } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "General Error" ); } CHAPTER 7 / Win32 COM Object Client APIs 255

Win32 IRWClient API PlayLastSessionOnNameChange Description Sets the PlayLastSessionOnNameChange flag for the RemoteWare Client. If set, the last session (or the current session up to the current state) will be replayed when the object’s ClientName property is set. Comments In order to take effect, this value must be set prior to setting the Client name with IRWClient PutClientName.

IDL Synopsis [propput] void PutPlayLastSessionOnNameChange ( [in] VARIANT_BOOL pPlaySession ) Parameters [in] pPlaySession Set VARIANT_TRUE to play the last RemoteWare session; set VARIANT_FALSE to disable. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Example try { IRWClientPtr pClient; pClient.CreateInstance( __uuidof(RWClient) ); if ( IsDlgButtonChecked( IDC_PLAY ) != 0 ) pClient->PutPlayLastSessionOnNameChange ( VARIANT_TRUE ); else pClient->PutPlayLastSessionOnNameChange ( VARIANT_FALSE ); } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "General Error" ); } 256 RemoteWare API Manual

Win32 IRWClient API Load Description Loads the RemoteWare kernel.

IDL Synopsis HRESULT Load ( ) Parameters [in] pPlaySession Set VARIANT_TRUE to play the last RemoteWare session; set VARIANT_FALSE to disable. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Example try { IRWClientPtr pClient; pClient.CreateInstance( __uuidof(RWClient) ); pClient->Load(); } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "General Error" ); } CHAPTER 7 / Win32 COM Object Client APIs 257

Win32 IRWClient API Unload Description Unloads the RemoteWare kernel.

IDL Synopsis HRESULT Unload ( ) Parameters None Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Example try { IRWClientPtr pClient; pClient.CreateInstance( __uuidof(RWClient) ); pClient->Unload(); } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "General Error" ); }

Win32 IRWClient API Connect Description Connects to the RemoteWare Server using the current resource (dialing directory entry).

IDL Synopsis HRESULT Connect ( ) Parameters None 258 RemoteWare API Manual

Win32 IRWClient API Connect (Continued)

Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Example try { IRWClientPtr pClient; pClient.CreateInstance( __uuidof(RWClient) ); long lStatus = pClient->GetClientStatus(); if ((lStatus & RWCS_LOADED) == 0) { pClient->Load(); } if ((lStatus & RWCS_RESOURCE_READY) == 0) { MessageBox("Waiting for client to be ready!", "Waiting...", MB_OK); } else { pClient->Connect(); } } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "General Error" ); } CHAPTER 7 / Win32 COM Object Client APIs 259

Win32 IRWClient API Initialize Description Establishes or re-establishes a link with the RemoteWare kernel to monitor activity.

IDL Synopsis HRESULT Initialize ( ) Parameters None Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Example try { IRWClientPtr pClient; pClient.CreateInstance( __uuidof(RWClient) ); pClient->Initialize(); } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "General Error" ); }

Win32 IRWClient API ReleasePort Description Releases the port for the selected RemoteWare Client. To reacquire the port, call IRWClient::Initialize().

IDL Synopsis HRESULT ReleasePort ( ) Parameters None 260 RemoteWare API Manual

Win32 IRWClient API ReleasePort (Continued)

Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Example try { IRWClientPtr pClient; pClient.CreateInstance( __uuidof(RWClient) ); pClient->ReleasePort(); } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "General Error" ); }

Win32 IRWClient API Cancel Description Cancels the current connection (or connection request).

IDL Synopsis HRESULT Cancel ( [in] VARIANT_BOOL ForceIfConnected ) Parameters [in] ForceIfConnected If ForceIfConnected is True, then a cancel will be attempted even if an active connection exists. If ForceIfConnected is False, the cancel will be attempted only if a connection request is pending but is not yet established; it will not be attempted if the connection is already active. CHAPTER 7 / Win32 COM Object Client APIs 261

Win32 IRWClient API Cancel (Continued)

Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Example try { IRWClientPtr pClient; pClient.CreateInstance( __uuidof(RWClient) ); pClient->Cancel( VARIANT_TRUE ); } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "General Error" ); }

Win32 IRWClient API ApplyESD Description Applies any pending ESD (Electronic Software Distribution).

IDL Synopsis HRESULT ApplyESD( [in] VARIANT_BOOL RebootIfNecessary, [out, retval] long* pApplyResult ); Parameters [in] RebootIfNecessary Set to VARIANT_TRUE to reboot after applying the ESD. [out, retval] An error result code indicating if the ESD was applied successfully. pApplyResult Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. 262 RemoteWare API Manual

Win32 IRWClient API ApplyESD (Continued)

Example try { CButton* pApplyESD = (CButton*) GetDlgItem( IDC_APPLY_ESD ); long lApplyResult = 0L; IRWClientPtr pClient; pClient.CreateInstance( __uuidof(RWClient) ); lApplyResult = pClient->ApplyESD (VARIANT_FALSE); if (lApplyResult & RWCAE_ERROR_COPY) { if (lApplyResult == RWCAE_ERROR_COPY) MessageBox("Error copying file", “Apply ESD", MB_OK); else if (lApplyResult & WCAE_ERROR_NETWORK_FILE_IN_USE) MessageBox("Network File Error.", "Apply ESD", MB_OK); else if (lApplyResult & RWCAE_ERROR_COPY_READ_ONLY) MessageBox("Read Only File Error", "Apply ESD", MB_OK); else if (lApplyResult & RWCAE_ERROR_REBOOT) { if (MessageBox("Reboot to apply ESD.", "Apply ESD", MB_OK) == IDOK) { ExitWindowsEx(EWX_REBOOT, 0); } } } else Example (Continued) { MessageBox("ESD applied", "Apply ESD", MB_OK); } pApplyESD->EnableWindow(FALSE); } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "General Error" ); } CHAPTER 7 / Win32 COM Object Client APIs 263

Win32 IRWClient API RefreshAlerts Description Manually forces an update of the RemoteWare Client’s alert status.

IDL Synopsis HRESULT RefreshAlerts( ); Parameters None Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. Example try { IRWClientPtr pClient;

pClient.CreateInstance( __uuidof(RWClient) ); pClient->RefreshAlerts(); } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "General Error" ); } 264 RemoteWare API Manual

IRWClientInfo API Methods IRWClientInfo provides three functions that enable basic Client information such as the installation path and Client name to be retrieved. The functions also determine whether the Client is licensed and the license type. IRWClientInfo implements the coclass RWClientInfo and is a user creatable interface.

Overview

• Implements coclass: RWClientInfo. • Creatable? Yes. The following table summarizes the IRWClientInfo API methods: Table 26. IRWClientInfo API methods Method Name Description

Name Gets the name of the RemoteWare Cient. InstallPath Gets the RemoteWare Client’s installation path. IsLicensed This method is obsolete and should not be used.

Win32 IRWClientInfo API Name Description Gets the name of the RemoteWare Client.

IDL Synopsis [propget] HRESULT Name( [out, retval] BSTR* ppName ); Parameters [out, retval] ppName The name of the RemoteWare Client CHAPTER 7 / Win32 COM Object Client APIs 265

Win32 IRWClientInfo API Name (Continued) Return values A Win32 HRESULT indicates the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Example try { CListCtrl* pList = (CListCtrl*) GetDlgItem( IDC_CLIENT_LIST ); IRWClientInfoPtr pInfo; IEnumVARIANTPtr pEnum; VARIANT var = {0}; ULONG Fetched; int Item = 0; pEnum = pCol->Get_NewEnum(); while ( S_OK == pEnum->Next( 1, &var, &Fetched ) ) { ASSERT( var.vt == VT_DISPATCH ); pInfo = var.pdispVal; pList->InsertItem( Item, pInfo-> GetName() ); Item++; ::VariantClear( &var ); } } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "General Error" ); }

Win32 IRWClientInfo API InstallPath Description Gets the RemoteWare Client’s installation path.

IDL Synopsis [propget] HRESULT InstallPath( [out, retval] BSTR* ppPath ); Parameters [out, retval] ppPath The installation path of the RemoteWare Client 266 RemoteWare API Manual

Win32 IRWClientInfo API InstallPath (Continued)

Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. Example try { CListCtrl* pList = (CListCtrl*) GetDlgItem( IDC_CLIENT_LIST ); IRWClientInfoPtr pInfo; IEnumVARIANTPtr pEnum; VARIANT var = {0}; ULONG Fetched; int Item = 0; pEnum = pCol->Get_NewEnum(); while ( S_OK == pEnum->Next( 1, &var, &Fetched ) ) { ASSERT( var.vt == VT_DISPATCH ); pInfo = var.pdispVal; pList->InsertItem( Item, pInfo->GetName() ); pList->SetItemText(Item, 1, pInfo->GetInstallPath() ); Item++; ::VariantClear( &var ); } } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "General Error" ); }

Win32 IRWClientInfo API IsLicensed Notice This method is obsolete and should not be used. CHAPTER 7 / Win32 COM Object Client APIs 267

IRWClientDialingEntry API The IRWClientDialingEntry interface provides functionality to manipulate dialing entries. It also allows retrieval of the Work Objects for a dialing entry via the return of a IRWClientWOSelection interface pointer. The IRWClientDialingEntry interface implements the RWClientDiaingEntry coclass and is not a user createable interface. To use the IRWClientDialing Entry interface, it must be retrieved through an IRWClientDialingDirectory interface.

Overview

• Implements coclass: RWClientDialingEntry. • Creatable: No, must be retrieved from IRWClientDialingDirectory. The following table summarizes the IRWClientDialingEntry API methods: Table 27. IRWClientDialingEntry API methods Method Name Description

Name Gets the name of the dialing entry. Name Sets the name of the dialing entry. Address Sets the dialing entry’s network address. Address Gets the dialing entry’s network address. EnableAutoAnswer Gets the flag that determines if this dialing entry will accept incoming calls from the Server. EnableAutoAnswer Sets the flag that determines if this dialing entry will accept incoming calls from the Server. DisableESD Gets the flag that will determine if ESD will be processed with this dialing entry. DisableESD Sets the flag that will determine if ESD will be processed with this dialing entry. ResourceType Gets the dialing entry’s resource type. ReadOnly Gets the flag that determines if this dialing entry can be modified by the RemoteWare Client. SetAsDefaultEntry Sets this dialing entry to be the default resource. WorkObjectSelection Gets an interface pointer to the work object list for the selected dialing entry. 268 RemoteWare API Manual

Win32 IRWClientDialingEntry API Name Description Gets the name of the dialing entry.

IDL Synopsis [propget] HRESULT Name ( [out, retval] BSTR* ppName ); Parameters [out, retval] ppName The name of the Dialing Entry. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Example try { CListCtrl* pList = (CListCtrl*) GetDlgItem( IDC_ENTRY_LIST ); IRWClientDialingDirectoryPtr pDirectory; IRWClientDialingEntryPtr pEntry; _bstr_t EntryName; _bstr_t name; int Item = 0; IRWClientPtr pClient( __uuidof( RWClient ) ); ... pClient->PutClientName( name ); pDirectory = pClient; pDirectory->GetEntry( EntryName, &pEntry ); pList->InsertItem( Item, pEntry->GetName() ); pList->SetItemText( Item, 1, pEntry ->GetAddress() ); ... } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "General Error" ); } CHAPTER 7 / Win32 COM Object Client APIs 269

Win32 IRWClientDialingEntry API Name Description Sets the name of the dialing entry.

IDL Synopsis [propput] HRESULT Name ( [in] BSTR ppName ); Parameters [in] ppName The name of the Dialing Entry. 270 RemoteWare API Manual

Win32 IRWClientDialingEntry API Name (Continued)

Return values A Win32 HRESULT indicates the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Example try { IRWClientDialingEntryPtr pEntry; ... CNewDlg dlg; int ret = dlg.DoModal(); if ( ret == IDOK ) { // Set Entry Name _bstr_t EntryName( dlg.m_strEntryName ); pEntry->PutName(EntryName); ... if ( dlg.IsDefault() == VARIANT_TRUE ) pEntry->SetAsDefaultEntry(); } } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "General Error" ); } CHAPTER 7 / Win32 COM Object Client APIs 271

Win32 IRWClientDialingEntry API Address Description Gets the dialing entry’s network address.

IDL Synopsis [propget] HRESULT Address ( [out, retval] BSTR* ppAddress ) Parameters [out, retval] ppAddress The network address for the current Dialing Entry. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Example try { CListCtrl* pList = (CListCtrl*) GetDlgItem (IDC_ENTRY_LIST) IRWClientDialingDirectoryPtr pDirectory; IRWClientDialingEntryPtr pEntry; _bstr_t EntryName; _bstr_t name; int Item = 0; IRWClientPtr pClient(__uuidof( RWClient ) ); ... pClient->PutClientName( name ); pDirectory = pClient; pDirectory->GetEntry( EntryName, &pEntry ); pList->SetItemText( Item, 1, pEntry ->GetAddress() ); ... } catch( const_com_error e ) { ErrorMessage( e); } catch(...) { AfxMessageBox ( “General Error” ); 272 RemoteWare API Manual

Win32 IRWClientDialingEntry API Address Description Sets the dialing entry’s network address.

IDL Synopsis [propput] void Address ( [in] BSTR ppAddress ) Parameters [in] ppAddress The network address for the dialing entry. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Example try { IRWClientDialingEntryPtr pEntry; ... CNewDlg dlg; int ret = dlg.DoModal(); if ( ret == IDOK ) { // Set Entry Name _bstr_t EntryName( dlg.m_strEntryName ); pEntry->PutName(EntryName); // Set the address _bstr_t Address( dlg.m_strAddress ); pEntry->PutAddress( Address ); ... if ( dlg.IsDefault() == VARIANT_TRUE ) pEntry->SetAsDefaultEntry(); } } } } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "General Error" ); } CHAPTER 7 / Win32 COM Object Client APIs 273

Win32 IRWClientDialingEntry API EnableAutoAnswer Description Gets the flag that determines if this dialing entry will accept incoming calls from the Server.

IDL Synopsis [propget] HRESULT EnableAutoAnswer( [out, retval] VARIANT_BOOL* pEnable ); Parameters [out, retval] pEnable Status of the Auto Answer Flag. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Example pList->SetItemText( Item, 1, pEntry ->GetAddress() ); if ( pEntry->GetResourceType() == RWCRT_ASYNC ) { if ( pEntry->GetEnableAutoAnswer() == VARIANT_TRUE ) pList->SetItemText( Item, 2, "ON" ); else pList->SetItemText( Item, 2, "OFF" ); } else { pList->SetItemText( Item, 2, "N/A" ); } ... } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "General Error" ); } 274 RemoteWare API Manual

Win32 IRWClientDialingEntry API EnableAutoAnswer Description Sets the flag that determines if this dialing entry will accept incoming calls from the Server.

IDL Synopsis [propput] HRESULT EnableAutoAnswer( [in] VARIANT_BOOL pEnable ); Parameters [in] Enable Enable (VARIANT_TRUE) or disable (VARIANT_FALSE) Auto Answer. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Example try { IRWClientDialingEntryPtr pEntry; ... CNewDlg dlg; int ret = dlg.DoModal(); if ( ret == IDOK ) { // Set Entry Name _bstr_t EntryName( dlg.m_strEntryName ); pEntry->PutName(EntryName); // Set the address _bstr_t Address( dlg.m_strAddress ); pEntry->PutAddress( Address ); // Do we want AutoAnswer VARIANT_BOOL bAutoAnswer = dlg.IsAuto; pEntry->PutEnableAutoAnswer( bAutoAnswer );

Example (Continued) ... if ( dlg.IsDefault() == VARIANT_TRUE ) pEntry->SetAsDefaultEntry(); } } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "General Error" ); } CHAPTER 7 / Win32 COM Object Client APIs 275

Win32 IRWClientDialingEntry API DisableESD Description Gets the flag that will determine if ESD will be processed with this dialing entry.

IDL Synopsis [propget] HRESULT DisableESD( [out, retval] VARIANT_BOOL* pDisable ); Parameters [out, retval] pDisable Status of the Disable ESD flag. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. 276 RemoteWare API Manual

Win32 IRWClientDialingEntry API DisableESD (Continued)

Example try { CListCtrl* pList = (CListCtrl*) GetDlgItem( IDC_ENTRY_LIST ); IRWClientDialingDirectoryPtr pDirectory; IRWClientDialingEntryPtr pEntry; _bstr_t EntryName; _bstr_t name; int Item = 0;

IRWClientPtr pClient( __uuidof( RWClient ) ); ... pClient->PutClientName( name ); pDirectory = pClient; pDirectory->GetEntry( EntryName, &pEntry ); pList->InsertItem( Item, pEntry->GetName() ); ... if ( pEntry->GetDisableESD() == VARIANT_TRUE ) pList->SetItemText( Item, 3, "Enabled" ); else pList->SetItemText( Item, 3, "Disabled" ); ... } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "General Error" ); } CHAPTER 7 / Win32 COM Object Client APIs 277

Win32 IRWClientDialingEntry API DisableESD Description Sets the flag that will determine if ESD will be processed with this dialing entry.

IDL Synopsis [propget] HRESULT DisableESD( [in] VARIANT_BOOL pDisable ); Parameters [in] pDisable Enable (VARIANT_TRUE) or disable (VARIANT_FALSE) ESD. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Example try { IRWClientDialingEntryPtr pEntry; ... CNewDlg dlg; if ( ret ==IDOK ) { // Set Entry Name _bstr_t EntryName( dlg.m_strEntryName ); pEntry->PutName(EntryName); // Set the Address _bstr_t Address(dlg.m_strAddress ); pEntry->PutAddress( Address ); // Do we want Autoanswer VARIANT_BOOL bAutoAnswer = dlg.IsAuto; pEntry->PutEnableAutoAnswer ( bAutoAnswer ); ... if ( dlg.IsDefault() == VARIANT_TRUE ) pEntry->SetAsDefaultEntry(); } } catch( const_com_error e) { ErrorMessage( e ); } catch(...) { AfxMessageBox( “General Error” ); } 278 RemoteWare API Manual

Win32 IRWClientDialingEntry API ResourceType Description Gets the dialing entry’s resource type.

IDL Synopsis [propget] HRESULT ResourceType( [out, retval] RWC_ResourceType_e* pResourceType ); Parameters [out, retval] Type of resource used in the dialing entry. pResourceType For the definition and values for these enumerations, see “Enumerations and Structures” on page 418. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Example try { CListCtrl* pList = (CListCtrl*) GetDlgItem( IDC_ENTRY_LIST ); IRWClientDialingDirectoryPtr pDirectory; IRWClientDialingEntryPtr pEntry; _bstr_t EntryName; _bstr_t name; int Item = 0; IRWClientPtr pClient( __uuidof( RWClient ) ); ... pClient->PutClientName( name ); pDirectory = pClient; pDirectory->GetEntry( EntryName, &pEntry ); pList->InsertItem( Item, pEntry->GetName() ); pList->SetItemText( Item, 1, pEntry ->GetAddress() ); if ( pEntry->GetResourceType() == RWCRT_ASYNC ) { if ( pEntry->GetEnableAutoAnswer() == VARIANT_TRUE ) pList->SetItemText( Item, 2, "ON" ); else pList->SetItemText( Item, 2, "OFF" ); } else CHAPTER 7 / Win32 COM Object Client APIs 279

Win32 IRWClientDialingEntry API ResourceType (Continued)

Example (Continued) { pList->SetItemText( Item, 2, "N/A" ); } ... } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "General Error" ); }

Win32 IRWClientDialingEntry API ReadOnly Description Gets the flag that determines if this dialing entry can be modified by the RemoteWare Client.

IDL Synopsis [propget] HRESULT ReadOnly( [out, retval] VARIANT_BOOL* pReadOnly ); Parameters [out, retval] pReadOnly Dialing entry Read Only flag. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. 280 RemoteWare API Manual

Win32 IRWClientDialingEntry API ReadOnly (Continued)

Example try { IRWClientPtr pClient( __uuidof( RWClient ) ); IRWClientDialingEntryPtr pEntry; IRWClientDialingDirectoryPtr pDirectory;

... pDirectory = pClient; CString strEntryName = pList->GetItemText(pos, 0); _bstr_t EntryName( strEntryName ); pDirectory->GetEntry( EntryName, &pEntry ); if (pEntry->GetReadOnly() == VARIANT_TRUE) { AfxMessageBox( "Entry is read only!" ); } else { ... } } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "General Error" ); } CHAPTER 7 / Win32 COM Object Client APIs 281

Win32 IRWClientDialingEntry API SetAsDefaultEntry Description Sets this dialing entry to be the default resource. This entry will be used by the RemoteWare Client for all incoming and outgoing calls.

IDL Synopsis HRESULT SetAsDefaultEntry ( ) Parameters None Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Example try { IRWClientDialingEntryPtr pEntry; ... CNewDlg dlg; int ret = dlg.DoModal(); if ( ret == IDOK ) { // Set Entry Name _bstr_t EntryName( dlg.m_strEntryName ); pEntry->PutName(EntryName); ... if ( dlg.IsDefault() == VARIANT_TRUE ) pEntry->SetAsDefaultEntry(); } } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "General Error" ); } 282 RemoteWare API Manual

Win32 IRWClientDialingEntry API WorkObjectSelection Description Gets an interface pointer to the work object list for the selected dialing entry.

IDL Synopsis HRESULT WorkObjectSelection( [out, retval] IUnknown** ppUnkRWClientWOSelection ); Parameters [out, retval] An interface pointer to the work object list of the selected dialing ppUnkRWClientWO entry, or NULL if the method call failed. Selection Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Example try { IRWClientWOSelectionPtr pSel; IRWClientDialingEntryPtr pEntry; IRWClientDialingDirectoryPtr pDirectory; VARIANT_BOOL bSelected; VARIANT_BOOL bDefault; IRWClientPtr pClient( __uuidof( RWClient ) ); ... pDirectory = pClient; pDirectory->GetEntry( EntryName, &pEntry ); pSel = pEntry->WorkObjectSelection(); CListBox* pWOList = (CListBox*) GetDlgItem( IDC_WOLIST ); CHAPTER 7 / Win32 COM Object Client APIs 283

Win32 IRWClientDialingEntry API WorkObjectSelection (Continued)

Example (Continued) for ( long i = 0; i < pSel->GetWorkObjectCount(); i++ ) { pWOList->AddString(pSel->WorkObject( i, &bSelected, &bDefault )); } ... } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "General Error" ); } 284 RemoteWare API Manual

IRWClientSessionStatus API Methods The IRWClientSessionStatus interface provides access to information about the current status of the RemoteWare session, such as the current executing command, session start and end time, and the number of bytes transferred for the session. IRWClientSessionStatus implements the RWClient coclass and is a user createable interface.

Highlights

• Implements coclass: RWClient. • Creatable? Yes. The following table summarizes the IRWClientSessionStatus API methods: Table 28. IRWClientSessionStatus API methods Method Name Description

SessionStatus Gets an interface pointer to the workobject list for the selected dialing entry. StartTime Gets the start time of the last RemoteWare session. EndTime Gets the end time of the last RemoteWare session. ServerSerialNumber Gets the serial number for the RemoteWare Server used in the last session. ServerName Gets the name the of the RemoteWare Server for the last session. CommandExecuting Gets the current command that the RemoteWare Client is executing. FileTransferring Gets the name of the file and the size of the file currently being transferred. FileBytesTransferred Gets the name and size of the file currently being transferred. InQTotalMessages Gets the total number and size of the messages that the message queue is expecting to receive. InQBytesTransferred Gets the total number of bytes received by the message queue. InQCurrentMessage If a message is currently being transferred to the RemoteWare Client’s incoming message queue, gets the number and size of that message. InQCurrentMessageBytes If a message is currently being transferred to the RemoteWare Transferred Client’s incoming message queue, gets the number of bytes in that message that have been received. InQMAPIMessagesTransferred Gets the number of MAPI messages transferred into the Client’s in queue. CHAPTER 7 / Win32 COM Object Client APIs 285

Table 28. IRWClientSessionStatus API methods (Continued) Method Name Description

OutQTotalMessages Gets the total number and size of messages that the message queue is expecting to send. OutQBytesTransferred Gets the total number of bytes sent from the Client in the current session. OutQCurrentMessage Gets the total number of bytes that have been sent from the Client in this session. OutQCurrentMessageBytes Gets the number of bytes transferred for the current message. Transferred OutQMAPIMessages The number of MAPI mail messages transferred from the Client’s in Transferred queue. 286 RemoteWare API Manual

Win32 IRWClientSessionStatus API SessionStatus Description Gets an interface pointer to the work object list for the selected dialing entry.

IDL Synopsis [propget] HRESULT SessionStatus( [out, retval] RWC_Session_e* pSessionStatus ); Parameters [out, retval] Status of the session. pSessionStatus For the definition and values for these enumerations, see “Enumerations and Structures” on page 418. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Example try { RWC_Session_e Status; IRWClientSessionStatusPtr pSession; IRWClientPtr pClient( __uuidof( RWClient ) ); ... pSession = pClient; Status = pSession->GetSessionStatus(); if (Status = RWCSS_NONE) { // Get last session result from log IRWClientSessionResultLogPtr pLog; pLog = pSession; long nLogCount; nLogCount = pLog->GetTotalEntries(); CHAPTER 7 / Win32 COM Object Client APIs 287

Win32 IRWClientSessionStatus API SessionStatus (Continued)

Example (Continued) // get last entry's status BSTR strStatus; Status = pLog->Getstatus(nLogCount - 1, &strStatus); } } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "General Error" ); }

Win32 IRWClientSessionStatus API StartTime Description Gets the start time of the last RemoteWare session.

IDL Synopsis [propget] HRESULT StartTime( [out, retval] DATE* pStartTime ); Parameters [out, retval] pStartTime Start time of the last session. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. 288 RemoteWare API Manual

Win32 IRWClientSessionStatus API StartTime (Continued)

Example try { IRWClientSessionStatusPtr pSession; IRWClientPtr pClient( __uuidof( RWClient ) ); ... pSession = pClient; COleDateTime timeStart(pSession ->GetStartTime()); CString strTime = "Session Started on " + timeStart.Format(); ... } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "General Error" ); }

Win32 IRWClientSessionStatus API EndTime Description Gets the end time of the last RemoteWare session.

IDL Synopsis [propget] HRESULT EndTime( [out, retval] DATE* pEndTime ); Parameters [out, retval] pStartTime End time of the last session. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. CHAPTER 7 / Win32 COM Object Client APIs 289

Win32 IRWClientSessionStatus API EndTime (Continued)

Example try { IRWClientSessionStatusPtr pSession; IRWClientPtr pClient( __uuidof( RWClient ) ); ... pSession = pClient; COleDateTime timeEnd(pSession ->GetEndTime()); CString strTime = "Session Started on " + timeEnd.Format(); ... } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "General Error" ); }

Win32 IRWClientSessionStatus API ServerSerialNumber Description Gets the serial number for the RemoteWare Server used in the last session.

IDL Synopsis [propget] HRESULT ServerSerialNumber( [out, retval] long* pSerialNumber ); Parameters [out, retval] The RemoteWare Server serial number. pSerialNumber Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. 290 RemoteWare API Manual

Win32 IRWClientSessionStatus API ServerSerialNumber (Continued)

Example try { IRWClientSessionStatusPtr pSession; IRWClientPtr pClient( __uuidof( RWClient ) ); ... pSession = pClient; long lSerial = pSession-> GetServerSerialNumber(); char szSerial[80]; sprintf(szSerial, "Server Serial Number: %ld\n", lSerial); AfxMessageBox(szSerial); ... } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "General Error" ); }

Win32 IRWClientSessionStatus API ServerName Description Gets the name the of the RemoteWare Server for the last session.

IDL Synopsis [propget] HRESULT ServerName( [out, retval] BSTR* ppName ); Parameters [out, retval] ppName The RemoteWare Server name. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. CHAPTER 7 / Win32 COM Object Client APIs 291

Win32 IRWClientSessionStatus API ServerName (Continued)

Example try { CStatic* pServerText = (CStatic*) GetDlgItem( IDC_SERVER ); IRWClientSessionStatusPtr pSession; IRWClientPtr pClient( __uuidof( RWClient ) ); ... pSession = pClient; pServerText->SetWindowText(pSession ->GetServerName()); ... } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "General Error" ); }

Win32 IRWClientSessionStatus API CommandExecuting Description Gets the current command that the RemoteWare Client is executing.

IDL Synopsis [propget] HRESULT CommandExecuting ( [out] BSTR* ppSWOExecuting, [out, retval] RWC_Command_e* pCommand ); Parameters [out] ppSWOExecuting Name of the executing work object [out, retval] Type of executing command. pCommand Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. 292 RemoteWare API Manual

Win32 IRWClientSessionStatus API CommandExecuting (Continued)

Example try { IRWClientSessionStatusPtr pSession; IRWClientPtr pClient( __uuidof( RWClient ) ); ... pSession = pClient; BSTR strCommand; pSession->GetCommandExecuting( &strCommand ); CString strcom( strCommand ); SetDlgItemText( IDC_EDIT_COMMAND, strcom ); ... } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "General Error" ); }

Win32 IRWClientSessionStatus API FileTransferring Description Gets the name of the file and the size of the file currently being transferred.

IDL Synopsis [propget] HRESULT FileTransferring ( [out] long* pFileBytes, [out, retval] BSTR* ppFileName ); Parameters [out] ppFileBytes The size of the file. [out, retval] The name of the file. pFileName Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. CHAPTER 7 / Win32 COM Object Client APIs 293

Win32 IRWClientSessionStatus API FileTransferring (Continued)

Example try{ IRWClientSessionStatusPtr pSession; IRWClientPtr pClient( __uuidof( RWClient ) ); ... long lTotalSize = 0; _bstr_t strFile; strFile = pSession-> GetFileTransferring(&lTotalSize); ... } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "General Error" ); } 294 RemoteWare API Manual

Win32 IRWClientSessionStatus API FileBytesTransferred Description Gets the name and size of the file currently being transferred.

IDL Synopsis [propget] HRESULT FileTransferring ( [out] long* pFileBytes, [out, retval] BSTR* ppFileName ); Parameters [out, retval] Number of bytes transferred. pBytesTransferred Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Example try { IRWClientSessionStatusPtr pSession; IRWClientPtr pClient( __uuidof( RWClient ) ); ... long lTotalSize = 0; _bstr_t strFile; strFile = pSession-> GetFileTransferring(&lTotalSize); CString Bytes; Bytes.Format( "%ld", pSession-> GetFileBytesTransferred()); ... } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "General Error" ); } CHAPTER 7 / Win32 COM Object Client APIs 295

Win32 IRWClientSessionStatus API InQTotalMessages Description Gets the total number and size of the messages that the message queue is expecting to receive.

IDL Synopsis propget] HRESULT InQTotalMessages ( [out] long* pTotalBytes, [out, retval] long* pTotalMessages ); Parameters [out] pTotalBytes Number of bytes in messages. [out, retval] Number of messages. pTotalMessages Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Example try { long lINQTotalBytes; long lINQTotal; long lOUTQTotalBytes; long lOUTQTotal; IRWClientSessionStatusPtr pSession; IRWClientPtr pClient( __uuidof( RWClient ) ); pSession = pClient; lINQTotal = pSession-> GetInQTotalMessages(&lINQTotalBytes); lOUTQTotal = pSession-> GetOutQTotalMessages(&lOUTQTotalBytes); ... } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "General Error" ); } 296 RemoteWare API Manual

Win32 IRWClientSessionStatus API InQBytesTransferred Description Gets the total number of bytes received by the message queue.

IDL Synopsis [propget] HRESULT InQBytesTransferred ( [out, retval] long* pBytesTransferred ); Parameters [out, retval] Total number of bytes transferred for messages in the incoming pBytesTransferred message queue. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Example try { long lINQTotalBytesTransferred; long lOUTQTotalBytesTransferred; IRWClientSessionStatusPtr pSession; IRWClientPtr pClient( __uuidof( RWClient ) ); pSession = pClient; lINQTotalBytesTransferred = pSession-> GetInQBytesTransferred(); lOUTQTotalBytesTransferred = pSession-> GetOutQBytesTransferred(); } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "General Error" ); }

Win32 IRWClientSessionStatus API InQCurrentMessage Description If a message is currently being transferred to the RemoteWare Client’s incoming message queue, get the number and size of that message. CHAPTER 7 / Win32 COM Object Client APIs 297

Win32 IRWClientSessionStatus API InQCurrentMessage (Continued)

IDL Synopsis propget] HRESULT InQCurrentMessage( [out] long* pMessageSize, [out, retval] long* pMessage ); Parameters [out] pMessageSize Size of the message. [out, retval] pMessage Number of the message currently in the Client’s incoming message queue. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Example try { long lINQCurrentTotalSize; long lINQCurrent; long lOUTQCurrentTotalSize; long lOUTQCurrent; IRWClientSessionStatusPtr pSession; IRWClientPtr pClient( __uuidof( RWClient ) ); pSession = pClient; lINQCurrent = pSession->GetInQCurrentMessage (&lINQCurrentTotalSize); lOUTQCurrent = pSession->GetOutQCurrentMessage (&lOUTQCurrentTotalSize); ... } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "General Error" ); } 298 RemoteWare API Manual

Win32 IRWClientSessionStatus API InQCurrentMessageBytesTransferred Description If a message is currently being transferred to the RemoteWare Client’s incoming message queue, gets the number of bytes in that message that have been received.

IDL Synopsis [propget] HRESULT InQCurrentMessageBytesTransferred ( [out, retval] long* pBytesTransferred ); Parameters [out, retval] Number of bytes that have been transferred in the current message. pBytesTransferred Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Example try { long lINQCurrentBytesTransferred; long lOUTQCurrentBytesTransferred; IRWClientSessionStatusPtr pSession; IRWClientPtr pClient( __uuidof( RWClient ) ); pSession = pClient; ... lINQCurrentBytesTransferred = pSession-> GetInQCurrentMessageBytesTransferred(); lOUTQCurrentBytesTransferred = pSession-> GetOutQCurrentMessageBytesTransferred(); ... } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "General Error" ); } CHAPTER 7 / Win32 COM Object Client APIs 299

Win32 IRWClientSessionStatus API InQMAPIMessagesTransferred Description Gets the number of MAPI messages transferred into the Client’s in queue.

IDL Synopsis [propget] HRESULT InQMAPIMessagesTransferred( [out, retval] long* pTransferred ); Parameters [out, retval] Number of mail messages transferred into the Client’s in queue. pTransferred Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. Example try { long lINQTotalMapiMsgs; long lOUTQTotalMapiMsgs;

IRWClientSessionStatusPtr pSession; IRWClientPtr pClient( __uuidof( RWClient ) ); pSession = pClient; ... lINQTotalMapiMsgs = pSession-> GetInQMAPIMessagesTransferred(); lOUTQTotalMapiMsgs = pSession-> GetOutQMAPIMessagesTransferred(); } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "General Error" ); } 300 RemoteWare API Manual

Win32 IRWClientSessionStatus API OutQTotalMessages Description Gets the total number and size of messages that the message queue is expecting to send.

IDL Synopsis [propget] HRESULT OutQTotalMessages ( [out] long* pTotalBytes, [out, retval] long* pTotalMessages ); Parameters [out] pTotalBytes Number of bytes in messages to be sent from the Client. [out, retval] Number of mail messages to be sent from the Client. pTotalMessages Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Example try { long lINQTotalBytes; long lINQTotal; long lOUTQTotalBytes; long lOUTQTotal; IRWClientSessionStatusPtr pSession; IRWClientPtr pClient( __uuidof( RWClient ) ); pSession = pClient; ... lINQTotal = pSession-> GetInQTotalMessages(&lINQTotalBytes); lOUTQTotal = pSession-> GetOutQTotalMessages(&lOUTQTotalBytes); ... } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "General Error" ); } CHAPTER 7 / Win32 COM Object Client APIs 301

Win32 IRWClientSessionStatus API OutQBytesTransferred Description Gets the total number of bytes sent from the Client in the current session.

IDL Synopsis [propget] HRESULT OutQBytesTransferred( [out, retval] long* pBytesTransferred ); Parameters [out, retval] Number of bytes that have been sent from the Client in this session. pBytesTransferred Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Example try { long lINQTotalBytesTransferred; long lOUTQTotalBytesTransferred; IRWClientSessionStatusPtr pSession; IRWClientPtr pClient( __uuidof( RWClient ) ); pSession = pClient; ... lINQTotalBytesTransferred = pSession-> GetInQBytesTransferred(); lOUTQTotalBytesTransferred = pSession-> GetOutQBytesTransferred(); ... } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "General Error" ); } 302 RemoteWare API Manual

Win32 IRWClientSessionStatus API OutQCurrentMessage Description Gets the total number of bytes that have been sent from the Client in this session.

IDL Synopsis [propget] HRESULT OutQCurrentMessage( [out] long* pMessageSize, [out, retval] long* pMessage ); Parameters [out] pMessageSize Size of message being sent to the Server. [out, retval] pMessage Number of the message transferring to Server. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Example try { long lINQCurrentTotalSize; long lINQCurrent; long lOUTQCurrentTotalSize; long lOUTQCurrent; IRWClientSessionStatusPtr pSession; IRWClientPtr pClient( __uuidof( RWClient ) ); pSession = pClient; ... lINQCurrent = pSession->GetInQCurrentMessage (&lINQCurrentTotalSize); lOUTQCurrent = pSession->GetOutQCurrent Message(&lOUTQCurrentTotalSize); ... } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "General Error" ); } CHAPTER 7 / Win32 COM Object Client APIs 303

Win32 IRWClientSessionStatus API OutQCurrentMessageBytesTransferred Description Gets the number of bytes transferred for the current message.

IDL Synopsis [propget] HRESULT OutQCurrentMessageBytesTransferred ( [out, retval] long* pBytesTransferred ); Parameters [out, retval] Number of bytes in messages that have been transferred. pBytesTransferred Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Example try { long lINQCurrentBytesTransferred; long lOUTQCurrentBytesTransferred; IRWClientSessionStatusPtr pSession; IRWClientPtr pClient( __uuidof( RWClient ) ); pSession = pClient; ... lINQCurrentBytesTransferred = pSession-> GetInQCurrentMessageBytesTransferred(); lOUTQCurrentBytesTransferred = pSession-> GetOutQCurrentMessageBytesTransferred(); ... } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "General Error" ); }

Win32 IRWClientSessionStatus API OutQMAPIMessagesTransferred Description The number of MAPI mail messages transferred from the Client’s in queue. 304 RemoteWare API Manual

Win32 IRWClientSessionStatus API OutQMAPIMessagesTransferred (Continued)

IDL Synopsis [propget] HRESULT OutQMAPIMessagesTransferred ( [out, retval] long* pTransferred ); Parameters [out, retval] The number of mail messages that have been transferred from the pTransferred Client’s in queue. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Example try { long lINQTotalMapiMsgs; long lOUTQTotalMapiMsgs; IRWClientSessionStatusPtr pSession; IRWClientPtr pClient( __uuidof( RWClient ) ); pSession = pClient; ... lINQTotalMapiMsgs = pSession-> GetInQMAPIMessagesTransferred(); lOUTQTotalMapiMsgs = pSession-> GetOutQMAPIMessagesTransferred(); ... } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "General Error" ); } CHAPTER 7 / Win32 COM Object Client APIs 305

IRWClientTextExplanation API Methods The IRWClientTextExplanation interface allows text strings describing RemoteWare errors and statuses to be retrieved. This is helpful in presenting information to the user of an application. The IRWClientTextExplanation interface implements the RWClient interface and is a user creatable interface.

Overview

• Implements: RWClient. • Creatable? Yes. The following table summarizes the IRWClientTextExplanation API methods: Table 29. IRWClientTextExplanation API methods Method Name Description

StatusExplanation Translates the RemoteWare Client’s status into a text string. AlertExplanation Translates the RemoteWare Client’s alerts into a text string. SessionResult Translates the RemoteWare Client’s status into a text string. LongSessionResult Translates a RemoteWare session’s status into a detailed (verbose) text string. SessionError Translates a RemoteWare session error into a text string. ResourceName Translates a RemoteWare resource name into a text string. ResourceStatusExplanation Translates a RemoteWare resource status into a text string. ResourceError Translates a RemoteWare resource error into a text string. 306 RemoteWare API Manual

Win32 IRWClientTextExplanation API StatusExplanation Description Translates the RemoteWare Client’s status into a text string.

IDL Synopsis [propget] HRESULT StatusExplanation ( [in] long statusmask, [out, retval] BSTR* ppText ); Parameters [in] statusmask Client status bit mask. [out, retval] ppText Text string describing Client status bit mask. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Win32 IRWClientTextExplanation API AlertExplanation Description Translates the RemoteWare Client’s alerts into a text string.

IDL Synopsis [propget] HRESULT AlertExplanation( [in] RWC_Alert_e alert, [out, retval] BSTR* ppText ); Parameters [in] alert Alert for which the text will be retrieved. [out, retval] ppText Alert text for the requested alert.

For the definition and values for these enumerations, see “Enumerations and Structures” on page 418. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. CHAPTER 7 / Win32 COM Object Client APIs 307

Win32 IRWClientTextExplanation API AlertExplanation (Continued)

Example try { IRWClientPtr pClient( __uuidof( RWClient ) ); IRWClientTextExplanationPtr pText = pClient; ... CListBox* pAlertBox = (CListBox*) GetDlgItem( IDC_ALERTMASK ): pAlertBox->ResetContent(); RWC_Alert_e AlertArray[5] = { RWCA_RESOURCEERROR, RWCA_ESDAVAILABLE, RWCA_ESDDISABLED, RWCA_AUTOANSWEROFF, RWCA_CLIENTNOTIFICATION }; long AlertMask = pClient->GetAlerts(); for( i = 0; i < 5; i++ ) { if ( (AlertMask & AlertArray[i] ) != 0 ) pAlertBox->AddString(pText->GetAlert Explanation( AlertArray[i] ) ); } ... } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "General Error" ); } 308 RemoteWare API Manual

Win32 IRWClientTextExplanation API SessionResult Description Translates the RemoteWare Client’s status into a text string.

IDL Synopsis [propget] HRESULT SessionResult ( [in] RWC_Session_e session, [in] RWC_ResourceType_e resource, [in] long ResourceError, [out, retval] BSTR* ppText ); Parameters [in] session Session result. [in] resource Resource type. [in] ResourceError Resource error number. [out, retval] ppText Text string describing the entered session.

For the definition and values for these enumerations, see “Enumerations and Structures” on page 418. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Win32 IRWClientTextExplanation API LongSessionResult Description Translates a RemoteWare session’s status into a detailed (verbose) text string.

IDL Synopsis [propget] HRESULT LongSessionResult ( [in] RWC_Session_e session, [in] RWC_ResourceType_e resource, [in] long ResourceError, [out, retval] BSTR* ppText ); Parameters [in] session Session result. [in] resource Resource type. [in] ResourceError Resource error number. CHAPTER 7 / Win32 COM Object Client APIs 309

Win32 IRWClientTextExplanation API LongSessionResult (Continued)

[out, retval] ppText Text string describing the entered session. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Example try { IRWClientPtr pClient( __uuidof( RWClient ) ); IRWClientSessionStatusPtr pSession = pClient; RWC_Session_e Status = pSession->GetSessionStatus(); if (Status = RWCSS_NONE) { // Get last session result from log IRWClientSessionResultLogPtr pLog = pSession; long nLogCount = pLog->GetTotalEntries(); // get last entry's status BSTR strStatus; Status = pLog->Getstatus(nLogCount - 1, &strStatus); } if ((Status != RWCSS_NONE) && (!m_bSessionStatusPosted)) { 310 RemoteWare API Manual

Win32 IRWClientTextExplanation API LongSessionResult (Continued)

Example (Continued) IRWClientTextExplanationPtr pExplanation = pSession; _bstr_t strSessionStatus; strSessionStatus = pExplanation-> GetLongSessionResult(Status, RWCRT_NONE, 0); if (Status != RWCSS_SUCCESSFUL) strSessionStatus = "Session failed because " + strSessionStatus; else strSessionStatus = "Session succeeded"; ... } } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "General Error" ); }

Win32 IRWClientTextExplanation API SessionError Description Translates a RemoteWare session error into a text string.

IDL Synopsis [propget] HRESULT SessionError ( [in] RWC_Session_e session, [in] RWC_ResourceType_e resource, [in] RWC_ResourceStatus_e status, [in] long ResourceError, [out, retval] BSTR* ppText ); CHAPTER 7 / Win32 COM Object Client APIs 311

Win32 IRWClientTextExplanation API SessionError (Continued)

Parameters [in] session Session result. [in] resource Resource type. [in] status Resource status. [in] ResourceError Resource error number. [out, retval] ppText Text string describing the entered session.

For the definition and values for these enumerations, see “Enumerations and Structures” on page 418. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Win32 IRWClientTextExplanation API ResourceName Description Translates a RemoteWare resource name into a text string.

IDL Synopsis [propget] HRESULT ResourceName ( [in] RWC_ResourceType_e resource, [out, retval] BSTR* ppText ); Parameters [in] resource Resource type. [out, retval] ppText Resource name.

For the definition and values for these enumerations, see “Enumerations and Structures” on page 418. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. 312 RemoteWare API Manual

Win32 IRWClientTextExplanation API ResourceName (Continued)

Example try { RWC_ResourceStatus_e Status; long Error; IRWClientPtr pClient; pClient.CreateInstance( __uuidof(RWClient) ); RWC_ResourceType_e Type; Type = pClient->GetResourceStatus( &Error, &Status ); IRWClientTextExplanationPtr pText = pClient; SetDlgItemText( IDC_ERROR, pText-> GetResourceError( Type, Error ) ); SetDlgItemText( IDC_TYPE, pText-> GetResourceName( Type ) ); ... } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "General Error" ); } CHAPTER 7 / Win32 COM Object Client APIs 313

Win32 IRWClientTextExplanation API ResourceStatusExplanation Description Translates a RemoteWare resource status into a text string.

IDL Synopsis [propget] HRESULT ResourceStatusExplanation ( [in] RWC_ResourceStatus_e status, [out, retval] BSTR* ppText ); Parameters [in] status Resource status. [out, retval] ppText Text string for the resource status. [out, retval] ppText Text string describing the entered session. (continued) For the definition and values for these enumerations, see “Enumerations and Structures” on page 418. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Win32 IRWClientTextExplanation API ResourceError Description Translates a RemoteWare resource error into a text string.

IDL Synopsis [propget] HRESULT ResourceError ( [in] RWC_ResourceType_e resource, [in] long ResourceError, [out, retval] BSTR* ppText ); Parameters [in] resource Resource type. [in] ResourceError Resource error. [out, retval] ppText Text string for a resource error.

For the definition and values for these enumerations, see “Enumerations and Structures” on page 418. 314 RemoteWare API Manual

Win32 IRWClientTextExplanation API ResourceError (Continued)

Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Example try { RWC_ResourceStatus_e Status; RWC_ResourceType_e Type; long Error; IRWClientPtr pClient; pClient.CreateInstance( __uuidof(RWClient) ); ... Type = pClient->GetResourceStatus ( &Error, &Status ); IRWClientTextExplanationPtr pText = pClient; SetDlgItemText( IDC_ERROR, pText-> GetResourceError( Type, Error ) ); SetDlgItemText( IDC_TYPE, pText-> GetResourceName( Type ) ); ... } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "General Error" ); } CHAPTER 7 / Win32 COM Object Client APIs 315

IRWClientDialingDirectory API Methods The IRWClientDialingDirectory interface provides methods to manipulate dialing entries. This includes creating, deleting, retrieving, and enumerating dialing entries. The IRWClientDialingDirectory interface implements the RWClient coclass and is user creatable.

Overview

• Implements coclass: RWClient • Creatable? Yes The following table summarizes the IRWClientDialingDirectory API methods: Table 30. IRWClientDialingDirectory API methods Method Name Description

EnumerateEntryNames Gets an object that can enumerate the dialing directory entry names. CreateEntry Creates a new dialing directory entry. RemoveEntry Removes a new dialing directory entry. GetEntry Gets a dialing directory entry. 316 RemoteWare API Manual

Win32 IRWClientDialingDirectory API EnumerateEntryNames Description Gets an object that can enumerate the dialing directory entry names.

IDL Synopsis HRESULT EnumerateEntryNames ( [out] IRWClientDialingEntryCollection** ppDirectory ); Parameters [out] ppDirectory IRWClientDialingEntryCollection interface pointer. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Example try { CListCtrl* pList = (CListCtrl*) GetDlgItem( IDC_ENTRY_LIST ); IRWClientDialingDirectoryPtr pDirectory; IRWClientDialingEntryCollectionPtr pCol; IEnumVARIANTPtr pEnum; VARIANT var = {0}; ULONG Fetched; int Item = 0; IRWClientPtr pClient( __uuidof( RWClient ) ); ... pDirectory = pClient; pDirectory->EnumerateEntryNames( &pCol ); pEnum = pCol->Get_NewEnum(); while ( S_OK == pEnum->Next( 1, &var, &Fetched ) ) { CHAPTER 7 / Win32 COM Object Client APIs 317

Win32 IRWClientDialingDirectory API EnumerateEntryNames (Continued)

Example (Continued) ASSERT( var.vt == VT_BSTR ); _bstr_t EntryName( var.bstrVal ); pDirectory->GetEntry( EntryName, &pEntry ); pList->InsertItem( Item, pEntry->GetName() ); ... Item++; ::VariantClear( &var ); } } catch( const _com_error& e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox("General Error"); }

Win32 IRWClientDialingDirectory API CreateEntry Description Creates a new dialing directory entry.

IDL Synopsis HRESULT CreateEntry ( [in] RWC_ResourceType_e ResourceType, [in] BSTR pName, [out] IRWClientDialingEntry** ppEntry ); Parameters [in] ResourceType Resource type. [in] pName Dialing directory entry name. [out] ppEntry COM interface pointer to the dialing directory entry.

For the definition and values for these enumerations, see “Enumerations and Structures” on page 418. 318 RemoteWare API Manual

Win32 IRWClientDialingDirectory API CreateEntry (Continued)

Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. Example try { IRWClientDialingDirectoryPtr pDirectory; IRWClientDialingEntryPtr pEntry;

IRWClientPtr pClient ( __uuidof( RWClient ) ); _bstr_t name("CLIENTNAME"); pClient->PutClientName( name ); pDirectory = pClient; HRESULT hr = pDirectory->CreateEntry( RWCRT_TCPIP, EntryName, &pEntry ); if (hr == S_FALSE) { AfxMessageBox("Invalid Entry Name"); } pEntry->PutEnableAutoAnswer( VARIANT_TRUE ); pEntry->PutDisableESD( VARIANT_TRUE ); _bstr_t Address( "LOCALHOST" ); pEntry->PutAddress( Address ); pEntry->SetAsDefaultEntry(); } catch(const _com_error e) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "General Error" ); } CHAPTER 7 / Win32 COM Object Client APIs 319

Win32 IRWClientDialingDirectory API RemoveEntry Description Removes a new dialing directory entry.

IDL Synopsis HRESULT RemoveEntry ( [in] BSTR pName ) Parameters [in] pName Name of dialing entry to remove from the directory. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Example try { CListCtrl* pList = (CListCtrl*) GetDlgItem( IDC_ENTRY_LIST ); IRWClientDialingDirectoryPtr pDirectory; IRWClientDialingEntryPtr pEntry; IRWClientPtr pClient( __uuidof( RWClient ) ); _bstr_t name("CLIENTNAME"); pClient->PutClientName( name ); pDirectory = pClient; int pos = pList->GetNextItem( -1, LVNI_SELECTED ); if (pos == -1) AfxMessageBox( "No entries selected!" ); else { while (pos != -1) { CString ItemName = pList->GetItemText( pos, 0 ); 320 RemoteWare API Manual

Win32 IRWClientDialingDirectory API RemoveEntry (Continued)

Example (Continued) _bstr_t EntryName( ItemName ); HRESULT hr = pDirectory->RemoveEntry( EntryName ); if ( FAILED(hr) ) AfxMessageBox( "Error in call RemoveEntry" ); pos = pList->GetNextItem( pos, LVNI_SELECTED ); } } } catch(const _com_error e) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "General Error" ); }

Win32 IRWClientDialingDirectory API GetEntry Description Gets a dialing directory entry.

IDL Synopsis HRESULT GetEntry ( [in] BSTR pName, [out] struct IRWClientDialingEntry ** ppEntry ) Parameters [in] pName Dialing directory entry name. [out] ppEntry COM interface pointer to the dialing directory entry. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. CHAPTER 7 / Win32 COM Object Client APIs 321

Win32 IRWClientDialingDirectory API GetEntry (Continued)

Example try { CListCtrl* pList = (CListCtrl*) GetDlgItem( IDC_ENTRY_LIST ); IRWClientDialingDirectoryPtr pDirectory; IRWClientDialingEntryPtr pEntry; _bstr_t EntryName; _bstr_t name; int Item = 0; IRWClientPtr pClient( __uuidof( RWClient ) ); ... pClient->PutClientName( name ); pDirectory = pClient; pDirectory->GetEntry( EntryName, &pEntry ); pList->InsertItem( Item, pEntry->GetName() ); pList->SetItemText( Item, 1, pEntry ->GetAddress() ); ... } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "General Error" ); } 322 RemoteWare API Manual

IRWClientSessionResultLog API Methods The IRWClientSessionResultLog interface provides access to the RemoteWare Client session result log. This log contains information such as the date and duration of the session, type of resource used to connect, the status of the session, and other important session information. The IRWClientSessionResultLog interface implements the RWClient coclass and is user creatable.

Overview

• Implements: RWClient. • Creatable? Yes. The following table summarizes the IRWClientSessionResultLog API methods: Table 31. IRWClientSessionResultLog API methods Method Name Description

TotalEntries Gets the number of entries in the RemoteWare session result log. Date Gets the date for a particular entry in the RemoteWare session result log. Duration Gets the duration for a particular entry in the RemoteWare session result log. ServerOriginated Gets a flag that indicates if the Server initiated the RemoteWare session. ServerName For a particular entry in the RemoteWare session result log, gets the name of the RemoteWare Server to which the Client connected. ServerSerialNumber Gets the RemoteWare Server serial number for a session. Status Gets the status of a RemoteWare session. Resource Gets the type of resource that was used for the RemoteWare session. Address Gets the network address that was used for a RemoteWare session result log entry. RefreshLog Refreshes the RemoteWare session result log. CHAPTER 7 / Win32 COM Object Client APIs 323

Win32 IRWClientSessionResultLog API TotalEntries Description Gets the number of entries in the RemoteWare session result log.

IDL Synopsis [propget] HRESULT TotalEntries ( [out, retval] long* pNumEntries ); Parameters [out, retval] Number of entries in session log. pNumEntries Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. Example try { CListCtrl* pList = (CListCtrl*) GetDlgItem( IDC_LOG ); IRWClientSessionResultLogPtr pLog; IRWClientPtr pClient( __uuidof( RWClient ) );

_bstr_t name( "CLIENTNAME" ); pClient->PutClientName( name ); pLog = pClient; long TotalEntries = pLog->GetTotalEntries(); for ( long i = 0; i < TotalEntries; i++ ) { BSTR status; pLog->Getstatus( i, &status); CString strStatus( status ); pList->InsertItem( i, strStatus ); ... } } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "Error Reading Log" ); } 324 RemoteWare API Manual

Win32 IRWClientSessionResultLog API Date Description Gets the date for a particular entry in the RemoteWare session result log.

IDL Synopsis [propget] HRESULT Date( [in] long Index, [out, retval] DATE* pDate ); Parameters [in] Index Entry for which the date will be retrieved. [out, retval] pDate The date of the submitted entry. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Example try { CListCtrl* pList = (CListCtrl*) GetDlgItem( IDC_LOG ); IRWClientSessionResultLogPtr pLog; IRWClientPtr pClient( __uuidof( RWClient ) ); _bstr_t name( "CLIENTNAME" ); pClient->PutClientName( name ); pLog = pClient; long TotalEntries = pLog->GetTotalEntries(); for ( long i = 0; i < TotalEntries; i++ ) { // Get and insert Session Status BSTR status; pLog->Getstatus( i, &status); CString strStatus( status ); pList->InsertItem( i, strStatus ); ... //Get and insert Date COleDateTime time = pLog->GetDate( i ); CString date; date.Format( "%d/%d/%d", time.GetMonth(), time.GetDay(), time.GetYear() ); pList->SetItemText( i, 7, date ); } CHAPTER 7 / Win32 COM Object Client APIs 325

Win32 IRWClientSessionResultLog API Date (Continued)

Example (Continued) } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "Error Reading Log" ); }

Win32 IRWClientSessionResultLog API Duration Description Gets the duration for a particular entry in the RemoteWare session result log.

IDL Synopsis [propget] HRESULT Date( [in] long Index, [out, retval] long* pSeconds ); Parameters [in] Index Session log entry. [out, retval] pSeconds Session duration. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. 326 RemoteWare API Manual

Win32 IRWClientSessionResultLog API Duration (Continued)

Example try { CListCtrl* pList = (CListCtrl*) GetDlgItem( IDC_LOG ); IRWClientSessionResultLogPtr pLog; IRWClientPtr pClient( __uuidof( RWClient ) ); _bstr_t name( "CLIENTNAME" ); pClient->PutClientName( name ); pLog = pClient; long TotalEntries = pLog->GetTotalEntries(); for ( long i = 0; i < TotalEntries; i++ ) { // Get and insert Session Status BSTR status; pLog->Getstatus( i, &status); CString strStatus( status ); pList->InsertItem( i, strStatus ); ... //Get and insert Duration long duration = pLog->GetDuration( i ); CString strDuration; strDuration.Format( "%d", duration ); pList->SetItemText( i, 6, strDuration ); ... } } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "Error Reading Log" ); } CHAPTER 7 / Win32 COM Object Client APIs 327

Win32 IRWClientSessionResultLog API ServerOriginated Description Gets a flag that indicates if the Server initiated the RemoteWare session.

IDL Synopsis [propget] HRESULT ServerOriginated( [in] long Index, [out, retval] VARIANT_BOOL* pServerOriginated ); Parameters [in] Index Result log entry index. [out, retval] Session origination flag. If VARIANT_TRUE, then Server pServerOriginated originated the session. If VARIANT_FALSE, then Client originated the session. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. 328 RemoteWare API Manual

Win32 IRWClientSessionResultLog API ServerOriginated (Continued)

Example try { CListCtrl* pList = (CListCtrl*) GetDlgItem( IDC_LOG ); IRWClientSessionResultLogPtr pLog; IRWClientPtr pClient( __uuidof( RWClient ) ); _bstr_t name( "CLIENTNAME" ); pClient->PutClientName( name ); pLog = pClient; long TotalEntries = pLog->GetTotalEntries(); for ( long i = 0; i < TotalEntries; i++ ) { // Get and insert Session Status BSTR status; pLog->Getstatus( i, &status); pList->InsertItem( i, strStatus ); ... //Get and insert Originated if ( pLog->GetServerOriginated( i ) == VARIANT_TRUE ) pList->SetItemText( i, 3, "SERVER" ); else pList->SetItemText( i, 3, "CLIENT" ); ... } } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "Error Reading Log" ); } CString strStatus( status ); CHAPTER 7 / Win32 COM Object Client APIs 329

Win32 IRWClientSessionResultLog API ServerName Description For a particular entry in the RemoteWare session result log, get the name of the RemoteWare Server to which the Client connected.

IDL Synopsis [propget] HRESULT ServerName ( [in] long Index, [out, retval] BSTR* ppServerName ); Parameters [in] Index Result log entry index. [out, retval] Server connected to during session. pServerName Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Example try { CListCtrl* pList = (CListCtrl*) GetDlgItem( IDC_LOG ); IRWClientSessionResultLogPtr pLog; IRWClientPtr pClient( __uuidof( RWClient ) ); _bstr_t name( "CLIENTNAME" ); pClient->PutClientName( name ); pLog = pClient; long TotalEntries = pLog->GetTotalEntries(); for ( long i = 0; i < TotalEntries; i++ ) { // Get and insert Session Status BSTR status; pLog->Getstatus( i, &status); CString strStatus( status ); 330 RemoteWare API Manual

Win32 IRWClientSessionResultLog API ServerName (Continued)

Example (Continued) pList->InsertItem( i, strStatus ); ... //Get and insert Server Name pList->SetItemText( i, 2, pLog-> GetServerName( i ) ); ... } } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "Error Reading Log" ); }

Win32 IRWClientSessionResultLog API ServerSerialNumber Description Gets the RemoteWare Server serial number for a session.

IDL Synopsis [propget] HRESULT ServerSerialNumber ( [in] long Index, [out, retval] long* pSerialNumber ); Parameters [in] Index Session result log entry index. [out, retval] Server serial number. pSerialNumber Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. CHAPTER 7 / Win32 COM Object Client APIs 331

Win32 IRWClientSessionResultLog API ServerSerialNumber (Continued)

Example try { CListCtrl* pList = (CListCtrl*) GetDlgItem( IDC_LOG ); IRWClientSessionResultLogPtr pLog; IRWClientPtr pClient( __uuidof( RWClient ) ); _bstr_t name( "CLIENTNAME" ); pClient->PutClientName( name ); pLog = pClient; long TotalEntries = pLog->GetTotalEntries(); for ( long i = 0; i < TotalEntries; i++ ) { // Get and insert Session Status BSTR status; pLog->Getstatus( i, &status); CString strStatus( status ); pList->InsertItem( i, strStatus ); ... //Get and insert Server Serial long serial = pLog-> GetServerSerialNumber( i ); CString strSerial; strSerial.Format( "%d", serial ); pList->SetItemText( i, 4, strSerial ); ... } } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "Error Reading Log" ); } 332 RemoteWare API Manual

Win32 IRWClientSessionResultLog API Status Description Gets the status of a RemoteWare session.

IDL Synopsis [propget] HRESULT status ( [in] long Index, [out] BSTR* ppStatus, [out, retval] RWC_Session_e* pStatus ); Parameters [in] Index Session result log entry index. [out] BSTR* ppStatus Text string describing result log entry. [out, retval] pStatus Session result log entry status. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Example try { CListCtrl* pList = (CListCtrl*) GetDlgItem( IDC_LOG ); IRWClientSessionResultLogPtr pLog; IRWClientPtr pClient( __uuidof( RWClient ) ); _bstr_t name( "CLIENTNAME" ); pClient->PutClientName( name ); pLog = pClient; long TotalEntries = pLog->GetTotalEntries(); for ( long i = 0; i < TotalEntries; i++ ) { // Get and insert Session Status BSTR status; pLog->Getstatus( i, &status); CString strStatus( status ); CHAPTER 7 / Win32 COM Object Client APIs 333

Win32 IRWClientSessionResultLog API Status (Continued)

Example (Continued) pList->InsertItem( i, strStatus ); ... } } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "Error Reading Log" ); }

Win32 IRWClientSessionResultLog API Resource Description Gets the type of resource used for the RemoteWare session.

IDL Synopsis [propget] HRESULT resource ( [in] long Index, [out] long* pResourceError, [out, retval] RWC_ResourceType_e* pResourceType ); Parameters [in] Index Session result log entry index. [out] pResourceError Resource error for the session. [out, retval] Resource type. pResourceType Return values A Win32 HRESULT indicates the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. 334 RemoteWare API Manual

Win32 IRWClientSessionResultLog API Resource (Continued)

Example try { CListCtrl* pList = (CListCtrl*) GetDlgItem( IDC_LOG ); IRWClientSessionResultLogPtr pLog; IRWClientTextExplanationPtr pText; IRWClientPtr pClient( __uuidof( RWClient ) ); _bstr_t name( "CLIENTNAME" ); pClient->PutClientName( name ); pLog = pClient; pText = pClient; long TotalEntries = pLog->GetTotalEntries(); for ( long i = 0; i < TotalEntries; i++ ) { // Get and insert Session Status BSTR status; pLog->Getstatus( i, &status); CString strStatus( status ); pList->InsertItem( i, strStatus ); // Get and insert resource RWC_ResourceType_e res = pLog-> Getresource( i, &lError ); pList->SetItemText( i, 1, pText-> GetResourceName( res ) ); ... } } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "Error Reading Log" ); } CHAPTER 7 / Win32 COM Object Client APIs 335

Win32 IRWClientSessionResultLog API Address Description Gets the network address used for a RemoteWare session result log entry.

IDL Synopsis [propget] HRESULT Address ( [in] long Index, [out, retval] BSTR* ppAddress ); Parameters [in] Index Session result log entry index. [out, retval] ppAddress Server address. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Example try { IRWClientSessionResultLogPtr pLog; IRWClientPtr pClient( __uuidof( RWClient ) ); _bstr_t name( "CLIENTNAME" ); pClient->PutClientName( name ); pLog = pClient; long TotalEntries = pLog->GetTotalEntries(); for ( long i = 0; i < TotalEntries; i++ ) { // Get and insert Session Status BSTR status; pLog->Getstatus( i, &status); CString strStatus( status ); pList->InsertItem( i, strStatus ); ... 336 RemoteWare API Manual

Win32 IRWClientSessionResultLog API Address (Continued)

Example (Continued) //Get and insert Address pList->SetItemText( i, 5, pLog-> GetAddress( i ) ); ... } } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "Error Reading Log" ); }

Win32 IRWClientSessionResultLog API RefreshLog Description Refreshes the RemoteWare session result log.

IDL Synopsis HRESULT RefreshLog ( ) Parameters None Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. CHAPTER 7 / Win32 COM Object Client APIs 337

Win32 IRWClientSessionResultLog API RefreshLog (Continued)

Example try { IRWClientPtr pClient( __uuidof( RWClient ) ); _bstr_t name( "CLIENTNAME" ); pClient->PutClientName( name ); IRWClientSessionResultLogPtr pLog; pLog = pClient; pLog->RefreshLog(); OnSelchangeClientName(); } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "Error Connecting" ); } //Get and insert Address pList->SetItemText( i, 5, pLog-> GetAddress( i ) ); ... } } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "Error Reading Log" ); } 338 RemoteWare API Manual

IRWClientStatus API methods The IRWClientStatus interface provides a subset of Client functionality, encapsulating many of the methods found in other RemoteWare interfaces. It is useful in languages that can only access IDispatch interfaces. The IRWClientStatus interface implements the RWClient coclass and is user creatable. Since the method calls of this interface are very similar to method calls in other interfaces, examples have not been provided for most methods. If you are familiar with the RemoteWare APIs, you should have no problem using this interface.

Overview

• Implements: RWClient • Creatable? Yes. • Example: Specific examples are not provided, although other interfaces provide similar methods and may be consulted for information, as noted in in the following sections. The following table summarizes the IRWClientStatus API methods: Table 32. IRWClientStatus API methods Method Name Description

ClientName Gets the Client name. ClientName Sets the Client name. SessionStartTime Gets the start time of the last session. ClientStatus Gets the status of the RemoteWare Client. VerboseStatusText Gets a text string describing the status of the RemoteWare Client. CurrentServerName Gets the name of the RemoteWare Server. CurrentServerID Gets the RemoteWare Server ID. InstallPath Gets the installation path of the RemoteWare Client. Alerts Gets the Client’s active alerts. CurrentSWO Gets the name of the currently executing work object. CurrentCommand Gets the currently executing command. CurrentFileName Gets the name of the file currently being transferred. CurrentFileSize Gets the size of the file currently being transferred. CurrentBytesTransferred Gets the number of bytes that have been transferred for the current file. CHAPTER 7 / Win32 COM Object Client APIs 339

Table 32. IRWClientStatus API methods (Continued) Method Name Description

SessionEndTime Gets the session end time for the last RemoteWare session. InQTotalMessages Gets the total number of messages in the Client’s in queue. OutQTotalMessages Gets the number of messages in the Client’s out queue. InQTotalBytes Gets the number of bytes of the messages in the Client’s in queue. OUTQTotalBytes Gets the number of bytes of the messages in the Client’s out queue. INQTotalBytesTransferred Gets the number of bytes transferred for the messages in the in queue. OUTQTotalBytesTransferred Gets the number of bytes transferred for the messages in the out queue. InQCurrentMessage Gets the message currently being transferred in the Client’s in queue. OutQCurrentMessage Gets the message currently being transferred in the Client’s out queue. INQCurrentMessageBytes Gets the number of bytes in the the message currently being transferred in the Client’s in queue. OUTQCurrentMessageBytes Gets the number of bytes in the the message currently being transferred in the Client’s out queue. INQCurrentMessageBytes Gets the number of bytes transferred for the current message in the Transferred Client’s in queue. OUTQCurrentMessageBytes Gets the number of bytes transferred for the current message in the Transferred Client’s out queue. InQMAPIMessagesTransferred Gets the total number of mail messages transferred into the Client’s in queue. OutQMAPIMessages Gets the total number of mail messages transferred from the Client’s Transferred in queue. PlayLastSessionOnNameChange Gets the PlayLastSessionOnNameChange flag for the RemoteWare Client. PlayLastSessionOnNameChange Sets the PlayLastSessionOnNameChange flag for the RemoteWare Client. LastSessionStatus Gets the status of the last RemoteWare session. LastSessionStatusText Gets a text string describing the status of the last RemoteWare session. Load Loads the RemoteWare kernel. Unload Unloads the RemoteWare kernel. Connect Initiates a connection to the RemoteWare Server. 340 RemoteWare API Manual

Table 32. IRWClientStatus API methods (Continued) Method Name Description

Initialize Establishes or re-establishes a link with the RemoteWare kernel to monitor activity. ReleasePort Releases the communications port. Cancel Cancels the current RemoteWare session. PendingOperations Gets a bit mask describing pending operations for the RemoteWare session. ApplyESD Applies the Electronic Software Distribution (if any). RefreshAlerts Refreshes the RemoteWare Client alerts. CHAPTER 7 / Win32 COM Object Client APIs 341

Win32 IRWClientStatus API ClientName Description Gets the Client name.

IDL Synopsis [propget] HRESULT ClientName( [out, retval] BSTR* pVal ); Parameters [out, retval] pVal RemoteWare Client name. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. Example For an example of a similar method, see “Win32 IRWClient API” on page 243.

Win32 IRWClientStatus API ClientName Description Sets the Client name.

IDL Synopsis [propput] HRESULT ClientName( [in] BSTR pVal ); Parameters [in] pVal RemoteWare Client name. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. Example For an example of a similar method, see “Win32 IRWClient API” on page 244. 342 RemoteWare API Manual

Win32 IRWClientStatus API SessionStartTime Description Gets the start time of the last session.

IDL Synopsis [propget] HRESULT SessionStartTime( [out, retval] DATE* pVal ); Parameters [out, retval] pVal RemoteWare session start time. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Win32 IRWClientStatus API ClientStatus Description Gets the status of the RemoteWare Client.

IDL Synopsis [propget] HRESULT ClientStatus( [out, retval] short* pVal ); Parameters [out, retval] pVal RemoteWare Client status. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. Example For an example of a similar method, see “Win32 IRWClient API” on page 248. CHAPTER 7 / Win32 COM Object Client APIs 343

Win32 IRWClientStatus API VerboseStatusText Description Gets a text string describing the status of the RemoteWare Client.

IDL Synopsis [propget] HRESULT VerboseStatusText( [out, retval] BSTR* pVal ); Parameters [out, retval] pVal Text string describing the status of the Client. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Win32 IRWClientStatus API CurrentServerName Description Gets the name of the RemoteWare Server.

IDL Synopsis [propget] HRESULT CurrentServerName( [out, retval] BSTR* pVal ); Parameters [out, retval] pVal RemoteWare Server name. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. 344 RemoteWare API Manual

Win32 IRWClientStatus API CurrentServerID Description Gets the RemoteWare Server ID.

IDL Synopsis [propget] HRESULT CurrentServerID( [out, retval] long* pVal ); Parameters [out, retval] pVal RemoteWare Server ID. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Win32 IRWClientStatus API InstallPath Description Gets the installation path of the RemoteWare Client.

IDL Synopsis [propget] HRESULT InstallPath( [out, retval]BSTR* pVal ); Parameters [out, retval] pVal Installation path for this RemoteWare Client. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. Example For an example of a similar method, see “Win32 IRWClientInfo API” on page 265. CHAPTER 7 / Win32 COM Object Client APIs 345

Win32 IRWClientStatus API Alerts Description Gets the Client’s active alerts.

IDL Synopsis [propget] HRESULT Alerts( [out, retval] long* pVal ); Parameters [out, retval] pVal A bit mask describing the current Client Alerts. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. Example For an example of a similar method, see “Win32 IRWClient API” on page 249.

Win32 IRWClientStatus API CurrentSWO Description Gets the name of the currently executing work object.

IDL Synopsis [propget] HRESULT CurrentSWO ( [out, retval] BSTR* pVal ); Parameters [out, retval] pVal The name of the executing work object. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. 346 RemoteWare API Manual

Win32 IRWClientStatus API CurrentSWO (Continued)

Example try { CStatic* pCurrentTask = (CStatic*) GetDlgItem ( IDC_CURRENT_TASK ); IRWClientPtr pClient; pClient.CreateInstance( __uuidof(RWClient) ); ... IRWClientStatusPtr pClientStatus = pClient; if (Command == RWCC_CMD_SWO) { pCurrentTask->SetWindowText (pClientStatus->GetCurrentSWO()); } else if (Command == RWCC_CMD_NONE) { pCurrentTask->SetWindowText(""); } } catch( const _com_error e ) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "General Error" ); } CHAPTER 7 / Win32 COM Object Client APIs 347

Win32 IRWClientStatus API CurrentCommand Description Gets the currently executing command.

IDL Synopsis [propget] HRESULT CurrentCommand( [out, retval] long* pVal ); Parameters [out, retval] pVal The command currently executing. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Win32 IRWClientStatus API CurrentFileName Description Gets the name of the file currently being transferred.

IDL Synopsis [propget] HRESULT CurrentFileName( [out, retval] BSTR* pVal ); Parameters [out, retval] pVal Name of the file currently being transferred. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. 348 RemoteWare API Manual

Win32 IRWClientStatus API CurrentFileSize Description Gets the size of the file currently being transferred.

IDL Synopsis [propget] HRESULT CurrentFileSize( [out, retval] long* pVal ); Parameters [out, retval] pVal Size of the file currently being transferred. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Win32 IRWClientStatus API CurrentBytesTransferred Description Gets the number of bytes that have been transferred for the current file.

IDL Synopsis [propget] HRESULT CurrentBytesTransferred( [out, retval] long* pVal ); Parameters [out, retval] pVal Number of bytes transferred for the current file. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. CHAPTER 7 / Win32 COM Object Client APIs 349

Win32 IRWClientStatus API SessionEndTime Description Gets the session end time for the last RemoteWare session.

IDL Synopsis [propget] HRESULT SessionEndTime( [out, retval] DATE* pVal ); Parameters [out, retval] pVal Session end time for the last RemoteWare session. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Win32 IRWClientStatus API InQTotalMessages Description Gets the total number of messages in the Client’s in queue.

IDL Synopsis [propget] HRESULT InQTotalMessages( [out, retval] long* pVal ); Parameters [out, retval] pVal Number of messages in the Client’s in queue. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. Example For an example of a similar method, see “Win32 IRWClientSessionStatus API” on page 295. 350 RemoteWare API Manual

Win32 IRWClientStatus API OutQTotalMessages Description Gets the number of messages in the Client’s out queue.

IDL Synopsis [propget] HRESULT OutQTotalMessages( [out, retval] long* pVal ); Parameters [out, retval] pVal Number of messages in the Client’s out queue. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. Example For an example of a similar method, see “Win32 IRWClientSessionStatus API” on page 300.

Win32 IRWClientStatus API InQTotalBytes Description Gets the number of bytes of the messages in the Client’s in queue.

IDL Synopsis [propget] HRESULT INQTotalBytes( [out, retval] long* pVal ); Parameters [out, retval] pVal Number of messages in the Client’s out queue. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. Example For an example of a similar method, see “Win32 IRWClientSessionStatus API” on page 300. CHAPTER 7 / Win32 COM Object Client APIs 351

Win32 IRWClientStatus API OUTQTotalBytes Description Gets the number of bytes of the messages in the Client’s out queue.

IDL Synopsis [propget] HRESULT OUTQTotalBytes( [out, retval] long* pVal ); Parameters [out, retval] pVal Number of bytes of the messages in the Client’s out queue. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Win32 IRWClientStatus API INQTotalBytesTransferred Description Gets the number of bytes transferred for the messages in the in queue.

IDL Synopsis [propget] HRESULT INQTotalBytesTransferred( [out, retval] long* pVal ); Parameters [out, retval] pVal Number of bytes transferred for the messages in the in queue. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. 352 RemoteWare API Manual

Win32 IRWClientStatus API OUTQTotalBytesTransferred Description Gets the number of bytes transferred for the messages in the out queue.

IDL Synopsis [propget] HRESULT OUTQTotalBytesTransferred( [out, retval] long* pVal ); Parameters [out, retval] pVal Number of bytes transferred for the messages in the in queue. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Win32 IRWClientStatus API InQCurrentMessage Description Gets the message currently being transferred in the Client’s in queue

IDL Synopsis [propget] HRESULT INQCurrentMessage ( [out, retval] long* pVal ); Parameters [out, retval] pVal The message currently being transferred in the Client’s in queue. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. Example For an example of a similar method, see “Win32 IRWClientSessionStatus API” on page 296. CHAPTER 7 / Win32 COM Object Client APIs 353

Win32 IRWClientStatus API OutQCurrentMessage Description Gets the message currently being transferred in the Client’s out queue.

IDL Synopsis [propget] HRESULT OutQCurrentMessage( [out, retval] long* pVal ); Parameters [out, retval] pVal The message currently being transferred in the Client’s in queue. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. Example For an example of a similar method, see “Win32 IRWClientSessionStatus API” on page 302.

Win32 IRWClientStatus API INQCurrentMessageBytes Description Gets the number of bytes in the the message currently being transferred in the Client’s in queue.

IDL Synopsis [propget] HRESULT INQCurrentMessageBytes( [out, retval] long* pVal ); Parameters [out, retval] pVal The message currently being transferred in the Client’s out queue. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. 354 RemoteWare API Manual

Win32 IRWClientStatus API OUTQCurrentMessageBytes Description Gets the number of bytes in the the message currently being transferred in the Client’s out queue.

IDL Synopsis [propget] HRESULT OUTQCurrentMessageBytes( [out, retval] long* pVal ); Parameters [out, retval] pVal The message currently being transferred in the Client’s out queue. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Win32 IRWClientStatus API INQCurrentMessageBytesTransferred Description Gets the number of bytes transferred for the current message in the Client’s in queue.

IDL Synopsis [propget] HRESULT INQCurrentMessageBytesTransferred( [out, retval] long* pVal ); Parameters [out, retval] pVal The number of bytes transferred for the current message in the Client’s in queue. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. Example For an example of a similar method, see “Win32 IRWClientSessionStatus API” on page 298. CHAPTER 7 / Win32 COM Object Client APIs 355

Win32 IRWClientStatus API OUTQCurrentMessageBytesTransferred Description Gets the number of bytes transferred for the current message in the Client’s out queue.

IDL Synopsis [propget] HRESULT OUTQCurrentMessageBytesTransferred( [out, retval] long* pVal ); Parameters [out, retval] pVal The number of bytes transferred for the current message in the Client’s out queue. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. Example For an example of a similar method, see “Win32 IRWClientSessionStatus API” on page 303.

Win32 IRWClientStatus API InQMAPIMessagesTransferred Description Gets the total number of mail messages transferred into the Client’s in queue.

IDL Synopsis [propget] HRESULT InQMAPIMessagesTransferred( [out, retval] long* pVal ); Parameters [out, retval] pVal The number of messages transferred into the Windows MAPI message queue. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. 356 RemoteWare API Manual

Win32 IRWClientStatus API OutQMAPIMessagesTransferred Description Gets the total number of mail messages transferred from the Client’s in queue.

IDL Synopsis [propget] HRESULT InQMAPIMessagesTransferred( [out, retval] long* pVal ); Parameters [out, retval] pVal The total number of mail messages that have been transferred from the Client’s in queue. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Win32 IRWClientStatus API PlayLastSessionOnNameChange Description Gets the PlayLastSessionOnNameChange flag for the RemoteWare Client.

IDL Synopsis [propget] HRESULT PlayLastSessionOnNameChange( [out, retval] long* pVal ); Parameters [out, retval] pVal The PlayLastSessionOnNameChange flag for the RemoteWare Client. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. Example For an example of a similar method, see “Win32 IRWClient API” on page 254. CHAPTER 7 / Win32 COM Object Client APIs 357

Win32 IRWClientStatus API PlayLastSessionOnNameChange Description Sets the PlayLastSessionOnNameChange flag for the RemoteWare Client.

IDL Synopsis [propput] HRESULT PlayLastSessionOnNameChange( [in] long pVal ); Parameters [in] pVal For more information, see “Win32 IRWClient API” on page 255. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. Example For an example of a similar method, see “Win32 IRWClient API” on page 255.

Win32 IRWClientStatus API LastSessionStatus Description Gets the status of the last RemoteWare session.

IDL Synopsis [propget] HRESULT LastSessionStatus( [propget] lon*g pVal ); Parameters [out, retval] pVal Bit mask describing the status of the last RemoteWare session. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. 358 RemoteWare API Manual

Win32 IRWClientStatus API LastSessionStatusText Description Gets a text string describing the status of the last RemoteWare session.

IDL Synopsis [propget] HRESULT LastSessionStatusText( [out, retval] BSTR* pVal ); Parameters [out, retval] pVal Text string describing the status of the last RemoteWare session. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Win32 IRWClientStatus API Load Description Loads the RemoteWare kernel. IDL Synopsis HRESULT Load ( ) Parameters None Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. Example For an example of a similar method, see “Win32 IRWClient API” on page 256. CHAPTER 7 / Win32 COM Object Client APIs 359

Win32 IRWClientStatus API UnLoad Description Unloads the RemoteWare kernel IDL Synopsis HRESULT Unload ( ) Parameters None Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. Example For an example of a similar method, see “Win32 IRWClient API” on page 257.

Win32 IRWClientStatus API Connect Description Initiates a connection to the RemoteWare Server. IDL Synopsis HRESULT Connect ( ) Parameters None Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. Example For an example of a similar method, see “Win32 IRWClient API” on page 257. 360 RemoteWare API Manual

Win32 IRWClientStatus API Initialize Description Establishes or re-establishes a link with the RemoteWare kernel to monitor activity. IDL Synopsis HRESULT Initialize ( ) Parameters None Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. Example For an example of a similar method, see “Win32 IRWClient API” on page 257.

Win32 IRWClientStatus API ReleasePort Description Releases the communications port. IDL Synopsis HRESULT ReleasePort ( ) Parameters None Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. Example For an example of a similar method, see “Win32 IRWClient API” on page 259. CHAPTER 7 / Win32 COM Object Client APIs 361

Win32 IRWClientStatus API Cancel Description Cancels the current RemoteWare session.

IDL Synopsis HRESULT Cancel ( [in] long ForceIfConnected ) Parameters [in] ForceIfConnected If ForceIfConnected is set (True), then a cancel will be attempted even if an active connection exists. If ForceIfConnected is not set (False), the cancel will be attempted only if a connection request is pending but is not yet established; it will not be attempted if the connection is already active. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Example For an example of a similar method, see “Win32 IRWClient API” on page 260.

Win32 IRWClientStatus API PendingOperations Description Gets a bit mask describing pending operations for the RemoteWare session.

IDL Synopsis HRESULT GetPendingOperations( [out, retval] long* pPendingOperationsMask ); Parameters [out, retval] A bit mask describing pending operations for the RemoteWare pPendingOperations session. For RWC_PendingOperation_e valid values, see Mask “Enumerations and Structures” on page 418. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. 362 RemoteWare API Manual

Win32 IRWClientStatus API PendingOperations (Continued)

Example For an example of a similar method, see “Win32 IRWClient API” on page 253.

Win32 IRWClientStatus API ApplyESD Description Applies the Electronic Software Distribution (if any).

IDL Synopsis HRESULT ApplyESD( [in] long RebootIfNecessary, [out, retval] long* pApplyResult ); Parameters [in] RebootIfNecessary If set, then reboot the Client if necessary. [out, retval] An error result code indicating if the ESD was applied successfully. pApplyResult Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. Example For an example of a similar method, see “Win32 IRWClient API” on page 261. CHAPTER 7 / Win32 COM Object Client APIs 363

Win32 IRWClientStatus API RefreshAlerts Description Refreshes the RemoteWare Client alerts.

IDL Synopsis HRESULT ApplyESD( [in] long RebootIfNecessary, [out, retval] long* pApplyResult ); Parameters None Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. Example For an example of a similar method, see “Win32 IRWClient API” on page 263. 364 RemoteWare API Manual

IRWClientWOSelection API methods The IRWClientWOSelection interface provides methods to manipulate the selections of work objects assigned to a RemoteWare Client. The IRWClientWOSelection interface implements the RWClientWOSelection coclass and is not user createable. To use the IRWClientWOSelection interface, it must be retrieved through an IRWClientDialingEntry interface.

Overview

• Implements coclass: RWClientWOSelection. • Creatable? No, must be retrieved from IRWClientDialingEntry interface. The following table summarizes the IRWClientWOSelection API methods: Table 33. IRWClientWOSelection API methods Method Name Description

WorkObjectCount Gets the number of work objects assigned to the RemoteWare Client. IsUsingDefaults Gets a flag indicating whether the default work object selections are currently be used. UseDefaults Uses the default work object selections. WorkObject Gets the name of a selected work object and determines whether it is a default selection or is currently selected. SelectWorkObject Selects a given work object. SaveWorkObjectSelection Saves the current work object selections. CHAPTER 7 / Win32 COM Object Client APIs 365

Win32 IRWClientWOSelection API WorkObjectCount Description Gets the number of work objects assigned to the RemoteWare Client.

IDL Synopsis [propget] HRESULT WorkObjectCount( [out, retval] long* pCount ); Parameters [out, retval] pCount Number of work objects assigned to the RemoteWare Client. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Example try { CListBox* pList = (CListBox*) GetDlgItem( IDC_OBJECT_LIST ); CStatic* pDefaults = (CStatic*) GetDlgItem( IDC_DEFAULTS ); CString strClientName; VARIANT_BOOL Selected; VARIANT_BOOL Default; GetDlgItemText( IDC_CLIENT_NAME, strClientName ); IRWClientPtr pClient( __uuidof( RWClient ) ); _bstr_t Name("CLIENTNAME"); pClient->PutClientName(Name); IRWClientDialingEntryPtr pEntry = pClient-> GetDefaultResource(); IRWClientWOSelectionPtr pSel = pEntry-> WorkObjectSelection(); 366 RemoteWare API Manual

Win32 IRWClientWOSelection API WorkObjectCount (Continued)

Example (Continued) for ( long i = 0; i < pSel-> GetWorkObjectCount(); i++ ) { pList->AddString(pSel->WorkObject( i, &Selected, &Default ) ); } if (pSel->GetIsUsingDefaults() == VARIANT_TRUE) pDefaults->SetWindowText("Using defaults: YES"); else pDefaults->SetWindowText("Using defaults: NO"); } catch(const _com_error e) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "General Error" ); }

Win32 IRWClientWOSelection API IsUsingDefaults Description Gets a flag indicating whether the default work object selections are currently be used.

IDL Synopsis [propget] HRESULT IsUsingDefaults (( [out, retval] VARIANT_BOOL* PUseDefaults ); Parameters [out, retval] A flag indicating whether the default work object selections are pUseDefaults currently be used. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. CHAPTER 7 / Win32 COM Object Client APIs 367

Win32 IRWClientWOSelection API IsUsingDefaults (Continued)

Example try { CListBox* pList = (CListBox*) GetDlgItem( IDC_OBJECT_LIST ); CStatic* pDefaults = (CStatic*) GetDlgItem( IDC_DEFAULTS ); CString strClientName; VARIANT_BOOL Selected; VARIANT_BOOL Default; GetDlgItemText( IDC_CLIENT_NAME, strClientName ); IRWClientPtr pClient( __uuidof( RWClient ) ); _bstr_t Name("CLIENTNAME"); pClient->PutClientName(Name); IRWClientDialingEntryPtr pEntry = pClient-> GetDefaultResource(); IRWClientWOSelectionPtr pSel = pEntry-> WorkObjectSelection(); for ( long i = 0; i < pSel-> GetWorkObjectCount(); i++ ) { pList->AddString(pSel->WorkObject( i, &Selected, &Default ) ); } if (pSel->GetIsUsingDefaults() == VARIANT_TRUE) pDefaults->SetWindowText("Using defaults: YES"); else pDefaults->SetWindowText("Using defaults: NO"); } catch(const _com_error e) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "General Error" ); } 368 RemoteWare API Manual

Win32 IRWClientWOSelection API UseDefaults Description Uses the default work object selections.

IDL Synopsis HRESULT UseDefaults ( ) Parameters None Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Example try { CListBox* pList = (CListBox*) GetDlgItem( IDC_OBJECT_LIST ); CStatic* pDefaults = (CStatic*) GetDlgItem( IDC_DEFAULTS ); VARIANT_BOOL selected, defaultsel; IRWClientPtr pClient( __uuidof( RWClient ) ); _bstr_t Name("CLIENTNAME"); pClient->PutClientName( Name ); IRWClientDialingEntryPtr pEntry = pClient-> GetDefaultResource( ); IRWClientWOSelectionPtr pSel = pEntry-> WorkObjectSelection(); pSel->UseDefaults(); for( int i = 0; i < pList->GetCount(); i++ ) { pSel->WorkObject( i, &selected, &defaultsel ); CHAPTER 7 / Win32 COM Object Client APIs 369

Win32 IRWClientWOSelection API UseDefaults (Continued)

Example (Continued) if ( defaultsel == VARIANT_TRUE ) pList->SetSel( i, TRUE ); else pList->SetSel( i, FALSE ); } if (pSel->GetIsUsingDefaults() == VARIANT_TRUE) pDefaults->SetWindowText("Using defaults: YES"); else pDefaults->SetWindowText("Using defaults: NO"); } catch(const _com_error e) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "General Error" ); }

Win32 IRWClientWOSelection API WorkObject Description Gets the name of a selected work object and determines whether it is a default selection or is currently selected.

IDL Synopsis HRESULT WorkObject ( [in] long Index, [out] VARIANT_BOOL* pSelected, [out] VARIANT_BOOL* pDefaultSelection, [out, retval] BSTR* ppName ); Parameters [in] Index Index of the work object from which to get info. [out] pSelected If VARIANT_TRUE, the work object is selected. [out] pDefaultSelection If VARIANT_TRUE, work object is a default. [out, retval] ppName The name of the selected work object. 370 RemoteWare API Manual

Win32 IRWClientWOSelection API WorkObject (Continued)

Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Example try { CListBox* pList = (CListBox*) GetDlgItem( IDC_OBJECT_LIST ); CStatic* pDefaults = (CStatic*) GetDlgItem( IDC_DEFAULTS ); VARIANT_BOOL selected, defaultsel; IRWClientPtr pClient( __uuidof( RWClient ) ); _bstr_t Name("CLIENTNAME"); pClient->PutClientName( Name ); IRWClientDialingEntryPtr pEntry = pClient-> GetDefaultResource( ); IRWClientWOSelectionPtr pSel = pEntry-> WorkObjectSelection(); pSel->UseDefaults(); for( int i = 0; i < pList->GetCount(); i++ ) { pSel->WorkObject( i, &selected, &defaultsel ); if ( defaultsel == VARIANT_TRUE ) pList->SetSel( i, TRUE ); else pList->SetSel( i, FALSE ); }

if (pSel->GetIsUsingDefaults() == VARIANT_TRUE) pDefaults->SetWindowText("Using defaults: YES"); else pDefaults->SetWindowText("Using defaults: NO"); } catch(const _com_error e) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "General Error" ); } CHAPTER 7 / Win32 COM Object Client APIs 371

Win32 IRWClientWOSelection API SelectWorkObject Description Selects a given work object.

IDL Synopsis HRESULT SelectWorkObject ( [in] BSTR pName, [in] VARIANT_BOOL Select); Parameters [in] pName The name of the work object to select. [in] Select If VARIANT_TRUE, select the work object. If VARIANT_FALSE, unselect the work object. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. 372 RemoteWare API Manual

Win32 IRWClientWOSelection API SelectWorkObject (Continued)

Example try { CListBox* pList = (CListBox*) GetDlgItem( IDC_OBJECT_LIST ); CString strObject; IRWClientPtr pClient( __uuidof( RWClient ) ); _bstr_t Name("CLIENTNAME"); pClient->PutClientName(Name); IRWClientDialingEntryPtr pEntry = pClient-> GetDefaultResource(); IRWClientWOSelectionPtr pSel = pEntry-> WorkObjectSelection(); for( int i = 0; i < pList->GetCount(); i++ ) { VARIANT_BOOL vbSelected; if ( pList->GetSel(i) > 0 ) vbSelected = VARIANT_TRUE; else vbSelected = VARIANT_FALSE; pList->GetText( i, strObject ); _bstr_t Object(strObject); pSel->SelectWorkObject( Object, vbSelected ); } pSel->SaveWorkObjectSelection(); } catch(const _com_error e) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "General Error" ); } CHAPTER 7 / Win32 COM Object Client APIs 373

Win32 IRWClientWOSelection API SaveWorkObjectSelection Description Saves the current work object selections.

IDL Synopsis HRESULT SaveWorkObjectSelection () Parameters None Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Example try { CListBox* pList = (CListBox*) GetDlgItem( IDC_OBJECT_LIST ); CString strObject; IRWClientPtr pClient( __uuidof( RWClient ) ); _bstr_t Name("CLIENTNAME"); pClient->PutClientName(Name); IRWClientDialingEntryPtr pEntry = pClient-> GetDefaultResource(); IRWClientWOSelectionPtr pSel = pEntry-> WorkObjectSelection(); for( int i = 0; i < pList->GetCount(); i++ ) { VARIANT_BOOL vbSelected; if ( pList->GetSel(i) > 0 ) vbSelected = VARIANT_TRUE ; else vbSelected = VARIANT_FALSE; pList->GetText( i, strObject ); _bstr_t Object(strObject); pSel->SelectWorkObject( Object, vbSelected ); } pSel->SaveWorkObjectSelection(); } catch(const _com_error e) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "General Error" ); } 374 RemoteWare API Manual

IRWClientDialingEntryCollection API Methods The IRWClientDialingEntryCollection interface provides methods to enumerate through the RemoteWare Client dialing entries. The IRWClientDialingEntryCollection interface implements coclass RWClientDialingEntryCollection and is not user createable. To use this interface, it must be retrieved through a method in the IRWClientDialingDirectory interface. An example of the IRWClientDialingEntryCollection has not been provided in the RemoteWare 32-bit and OS/2 Client API, but collections are similar in operation. See the other RemoteWare collection interfaces as examples.

Overview

• Implements coclass: RWClientDialingEntryCollection • Creatable? No. • The APIs in this collection are similar in operation to both each other and to other APIs in this guide. For examples of a similar methods, see “IRWClientInfoCollection API Methods” on page 377.. The following table summarizes the IRWClientDialingEntryCollection API methods: Table 34. IRWClientDialingEntryCollection API methods Method Name Description

_NewEnum Gets the status of the RemoteWare Client. Item Gets the item at a specified position in the collection. Count Gets the number of items in the collection. CHAPTER 7 / Win32 COM Object Client APIs 375

Win32 IRWClientDialingEntryCollection API _NewEnum Description Gets the status of the RemoteWare Client.

IDL Synopsis [propget] HRESULT ClientStatus( [out, retval] short* pVal ); Parameters [out, retval] pVal RemoteWare Client status. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. Example For an example of a similar method, see “IRWClientInfoCollection API Methods” on page 377.

Win32 IRWClientDialingEntryCollection API Item Description Gets the item at a specified position in the collection.

IDL Synopsis [propget] HRESULT Item( [in] long Index, [out, retval] VARIANT* retval ); Parameters [in] Index The dialing entry index. [out, retval] retval The dialing entry. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. Example For an example of a similar method, see “IRWClientInfoCollection API Methods” on page 377. 376 RemoteWare API Manual

Win32 IRWClientDialingEntryCollection API Count Description Gets the number of items in the collection.

IDL Synopsis [propget] HRESULT Count( [out, retval] long* retval ); Parameters [out, retval] retval Number of items in the collection. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. Example For an example of a similar method, see “IRWClientInfoCollection API Methods” on page 377. CHAPTER 7 / Win32 COM Object Client APIs 377

IRWClientInfoCollection API Methods The IRWClientInfoCollection interface provides methods to enumerate through RemoteWare Clients installed on a computer. The IRWClientInfoCollection interface implements coclass EnumRWClientInfo and is user createable.

Overview

• Implements: EnumRWClientInfo. • Creatable? Yes. The following table summarizes the IRWClientInfoCollection API methods: Table 35. IRWClientInfoCollection API methods Method Name Description

_NewEnum Gets an object that enumerates the installed RemoteWare Clients. Item Gets the RemoteWare Client at a specified position in the collection. Count Gets the RemoteWare Client at a specified position in the collection. AllowUnregisteredClients Gets a flag indicating if unregistered Clients are included in the collection. AllowUnregisteredClients Sets a flag including or excluding unregistered Clients in the collection. DefaultClientName Gets the default Client name for a RemoteWare Client, specified by an installation path. 378 RemoteWare API Manual

Win32 IRWClientInfoCollection API _NewEnum Description Gets an object that enumerates the installed RemoteWare Clients.

IDL Synopsis [propget] HRESULT _NewEnum ( [out, retval] IUnknown** retval ); Parameters [out, retval] retval Pointer to a new enumeration of the installed RemoteWare Clients. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Example try { CListCtrl* pList = (CListCtrl*) GetDlgItem( IDC_CLIENT_LIST ); IRWClientInfoPtr pInfo; IEnumVARIANTPtr pEnum; VARIANT var = {0}; ULONG Fetched; int Item = 0; IRWClientInfoCollectionPtr pCol( __uuidof( EnumRWClientInfo ) ); ... pCol->PutAllowUnregisteredClients (VARIANT_TRUE); pEnum = pCol->Get_NewEnum(); CHAPTER 7 / Win32 COM Object Client APIs 379

Win32 IRWClientInfoCollection API _NewEnum (Continued)

Example (Continued) while ( S_OK == pEnum->Next( 1, &var, &Fetched ) ) { ASSERT( var.vt == VT_DISPATCH ); pInfo = var.pdispVal; pList->InsertItem( Item, pInfo-> GetName() ); ... Item++; ::VariantClear( &var ); } } catch(const _com_error e) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "Error Enumerating Clients" ); }

Win32 IRWClientInfoCollection API Item Description Gets the RemoteWare Client at a specified position in the collection.

IDL Synopsis [propget] HRESULT Item ( [in] long Index, [out, retval] VARIANT* retval ); Parameters [in] Index The Client entry index. [out, retval] retval The Client info entry. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. 380 RemoteWare API Manual

Win32 IRWClientInfoCollection API Item (Continued)

Example try { CListCtrl* pList = (CListCtrl*) GetDlgItem( IDC_CLIENT_LIST ); IRWClientInfoPtr pInfo; IEnumVARIANTPtr pEnum; VARIANT var = {0}; ULONG Fetched; int Item = 0; IRWClientInfoCollectionPtr pCol( __uuidof( EnumRWClientInfo ) ); pCol->PutAllowUnregisteredClients (VARIANT_TRUE); pEnum = pCol->Get_NewEnum(); _variant_t vart; for (long i = 0; i < pCol->GetCount(); i++ ) { vart = pCol->GetItem(i); pInfo = vart.pdispVal; pList->InsertItem( i, pInfo->GetName() ); ... ::VariantClear( &vart ); } } catch(const _com_error e) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "Error Enumerating Clients" ); } CHAPTER 7 / Win32 COM Object Client APIs 381

Win32 IRWClientInfoCollection API Count Description Gets the RemoteWare Client at a specified position in the collection.

IDL Synopsis [propget] HRESULT Count ( [out, retval] long* retval ); Parameters [out, retval] retval Number of items (Clients) in the collection. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Example try { CListCtrl* pList = (CListCtrl*) GetDlgItem( IDC_CLIENT_LIST ); IRWClientInfoPtr pInfo; IEnumVARIANTPtr pEnum; VARIANT var = {0}; ULONG Fetched; int Item = 0; IRWClientInfoCollectionPtr pCol( __uuidof( EnumRWClientInfo ) ); pCol->PutAllowUnregisteredClients (VARIANT_TRUE); pEnum = pCol->Get_NewEnum(); _variant_t vart; for (long i = 0; i < pCol->GetCount(); i++ ) { vart = pCol->GetItem(i); 382 RemoteWare API Manual

Win32 IRWClientInfoCollection API Count (Continued)

Example (Continued) pInfo = vart.pdispVal; pList->InsertItem( i, pInfo->GetName() ); ... ::VariantClear( &vart ); } } catch(const _com_error e) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "Error Enumerating Clients" ); }

Win32 IRWClientInfoCollection API AllowUnregisteredClients Description Gets a flag indicating if unregistered Clients are included in the collection.

IDL Synopsis [propget] HRESULT AllowUnregisteredClients ( [out, retval] VARIANT_BOOL* pAllow ); Parameters [out, retval] pAllow If VARIANT_TRUE, unregistered Clients may be in the collection. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. CHAPTER 7 / Win32 COM Object Client APIs 383

Win32 IRWClientInfoCollection API AllowUnregisteredClients (Continued)

Example try { CListCtrl* pList = (CListCtrl*) GetDlgItem( IDC_CLIENT_LIST ); IRWClientInfoPtr pInfo; IEnumVARIANTPtr pEnum; VARIANT var = {0}; ULONG Fetched; int Item = 0; IRWClientInfoCollectionPtr pCol( __uuidof( EnumRWClientInfo ) ); pCol->PutAllowUnregisteredClients (VARIANT_TRUE); if (pCol->GetAllowUnregisteredClients() == VARIANT_TRUE) pStatus->SetWindowText("DISPLAYING UNREGISTERED CLIENTS"); else pStatus->SetWindowText("DISPLAYING REGISTERED CLIENTS"); pEnum = pCol->Get_NewEnum(); _variant_t vart; for (long i = 0; i < pCol->GetCount(); i++ ) { vart = pCol->GetItem(i); pInfo = vart.pdispVal; pList->InsertItem( i, pInfo->GetName() ); ... ::VariantClear( &vart ); } } catch(const _com_error e) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "Error Enumerating Clients" ); } 384 RemoteWare API Manual

Win32 IRWClientInfoCollection API AllowUnregisteredClients Description Sets a flag including or excluding unregistered Clients in the collection.

IDL Synopsis [propget] HRESULT AllowUnregisteredClients ( [out, retval] VARIANT_BOOL* pAllow ); Parameters [in] pAllow If VARIANT_TRUE, allow unregistered Clients in the collection. If VARIANT_FALSE, exclude unregistered Clients. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Example try { CListCtrl* pList = (CListCtrl*) GetDlgItem( IDC_CLIENT_LIST ); IRWClientInfoPtr pInfo; IEnumVARIANTPtr pEnum; VARIANT var = {0}; ULONG Fetched; int Item = 0; IRWClientInfoCollectionPtr pCol( __uuidof( EnumRWClientInfo ) ); pCol->PutAllowUnregisteredClients (VARIANT_TRUE); pEnum = pCol->Get_NewEnum(); _variant_t vart; for (long i = 0; i < pCol->GetCount(); i++ ) { vart = pCol->GetItem(i); CHAPTER 7 / Win32 COM Object Client APIs 385

Win32 IRWClientInfoCollection API AllowUnregisteredClients (Continued)

Example (Continued) pInfo = vart.pdispVal; pList->InsertItem( i, pInfo->GetName() ); ... ::VariantClear( &vart ); } } catch(const _com_error e) } ErrorMessage( e ); } catch(...) { AfxMessageBox( "Error Enumerating Clients" ); }

Win32 IRWClientInfoCollection API DefaultClientName Description Gets the default Client name for a RemoteWare Client, specified by an installation path.

IDL Synopsis [propget] HRESULT DefaultClientName ( [in] BSTR pFullPath, [out, retval] BSTR* ppClientName ); Parameters [in] pFullPath Install path for the RemoteWare Client. [out, retval] Client name. ppClientName Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. 386 RemoteWare API Manual

Win32 IRWClientInfoCollection API DefaultClientName (Continued)

Example try { IRWClientInfoCollectionPtr pCol( __uuidof( EnumRWClientInfo ) ); _bstr_t strPath("C:\PROGRAM FILES\ CONNECT_REMOTE\NODESYS"); pStatus->SetWindowText(pCol-> GetDefaultClientName(strPath)); } catch(const _com_error e) { ErrorMessage( e ); } catch(...) { AfxMessageBox( "Error Enumerating Clients" );

Transaction Pipe API functions The Transaction Pipe APIs let a process at a RemoteWare Client perform client-server operations via the RemoteWare Transaction Pipe, much like Named Pipes. The Transaction Pipe provides a reliable bi-directional, transport-independent communications path (a virtual circuit) between a process on a RemoteWare Client and a process on a RemoteWare Server. This provides an alternative way to communicate with the RemoteWare Server without using a traditional session, and it is ideal for communication over a Local Area Network (LAN). Transaction Pipe is an emulation of a named pipe via RemoteWare. RemoteWare acts as an agent between a RemoteWare Transaction Pipe Client program and a named pipe server on a RemoteWare Server’s LAN. The four Transaction Pipe Client API functions listed in the following table let a Client program open a pipe, send and receive messages through the pipe, and close the pipe when done. However, for a Client program to use these functions, the RemoteWare Server must be running a Named Pipe Server process that manages the pipe and passes messages to and from the appropriate applications. CHAPTER 7 / Win32 COM Object Client APIs 387

Function Name Description

RWCPipeOpen Opens the connection to a Transaction Pipe. RWCPipeClose Closes the connection to a Transaction Pipe. RWCPipeRead Reads a message from an open Transaction Pipe. RWCPipeWrite Writes a message to an open Transaction Pipe.

Transaction Pipe Notification Types When you open a Transaction Pipe, you are given the option to have your application notified of activity on the transaction pipe via standard WinProc messages. When the Transaction Pipe notifies an application, the first message parameter will contain a notification type and the second message parameter will contain the handle of the affected pipe instance (type HRWNPIPE).

Function Name Description

RWPN_CALLING Client is calling Server. RWPN_CONNECTED Pipe has successfully connected. RWPN_DISCONNECTED Pipe has disconnected (normally). RWPN_BROKEN Pipe (or underlying connection) was abnormally terminated. RWPN_MESSAGE Application message has been sent to your program and is waiting to be read. RWPN_LOADING Client is loading. RWPN_UNLOADING Client is unloading. RWPN_REINITIALIZING Client is reinitializing. RWPN_CONNECTING Waiting for pipe connection.

Transaction Pipe function Error Codes If an error occurs in a Transaction Pipe function, the return value will be one of the error codes listed in the following table:

Name Description

E_PIPE_NODE_NOT_LOAD The RemoteWare Client has not been loaded. ED E_PIPE_NOT_AVAILABLE The connection to the Server failed. E_PIPE_NOT_FOUND The connection to the Server succeeded but the open named pipe failed. 388 RemoteWare API Manual

Name Description

E_PIPE_BUSY The connection to the Server succeeded but the named pipe Server didn’t accept the request. E_PIPE_CONNECTING Still waiting for connection to the RemoteWare Server or Transaction Pipe Server. E_PIPE_INVALID_DIRENTR The dialing directory name you supplied is not valid. Y E_PIPE_INVALID_CLIENT The Client name you supplied is not valid. E_PIPE_BUFFER_FULL Insufficient space remains in the buffer to write the currently defined message. Write a smaller message or wait for previously buffered messages to be retrieved by the Server. E_PIPE_TRANSPORT_ERRO The transport resource failed. R E_PIPE_INVALID_HANDLE The specified HRWNPIPE value is invalid. E_PIPE_INVALID_PARAMET A supplied parameter is invalid. ER E_PIPE_BROKEN The Transaction Pipe (or the underlying connection) was abnormally terminated. E_PIPE_INSUFFICIENT_BU Insufficient space remains in the buffer to write the currently defined FFER message. Write a smaller message or wait for previously buffered messages to be retrieved by the Server. E_PIPE_BAD_PIPE The pipe state is invalid. E_PIPE_NO_DATA A pipe close is in progress. E_PIPE_NOT_CONNECTED The network connection does not exist. E_PIPE_MORE_DATA More data is available. E_PIPE_TIMEOUT The pipe connection has timed out. E_PIPE_TOOMANY Too many pipes are currently open. E_PIPE_NOT_ENOUGH_ME Not enough memory to complete pipe operation. MORY other The function failed; the value returned is the Windows error code indicating the reason for the failure. CHAPTER 7 / Win32 COM Object Client APIs 389

32-bit Client Transaction Pipe API RWCPipeOpen

Description This function opens the connection to a Transaction Pipe. Comments If your program uses this function call, be sure to #define INCL_RWC_PIPE prior to including RWCAPI.H.

C Synopsis RWNRET RWNENTRY RWCPipeOpen( PSZ pszClient, PHRWNPIPE phrwp, PSZ pszPipeName, PVOID pvMsg, UINT cbMsg, ULONG fulOptions, PRWNPOPEN prwpo ); Parameters pszClient This parameter specifies the name of the Client that is opening the pipe. Use NULL to specify the default Client. phrwp This is a pointer to a variable of type HRWNPIPE to receive the pipe handle upon successful opening of the Pipe. pszPipeName This is a pointer to a null-terminated string (maximum size of CCHMAXNAME) that specifies the name of the Transaction Pipe Server to connect with. Transaction Pipe Server names typically take the form \\computername\pipe\pipename. pvMsg This parameter contains a pointer to the Transaction Pipe message buffer, which can contain an initial message (such as initial application data). cbMsg This parameter indicates the number of bytes of the message buffer to be written to the pipe. fulOptions This parameter is for future options. Always pass 0L (zero). prwpo This parameter contains a pointer to a buffer that contains the RWNPOPEN structure, which is defined later in this section. RWNPOPEN The RWNPOPEN parameter is used as described in the prwpo parameter above. 390 RemoteWare API Manual

32-bit Client Transaction Pipe API RWCPipeOpen (Continued)

Structure of typedef struct _rwnpopen RWNPOPEN { ULONG cb ; // size (in bytes) of this structure. ULONG cbMaxInBuf ; // size (in bytes) of message input // buffer; see RWNPipeRead(). ULONG cbMaxOutBuf ; // size (in bytes) of message output // buffer; see RNWPipeWrite(). ULONG cmsTimeout ; // count in milliseconds to wait // for Server (ALWAYS SET TO 0; // not yet implemented). HWND hwnd ; // window handle to notify ULONG uWndMsg ; // notification window message PSZ psdDirEntry ; // name of the Dialing Directory entry // to use; NULL specifies default entry } RWNPOPEN, FAR * PRWNPOPEN ; Return values This function returns one of the following values: E_PIPE_OK The request was successfully acknowledged.

Note: A return value of E_PIPE_OK means the request to open a pipe has been successfully acknowledged, but it does not mean that the pipe has actually been opened. The Server may have to finish other tasks before actually attempting to open the requested pipe. At that point, either you will begin to receive pipe messages, or you will receive an error message if the open attempt fails. other The function failed. The value returned is an error code indicating the reason for the failure. For descriptions, see “Transaction Pipe function Error Codes” on page 387. CHAPTER 7 / Win32 COM Object Client APIs 391

32-bit Client Transaction Pipe API RWCPipeOpen (Continued)

Example HRWNPIPE hPipe; RWNPOPEN PipeOpenStruct; RWNRET rc;

PipeOpenStruct.cb=sizeof(RWNPOPEN); PipeOpenStruct.cbMaxInBuf=1024; PipeOpenStruct.cbMaxOutBuf=1024; PipeOpenStruct.cmsTimeout=0; // No timeout PipeOpenStruct.hwnd = NULL; PipeOpenStruct.uWndMsg = 0L; PipeOpenStruct.pszDirEntry = NULL;

rc=RWNPipeOpen( &hPipe, (PSZ)”\\\\.\\pipe\\mypipe”, NULL, 0, 0L, &PipeOpenStruct);

32-bit Client Transaction Pipe API RWCPipeClose

Description This function closes the connection to a Transaction Pipe that was opened using RWCPipeOpen(). Comments If your program uses this function call, be sure to #define INCL_RWC_PIPE prior to including RWNAPI.H.

C Synopsis RWNRET RWNENTRY RWNPipeClose( HRWNPIPE hrwp, ULONG fulOptions, ); Parameters hrwp This variable initially received the pipe handle from the call to RWCPipeOpen() and identifies the pipe to be closed. fulOptions This parameter is for future options. Always pass 0L (zero). Return values This function returns one of the following values: E_PIPE_OK The function was successful. 392 RemoteWare API Manual

32-bit Client Transaction Pipe API RWCPipeClose (Continued)

other The function failed. The value returned is an error code indicating the reason for the failure. For descriptions, see “Transaction Pipe function Error Codes” on page 387.

Example HRWNPIPE hPipe;

RWNPipeClose(hPipe,0L);

32-bit Client Transaction Pipe API RWCPipeRead

Description This function reads a message from a Transaction Pipe that was opened using RWCPipeOpen(). The message is read from the pipe’s internal input message buffer (of the size specified by cbMaxInBuf in the RWCPipeOpen() call) and is written to the buffer pointed to by pvMsg in the RWCPipeRead() call (with the size specified in cbMsg). The actual number of bytes copied is returned in pcbActual. Comments If your program uses this function call, be sure to #define INCL_RWN_PIPE prior to including RWNAPI.H.

C Synopsis RWNRET RWNENTRY RWNPipeRead( HRWNPIPE hrwp, PVOID pvMsg, UINT cbMsg, PUINT pcbActual, ULONG ulTimeout ); Parameters hrwp This variable initially received the pipe handle from the call to RWCPipeOpen() and identifies the pipe to read from. pvMsg This parameter contains a pointer to the buffer to which the incoming message should be copied. cbMsg This parameter indicates the number of bytes in the buffer pointed to by pvMsg. pcbActual This is a pointer to an unsigned integer. On return, the integer contains the the number of bytes actually read. ulTimeout This parameter indicates the number of milliseconds to wait for the Server. CHAPTER 7 / Win32 COM Object Client APIs 393

32-bit Client Transaction Pipe API RWCPipeRead (Continued)

Return values This function returns one of the following values: E_PIPE_OK The function was successful. other The function failed. The value returned is an error code indicating the reason for the failure. For descriptions, see “Transaction Pipe function Error Codes” on page 387.

Example #define BUFFER_SIZE 1024

char pBuffer[BUFFER_SIZE]; UINT cbActual; RWNRET rc;

rc=RWNPipeRead(hPipe,(PVOID)pBuffer,(UINT)BUFFER_ SIZE,&cbActual,0L);

32-bit Client Transaction Pipe API RWCPipeWrite

Description This function writes a message to a Transaction Pipe (which was opened using RWCPipeOpen). The message to be written should be stored in the buffer pointed to by pvMsg in the RWCPipeWrite() call (with the message size specified in cbMsg). The message in that buffer is written to the pipe’s internal output message buffer (which is of the size specified by cbMaxOutBuf in the RWCPipeOpen() call used to open the pipe). Comments If your program uses this function call, be sure to #define INCL_RWN_PIPE prior to including RWNAPI.H.

C Synopsis RWNRET RWNENTRY RWNPipeWrite( HRWNPIPE hrwp, PVOID pvMsg, UINT cbMsg, ); Parameters hrwp This variable initially receives the pipe handle from RWNPipeOpen() and identifies the pipe that should be written to. pvMsg This parameter is a pointer to the Transaction Pipe message buffer containing the message to be written. 394 RemoteWare API Manual

32-bit Client Transaction Pipe API RWCPipeWrite (Continued)

cbMsg This parameter indicates the number of bytes of the message buffer to be written to the pipe. Return values This function returns one of the following values: E_PIPE_OK The function was successful. other The function failed. The value returned is an error code indicating the reason for the failure. For descriptions, see “Transaction Pipe function Error Codes” on page 387.

Example #define BUFFER_SIZE 1024 char pBuffer[BUFFER_SIZE]; UINT uiLength; RWNRET rc; strcpy(pBuffer,”Text to be sent to named pipe via RemoteWare Server”); uiLength = (UINT)strlen(pBuffer); rc=RWNPipeWrite(hPipe,(PVOID)pBuffer,uiLength);

IXWorkList API methods The IXWorkList interface allows work list events to be manipulated. This includes creation, deletion, and insertion of work list events into a work list. The IXWorkList implements the XWorklist coclass and is user creatable. Note: The installation path should be set before calling any of these methods.

Overview

• Implements: XWorklist. • Creatable? Yes. CHAPTER 7 / Win32 COM Object Client APIs 395

The following table summarizes the IXWorklist API methods: Table 36. IXWorklist API methods Method Name Description

InstallPath Gets the installation path of the WORKLIST.DLL. InstallPath Sets the installation path of the WORKLIST.DLL. FileName Gets the worklist filename. FileName Sets the worklist filename. EventCount Sets the worklist filename. ReadFile Reads in events from a worklist file. WriteFile Writes out events to a worklist file. GetEvent Gets an event at a specified location. SetEvent Replaces or sets a worklist event at a specified position in the worklist. vbGetEvent Gets an event at a specified location. Used specifically for Microsoft’s Visual Basic. vbSetEvent Replaces or sets a worklist event at a specified position in the work list. Used specifically for Microsoft’s Visual Basic. DeleteEvent Deletes a worklist event at a specified location. InsertEvent Inserts a worklist event at a specified location. vbInsertEvent Inserts a worklist event at a specified location. Used specifically for Microsoft’s Visual Basic. InsertFile Inserts worklist events in a worklist file into the current worklist InsertWorklist Inserts worklist events from another worklist into the current worklist. 396 RemoteWare API Manual

Win32 IXWorklist API InstallPath Description Gets the installation path of the WORKLIST.DLL.

IDL Synopsis [propget] HRESULT InstallPath( [out, retval] BSTR* ppPath ); Parameters [out, retval] ppPath The directory where the WORKLIST.DLL resides. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Example try { IXWorkListPtr pWorklist( __uuidof( XWorkList ) ); ... _bstr_t strInstallPath = pWorklist-> GetInstallPath(); AfxMessageBox( strInstallPath ); } catch( const _com_error e ) { ErrorMessage(e); } catch(...) { AfxMessageBox("General Error"); } CHAPTER 7 / Win32 COM Object Client APIs 397

Win32 IXWorklist API InstallPath Description Sets the installation path of the WORKLIST.DLL. This method should be called prior to calling any other method in this interface.

IDL Synopsis [propget] HRESULT InstallPath( [out, retval] BSTR ppPath ); Parameters [in] ppPath The directory where the WORKLIST.DLL resides. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Example try { IXWorkListPtr pWorklist( __uuidof( XWorkList ) ); ... _bstr_t strInstallPath = pWorklist-> GetInstallPath(); AfxMessageBox( strInstallPath ); } catch( const _com_error e ) { ErrorMessage(e); } catch(...) { AfxMessageBox("General Error"); } 398 RemoteWare API Manual

Win32 IXWorklist API FileName Description Gets the worklist filename.

IDL Synopsis [propget] HRESULT FileName( [out, retval] BSTR* ppFileName ); Parameters [out, retval] Name of the worklist file. ppFileName Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Win32 IXWorklist API FileName Description Sets the worklist filename.

IDL Synopsis [propget] HRESULT FileName( [out, retval] BSTR* ppFileName ); Parameters [out, retval] Name of the worklist file. ppFileName Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. CHAPTER 7 / Win32 COM Object Client APIs 399

Win32 IXWorklist API FileName (Continued)

Example try { IXWorkListPtr pWorklist( __uuidof( XWorkList ) ); ... _bstr_t File( "TEMP.EVF" ); pWorklist->PutFileName( File ); pWorklist->ReadFile( VARIANT_FALSE ); } catch( const _com_error& e ) { ErrorMessage(e); } catch(...) { AfxMessageBox("General Error"); }

Win32 IXWorklist API EventCount Description Sets the worklist filename.

IDL Synopsis [propget] HRESULT EventCount( [out, retval] long* pEventCount ); Parameters [out, retval] Number of events in the worklist pEvenCount Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. 400 RemoteWare API Manual

Win32 IXWorklist API EventCount (Continued)

Example try { IXWorkListPtr pWorklist( __uuidof( XWorkList ) ); _bstr_t File( "TEMP.EVF" ); pWorklist->PutFileName( File ); pWorklist->ReadFile( VARIANT_FALSE ); ... IXWorkListPtr pTempWorklist( __uuidof( XWorkList ) ); pTempWorklist->PutInstallPath( "C:\PROGRAM FILES\CREMOTE\NODESYS" ); _bstr_t newfile( "NEW.EVF" ); pTempWorklist->PutFileName( newfile ); pTempWorklist->ReadFile( VARIANT_FALSE ); long lIndex = pWorklist->GetEventCount(); pWorklist->InsertWorklist( WL_INS_AFTER, lIndex, pTempWorklist ); ... pWorklist->WriteFile(); } catch( const _com_error e ) { if ( e.Error() == E_OUTOFMEMORY ) { int ret = AfxMessageBox( "Did you set the file name?", MB_YESNO ); if ( ret == IDYES ) ErrorMessage(e); } else { ErrorMessage(e); } } catch(...) { AfxMessageBox("General Error"); } CHAPTER 7 / Win32 COM Object Client APIs 401

Win32 IXWorklist API ReadFile Description Reads in events from a worklist file.

IDL Synopsis HRESULT ReadFile( [in] VARIANT_BOOL bAppendonly ); Parameters [in] bAppendOnly If VARIANT_TRUE, only appends to end of file (no insertions). Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Example try { IXWorkListPtr pWorklist( __uuidof( XWorkList ) ); _bstr_t File( "TEMP.EVF" ); pWorklist->PutFileName( File ); pWorklist->ReadFile( VARIANT_FALSE ); } catch( const _com_error& e ) { ErrorMessage(e); } catch(...) { AfxMessageBox("General Error"); } 402 RemoteWare API Manual

Win32 IXWorklist API WriteFile Description Writes out events to a worklist file.

IDL Synopsis HRESULT WriteFile() Parameters None Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Example try { IXWorkListPtr pWorklist( __uuidof( XWorkList ) ); _bstr_t File( "TEMP.EVF" ); pWorklist->PutFileName( File ); pWorklist->ReadFile( VARIANT_FALSE ); _bstr_t NewFile( "NEW.EVF" ); pWorklist->PutFileName( NewFile ); pWorklist->WriteFile( ); } catch( const _com_error& e ) { ErrorMessage(e); } catch(...) { AfxMessageBox("General Error"); } CHAPTER 7 / Win32 COM Object Client APIs 403

Win32 IXWorklist API GetEvent Description Gets an event at a specified location.

IDL Synopsis HRESULT GetEvent ( [in] long Index, [out, retval] XWorklist_Event** ppEvent ); Parameters [in] long Index Index of the event to retrieve. [out, retval] ppEvent The worklist event.

For the definition and values for these enumerations, see “Enumerations and Structures” on page 418. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Example try { IXWorkListPtr pWorklist( __uuidof( XWorkList ) ); _bstr_t File( "TEMP.EVF" ); pWorklist->PutFileName( File ); pWorklist->ReadFile( VARIANT_FALSE ); XWorklist_Event* pEvent = pWorklist-> GetEvent( 0L ); ... ::CoTaskMemFree( pEvent ); } catch( const _com_error& e ) { ErrorMessage(e); } catch(...) { AfxMessageBox("General Error"); } 404 RemoteWare API Manual

Win32 IXWorklist API SetEvent Description Replaces or sets a worklist event at a specified position in the worklist.

IDL Synopsis HRESULT SetEvent ( [in] long Index, [in] XWorklist_Event* pEvent ); Parameters [in] long Index Index of the worklist event to retrieve. [in] pEvent The worklist event. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Example { IXWorkListPtr pWorklist( __uuidof( XWorkList ) ); _bstr_t File( "TEMP.EVF" ); pWorklist->PutFileName( File ); pWorklist->ReadFile( VARIANT_FALSE ); XWorklist_Event* pEvent = pWorklist-> GetEvent( 0L ); ... pEvent->ExecutionMask |= WL_EX_DURING; pWorkList->SetEvent( 0L ); ::CoTaskMemFree( pEvent ); } catch( const _com_error& e ) { ErrorMessage(e); } catch(...) { AfxMessageBox("General Error"); } CHAPTER 7 / Win32 COM Object Client APIs 405

Win32 IXWorklist API vbGetEvent Description Gets an event at a specified location. Used specifically for Microsoft’s Visual Basic

IDL Synopsis HRESULT vbGetEvent ( [in] long Index, [out, retval] VARIANT* pVarEvent ); Parameters [in] Index Index of event to retrieve. Note: The Variant corresponds to the XWorklist_Event structure used in C++ that has had its member variables serialized into an array (0 to 3) of variants where: • the first element is a variant of type long which holds the command, • the second member is a variant of type long which holds the execution mask • the third element is a variant of type long which holds the subfunction mask • the fourth element is a variant which contains an array of strings (0 to x) which contain the event parameters [out, retval] pVarEvent Variant containing the worklist event. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Win32 IXWorklist API vbSetEvent Description Replaces or sets a worklist event at a specified position in the work list. Used specifically for Microsoft’s Visual Basic.

IDL Synopsis HRESULT vbSetEvent ( [in] long Index, [in] VARIANT VarEvent ); Parameters [in] Index The position of the event to set. [in] VarEvent The worklist event. 406 RemoteWare API Manual

Win32 IXWorklist API vbSetEvent (Continued) Note: The Variant corresponds to the XWorklist_Event structure used in C++ that has had its member variables serialized into an array (0 to 3) of variants where: • the first element is a variant of type long which holds the command, • the second member is a variant of type long which holds the execution mask • the third element is a variant of type long which holds the subfunction mask • the fourth element is a variant which contains an array of strings (0 to x) which contain the event parameters Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Win32 IXWorklist API DeleteEvent Description Deletes a worklist event at a specified location.

IDL Synopsis HRESULT DeleteEvent ( [in] long Index, ) Parameters [in] long Index The position of the event to be deleted. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. CHAPTER 7 / Win32 COM Object Client APIs 407

Win32 IXWorklist API DeleteEvent (Continued)

Example try { IXWorkListPtr pWorklist( __uuidof( XWorkList ) ); _bstr_t File( "TEMP.EVF" ); pWorklist->PutFileName( File ); pWorklist->ReadFile( VARIANT_FALSE ); ... pWorklist->DeleteEvent( 0L ); pWorklist->WriteFile(); ... } catch( const _com_error& e ) { ErrorMessage(e); } catch(...) { AfxMessageBox("General Error"); }

Win32 IXWorklist API InsertEvent Description Inserts a worklist event at a specified location.

IDL Synopsis HRESULT InsertEvent ( [in] enum WL_Insert_e InsertType, [in] long Index, [in] struct XWorklist_Event * pEvent ) Parameters [in] InsertType Type of insertion to be performed. [in] Index Position to insert the worklist event. [in] pEvent The worklist event to insert.

For the definition and values for these enumerations, see “Enumerations and Structures” on page 418. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. 408 RemoteWare API Manual

Win32 IXWorklist API InsertEvent (Continued)

E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Example try { IXWorkListPtr pWorklist( __uuidof( XWorkList ) ); _bstr_t File( "TEMP.EVF" ); pWorklist->PutFileName( File ); pWorklist->ReadFile( VARIANT_FALSE ); ... XWorklist_Event Event; memset( &Event, 0, sizeof(XWorklist_Event ) ); Event.Command = WL_CMD_SENDFILE; Event.SubFunctionMask = WL_SUBF_NO_OVERWRITE; Event.ExecutionMask = WL_EX_DURING; ... pWorklist->InsertEvent( WL_INS_FIRST, 0, &Event ); pWorklist->WriteFile(); } catch( const _com_error& e ) { ErrorMessage(e); } catch(...) { AfxMessageBox("General Error"); } CHAPTER 7 / Win32 COM Object Client APIs 409

Win32 IXWorklist API vbInsertEvent Description Inserts a worklist event at a specified location. Used specifically for Microsoft’s Visual Basic.

IDL Synopsis HRESULT vbInsertEvent ( [in] WL_Insert_e InsertType, [in] long Index, [in] const VARIANT varEvent ) Parameters [in] InsertType Type of insertion to be performed. [in] Index Position to insert the worklist event. [in] varEvent The worklist event to insert.

Note: For the definition and values for these enumerations, Note: The Variant corresponds to the XWorklist_Event structure used in C++ that has had its member variables serialized into an array (0 to 3) of variants where: • the first element is a variant of type long which holds the command, • the second member is a variant of type long which holds the execution mask • the third element is a variant of type long which holds the subfunction mask • the fourth element is a variant which contains an array of strings (0 to x) which contain the event parameters Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. 410 RemoteWare API Manual

Win32 IXWorklist API vbInsertEvent (Continued)

Example Sub AddEvent() Set CoWorklist = New XWorkList

CoWorklist.InstallPath = "E:\"'Set Install path to initialize worklist functions CoWorklist.FileName = "E:\test.evf"'Set file name to use

CoWorklist.ReadFile (False)'Load worklist into memory

Dim MyEvent(0 To 3) As Variant Dim Param(0 To 1) As String Dim Command As WL_Command_e Dim Execute As Long Dim Subfunction As Long

Command = WL_CMD_SENDFILE Execute = WL_EX_DURING Or WL_EX_ONCLIENT Subfunction = WL_SUBF_SAFE_SEND Or WL_SUBF_UPDATEFILE Or WL_SUBF_SEND_NEWER

Param(0) = "nodesys\win32\rwclient3.exe" Param(1) = "\rwclient3.exe"

MyEvent(0) = Command MyEvent(1) = Execute MyEvent(2) = Subfunction MyEvent(3) = Param

Call CoWorklist.vbInsertEvent(WL_INS_LAST, 0, MyEvent)

CoWorklist.WriteFile

Set CoWorklist = Nothing

End Sub CHAPTER 7 / Win32 COM Object Client APIs 411

Win32 IXWorklist API InsertFile Description Insert worklist events in a worklist file into the current worklist.

IDL Synopsis HRESULT InsertFile ( [in] WL_Insert_e InsertType, [in] long Index, [in] BSTR pFileName ) Parameters [in] InsertType Type of insertion to be performed. [in] Index Position to insert the worklist event. [in] pFileName The filename of worklist file to be inserted.

Note: For the definition and values for these enumerations, see “Enumerations and Structures” on page 418. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Win32 IXWorklist API InsertWorkList Description Inserts worklist events from another worklist into the current worklist.

IDL Synopsis HRESULT InsertWorklist ( [in] WL_Insert_e InsertType, [in] long Index, [in] IXWorkList* pWorklist ) Parameters [in] InsertType Type of insertion to be performed. [in] Index Position to insert the worklist event. [in] pWorklist The worklist to insert.

Note: For the definition and values for these enumerations, see “Enumerations and Structures” on page 418. 412 RemoteWare API Manual

Win32 IXWorklist API InsertWorkList (Continued)

Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

Example try { IXWorkListPtr pWorklist( __uuidof( XWorkList ) ); _bstr_t File( "TEMP.EVF" ); pWorklist->PutFileName( File ); pWorklist->ReadFile( VARIANT_FALSE ); ... IXWorkListPtr pTempWorklist( __uuidof( XWorkList ) ); pTempWorklist->PutInstallPath( "C:\PROGRAM FILES\CREMOTE\NODESYS" ); _bstr_t newfile( "NEW.EVF" ); pTempWorklist->PutFileName( newfile ); pTempWorklist->ReadFile( VARIANT_FALSE ); long lIndex = pWorklist->GetEventCount(); pWorklist->InsertWorklist( WL_INS_AFTER, lIndex, pTempWorklist ); ... pWorklist->WriteFile(); }

Example (Continued) catch( const _com_error e ) { if ( e.Error() == E_OUTOFMEMORY ) { int ret = AfxMessageBox( "Did you set the file name?", MB_YESNO ); if ( ret == IDYES ) ErrorMessage(e); } else { ErrorMessage(e); } } catch(...) { AfxMessageBox("General Error"); } CHAPTER 7 / Win32 COM Object Client APIs 413

IRWClientStatusEvents API methods The IRWClientStatusEvents are a collection of methods in a single dispatch interface that service events from the RemoteWare API DLL. In this case, these methods can be thought of as DLL callback functions. They exist in the Client application but are called by the API DLL. In order to use this interface, you must first register to accept the messages generated by the RemoteWare API DLL.

Overview RemoteWare 32-bit and OS/2 Client API Clients demonstrate a basic RemoteWare Client constructed using the COM API's and demonstrate use of the dispatch interface. The following table summarizes the IRWClientStatusEvents API methods: Table 37. IRWClientStatusEvents API methods Method Name Description

CommandChange Called when a command change occurs with the RemoteWare Client. StatusChange Called when the status of the RemoteWare Client changes. AlertChange Triggered when an alert is generated for the RemoteWare Client. BytesTransferredChange Triggered whenever the total number of bytes transferred during the current connection is updated. MessageQueueChange Triggered if a change occurs in the incoming or outgoing message queue. DirectoryChange Triggered when there has been a change in the directory duing a RemoteWare session. DefaultEntryChange Triggered when there has been a change in the Default Entry for a RemoteWare Client. 414 RemoteWare API Manual

IRWClientStatusEvents API CommandChange Description Called when a command change occurs with the RemoteWare Client.

IDL Synopsis HRESULT CommandChange ( enum RWC_Command_e Command ) Parameters [in] Command The currently executing command. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

IRWClientStatusEvents API StatusChange Description Called when the status of the RemoteWare Client changes.

IDL Synopsis HRESULT StatusChange ( long NewClientStatusMask, enum RWC_ResourceStatus_e RSCStatus, long ResourceError ) Parameters [in] Current Client status. For the definition and values for NewClientStatusMask RWC_Status_e, see “Enumerations and Structures” on page 418. [in] RSCStatus Resource status. For the valid values, see “Enumerations and Structures” on page 418. [in] ResourceError The error code for the Resource. CHAPTER 7 / Win32 COM Object Client APIs 415

IRWClientStatusEvents API StatusChange (Continued)

Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

IRWClientStatusEvents API AlertChange Description Triggered when an alert is generated for the RemoteWare Client.

IDL Synopsis HRESULT AlertChange ( long NewClientAlertMask ) Parameters NewClientAlertMask Bit mask containing the new Client status. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

IRWClientStatusEvents API BytesTransferredChange Description Triggered whenever the total number of bytes transferred during the current connection is updated.

IDL Synopsis HRESULT BytesTransferredChange ( long BytesTransferred ) 416 RemoteWare API Manual

IRWClientStatusEvents API BytesTransferredChange (Continued)

Parameters BytesTransferred Number of bytes transferred for the current file. Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

IRWClientStatusEvents API MessageQueueChange Description Triggered if a change occurs in the incoming or outgoing message queue.

IDL Synopsis HRESULT MessageQueueChange ( ) Parameters None Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

IRWClientStatusEvents API DirectoryChange Description Triggered when there has been a change in the directory duing a RemoteWare session.

IDL Synopsis HRESULT DirectoryChange ( ) CHAPTER 7 / Win32 COM Object Client APIs 417

IRWClientStatusEvents API DirectoryChange (Continued)

Parameters None Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly.

IRWClientStatusEvents API DefaultEntryChange Description Triggered when there has been a change in the Default Entry for a RemoteWare Client.

IDL Synopsis HRESULT DirectoryChange ( ) Parameters None Return values A Win32 HRESULT indicating the result of the method call. S_OK Indicates the method completed successfully. E_FAIL Indicates the function failed. The value of E_FAIL is returned and the Win32 error text is set accordingly. 418 RemoteWare API Manual

Enumerations and Structures The following enumerations and structures are defined and used in the RemoteWare APIs.

enum RWC_Status_e { RWCS_LOADED = 1, RWCS_AUTOANSWER = 2, RWCS_DIALING = 4, RWCS_CONNECTING = 8, RWCS_PASSWORD = 16, RWCS_CONNECTED = 32, RWCS_DISCONNECTED = 64, RWCS_ESD_DISBALED = 256, RWCS_PORT_RELEASED = 512, RWCS_RESOURCE_READY = 1024 }; enum RWC_ApplyESD_e { RWCAE_FINISHED = 0, RWCAE_ERROR_COPY = 256, RWCAE_ERROR_COPY_READ_ONLY = 1, RWCAE_ERROR_REBOOT = 2, RWCAE_ERROR_NETWORK_FILE_IN_USE = 4, RWCAE_ERROR_UNABLETOREBOOT = 4096 }; enum RWC_PendingOperation_e { RWCO_NONE = 0, RWCO_REINIT = 1, RWCO_UNLOAD = 2, RWCO_CONNECT = 4, RWCO_CANCEL = 16, RWCO_ENABLEAA = 32, RWCO_DISABLEAA = 64, RWCO_RELEASEPORT = 128, RWCO_EANBLEESD = 256, RWCO_DISABLEESD = 512 };

enum RWC_LicenseType_e { RWCLT_APPLICATIONS = 1 }; enum WL_Execute_e { WL_EX_NONE = 0, WL_EX_BEFORE = 1, WL_EX_DURING = 2, WL_EX_AFTER = 4, CHAPTER 7 / Win32 COM Object Client APIs 419

WL_EX_ONSERVER = 8, WL_EX_ONCLIENT = 16, WL_EX_CONDITIONAL = 32, WL_EX_CONDITIONAL_FALSE = 64, WL_EX_CONTROL_VERB = 128 }; enum WL_SubFunction_e { WL_SUBF_NO_OPTIONS = 0, WL_SUBF_NO_OVERWRITE = 1, WL_SUBF_UPDATEFILE = 2, WL_SUBF_SAFE_SEND = 4, WL_SUBF_CRITICAL = 8, WL_SUBF_DELETE_AFTER = 16, WL_SUBF_CRITICAL_RETRY = 32, WL_SUBF_NO_COMPRESS = 64, WL_SUBF_NOT_NEEDED = 128, WL_SUBF_SEND_NEWER = 256, WL_SUBF_RECURSIVE = 512, WL_SUBF_MAKEPATH = 1024, WL_SUBF_WO_CRITICAL = 2048 }; enum RWC_Command_e { RWCC_CMD_NONE = 0, RWCC_CMD_SND = 1, RWCC_CMD_RCV = 2, RWCC_CMD_SWO = 3 }; enum RWC_ResourceStatus_e { RWCRS_READY = 0, RWCRS_ERROR = 1, RWCRS_LOAD_FAILED = 2, RWCRS_OPEN_FAILED = 3, RWCRS_INIT_FAILED = 4, RWCRS_BUSY = 128, RWCRS_LOADING = 255, RWCRS_UNLOADING = 254, RWCRS_REINITING = 253, RWCRS_RELEASING = 252 }; enum RWC_ResourceType_e { RWCRT_NONE = -1, RWCRT_ASYNC = 0, RWCRT_NETBIOS = 2, RWCRT_TCPIP = 5, RWCRT_SPX = 6 }; enum RWC_Session_e { 420 RemoteWare API Manual

RWCSS_NONE = 0, RWCSS_SUCCESSFUL = 1, RWCSS_ABORTED = 2, RWCSS_TIMEOUT = 3, RWCSS_LOST_CONNECTION = 4, RWCSS_PASSWORD_FAIL = 5, RWCSS_CANCELED = 6, RWCSS_NO_ANSWER = 7, RWCSS_RESOURCE_ERROR = 8, RWCSS_SERVER_DOWN = 9, RWCSS_SERVER_SUSPENDED = 10, RWCSS_SCHEDULER_OFF = 11, RWCSS_NODE_DISABLED = 12, RWCSS_NODE_UNDEFINED = 13, RWCSS_NODEREG_DISABLED = 14 };

enum RWC_Alert_e { RWCA_RESOURCEERROR = 1, RWCA_ESDAVAILABLE = 2, RWCA_ESDDISABLED = 4, RWCA_AUTOANSWEROFF = 8, RWCA_CLIENTNOTIFICATION = 16 }; enum WL_Insert_e { WL_INS_FIRST = 0, WL_INS_LAST = 1, WL_INS_BEFORE = 2, WL_INS_AFTER = 3 }; enum WL_Command_e { WL_CMD_SENDFILE = 1, WL_CMD_GETFILE = 2, WL_CMD_CHECK_SENDFILE = 50, WL_CMD_RENAMEFILE = 5, WL_CMD_DELETEFILE = 6, WL_CMD_COPYFILE = 7, WL_CMD_APPENDFILE = 8, WL_CMD_FILESTAT = 9, WL_CMD_DIRECTORY = 10, WL_CMD_CHECKDISK = 11, WL_CMD_MAKEDIR = 12, WL_CMD_REMOVEDIR = 13, WL_CMD_SETTIME = 14, WL_CMD_CHECK_FILE = 40, WL_CMD_EXECUTE = 15, WL_CMD_WORKLIST = 16, WL_CMD_NOTIFY = 17, WL_CMD_EXCEPTION = 34, WL_CMD_GROUP_TEST = 35, CHAPTER 7 / Win32 COM Object Client APIs 421

WL_CMD_SET_VARIABLE = 37, WL_CMD_TEST_VARIABLE = 38, WL_CMD_COMMENT = 36, WL_CMD_UNASSIGN = 42, WL_CMD_REBOOT_CLIENT = 19, WL_CMD_WAIT = 21, WL_CMD_ASCII_APPEND = 22, WL_CMD_USER_ALARM = 23, WL_CMD_END_SESSION = 24, WL_CMD_END_WORKOBJ = 43, WL_CMD_XCHG_MSGQUE = 41, WL_CMD_READ_VAR_FILE = 44, WL_CMD_SET_REGISTRY = 45, WL_CMD_GET_REGISTRY = 46, WL_CMD_DELETE_REG_VALUE = 47, WL_CMD_CREATE_REG_KEY = 48, WL_CMD_DELETE_REG_KEY = 49, WL_CMD_IF_TRUE = 27, WL_CMD_IF_FALSE = 28, WL_CMD_ELSE_IF = 29, WL_CMD_END_IF = 30, WL_CMD_REPEAT_IF_TRUE = 31, WL_CMD_REPEAT_IF_FALSE = 32, WL_CMD_END_REPEAT = 33 }; struct XWorklist_Event { enum WL_Command_e Command; long ExecutionMask; long SubFunctionMask; short RepeatCount; long ParamCount; BSTR * ParamList; }; 422 RemoteWare API Manual

Client ActiveX Controls The RemoteWare 32-bit Client software includes an ActiveX control you can use to add selected Client functionality to ActiveX or OLE container applications that you develop or purchase. The control is automatically installed and registered with Windows NT or Windows 95 when the RemoteWare 32-bit Client software is installed.

Client ActiveX Control Directory Control Description The RemoteWare Directory ActiveX Control provides methods, properties, and events to display and control the Directory folder window for a Client. This window can include the ability to connect using a specified Directory Entry. Using the Directory The RemoteWare Directory Control’s methods, properties, and Control events are provided through the RWCDRCTY.OCX file, which is automatically installed and registered when the 32-bit Client software is installed.

Note: The RemoteWare Directory Control is only useful on a system that has the RemoteWare 32-bit Client software version 3.2 or higher installed. After a RemoteWare Directory Control is added to an OLE container application, OLE automation can be used with the control’s methods, properties, and events to initiate, monitor, and control 32-bit Client connections. Binding the control to To use an instance of the RemoteWare Directory Control, the a Client control’s ClientName property must first be assigned a valid RemoteWare Client Name, either at runtime or design time.

The ClientName property binds the control instance to a particular Client software installation on the system. That particular Client’s configuration and operating files are subsequently accessed by the control instance’s methods and properties, and only events for that Client cause event triggers for the control instance.

Note: The ClientName property is needed because a system can have multiple copies of Client installed, each with its own corresponding files and connections. CHAPTER 7 / Win32 COM Object Client APIs 423

Client ActiveX Control Directory Control (Continued)

Properties ClientName Assign a valid RemoteWare Client Name to this property. The named Client must be installed on the current system at runtime.

Note: This property must be assigned before any methods or events or any other properties become useable. Type: BSTR Mode: Read/Write AllowConnection True activates the Connect button in the dialog that displays when a user double-clicks a directory entry. False disables that button, preventing a user from connecting via the Directory folder window.

Type: BSTR Mode: Read/Write DefaultEntryName This contains the name of the Default Directory Entry for the selected Client.

Type: BSTR Mode: Read/Write DefaultEntryResource This contains the type of resource used by the Default Directory Entry for the selected Client.

Type: BSTR Mode: Read/Write TotalEntries This is the number of entries contained in the selected Client’s Directory folder (excluding the Add New Entry item).

Type: BSTR Mode: Read/Write View This indicates/sets the view type used in the Directory folder window, as follows:

0 Large icon view 1 List view 2 Horizontal small icon view 3 Vertical small icon view

Type: I2 BSTR: Read/Write 424 RemoteWare API Manual

Client ActiveX Control Directory Control (Continued)

Events DirectoryModified() Triggered if the Directory for the selected Client is modified. DefaultChanged() Triggered if the Default Directory Entry for the selected Client is changed. Connect(lpszEntryName Triggered if a user connects using the Directory folder window. ) The event passes the name of the Directory Entry used to make the connection in lpszEntryName. lpszEntryName See also the AllowConnection property presented previously. BeginEntryNameEdit() Triggered when a user invokes the Directory Entry edit dialog for an entry. EndEntryNameEdit() Triggered when a user closes the Directory Entry edit dialog for an entry. Methods EditEntry (BSTR lpszEntryName) This invokes the Edit Entry dialog for the directory entry specified (by name) in the lpszEntryName argument.

Return value

I4 Valid return values are:

1 Dialog ended with OK button.

2 Dialog ended with Cancel button (or Escape), or error occurred; most likely an invalid entry name was passed. RemoveEntry (BSTR lpszEntryName) This removes the directory entry specified (by name) in the lpszEntryName argument.

Return value

BOOL True if successful, False if not successful (probably because an invalid entry name was passed). CHAPTER 7 / Win32 COM Object Client APIs 425

Client ActiveX Control Directory Control (Continued)

RenameEntry (BSTR lpszCurrentName, BSTR lpszNewName) This renames the directory entry currently having the name specified in the lpszCurrentName to the new name specified in lpszNewName.

Return value

BOOL True if successful, False if not successful (probably because an invalid current entry name was passed). AddEntry (BSTR lpszEntryName) This adds a directory entry with the name specified in the lpszEntryName argument. This will automatically update the TotalEntries property.

Return value

I4 Index to the new entry (which is 0 relative; that is, the first entry has an index of 0). GetEntryNameFromIndex (I4 IEntryIndex) This returns the name of the directory entry specified by the IEntryIndex argument (which is 0 relative; that is, the first entry has an index of 0). Among other things, this is useful in building an array of entry names using a loop from 1 to the value in the TotalEntries property.

Return value

BSTR Name of the entry at the specified index. Will be empty if an invalid index was passed. 426 RemoteWare API Manual

Client ActiveX Control Directory Control (Continued)

GetEntryResourceFromIndex (I4 IEntryIndex) This returns the type of communication resource defined for the directory entry specified by the IEntryIndex argument (which is 0 relative; that is, the first entry has an index of 0). Among other things, this is useful in building an array of entry resources using a loop from 1 to the value in the TotalEntries property.

Return value

BSTR Name of the entry at the specified index. Will be empty if an invalid index was passed. IsEntryDirectConnectFromIndex (I4 IEntryIndex) This indicates whether the resource directory entry specified (by index) in the IEntryIndex argument is a direct connect type.

Return value

BOOL True if resource is direct connect, otherwise False. IsEntryReadOnly (BSTR lpszEntryName) This indicates whether the directory entry specified (by name) in the lpszEntryName argument is a read-only entry that cannot be edited.

Return value

BOOL True if entry is read-only, otherwise False. IsItemSelected (BSTR lpszEntryName) This indicates whether the directory entry specified (by name) in the lpszEntryName argument is currently selected in the Directory folder window.

Return value

BOOL True if entry is selected, otherwise False. CHAPTER 7 / Win32 COM Object Client APIs 427

Client ActiveX Control Directory Control (Continued)

SelectEntry (BSTR lpszEntryName) This selects in the Directory folder window the directory entry specified (by name) in the lpszEntryName argument.

Return value

BOOL True if successful, False if not successful (probably because an invalid entry name was passed). GetNextSelectedItem (BSTR lpszFromThisName) This returns the name of the directory entry that is currently selected. If an lpszFromThisName argument is passed, a selected entry is searched for only from the entry specified in lpszFromThisName to the end of the directory entry list. If no lpszFromThisName argument is passed, the current entry is always returned.

Return value

BSTR Name of the next selected entry. Will be empty if no selected entry was found in the range from the specified starting entry to the end of the list. ShowMakeNewEntryItem (BOOL bVisible) If bVisible is passed as True, this shows the Make New Entry item in the Directory folder window. If bVisible is passed as False, this hides the Make New Entry item.

Return value

BOOL True if state specified in bVisible was already set, otherwise False. AboutBox () Displays the RemoteWare Client Control’s About Box dialog. RefreshList () Not yet implemented. 428 RemoteWare API Manual CHAPTER 7 / Win32 COM Object Client APIs 429 430 RemoteWare API Manual APPENDIX A

1 Dial Scripts

The Dial Script command “DLLCALL” allows administrators to execute customized code from a dial script on a RemoteWare Server or Windows Client. This appendix describes the methods for using dial scripts. 432 RemoteWare API Manual

Using DLLCALL The Dial Script command “DLLCALL” allows administrators to execute customized code from a dial script on a RemoteWare Server or 16-bit Windows Client. The customized code is compiled into a Windows DLL called RWWDSEXT.DLL. Note: If executed on a Windows Client, Dial Script functions are available only for 16- bit programs. The basic command syntax is: DLLCALL iCommand "Optional Text" where “iCommand” is an integer value that identifies the customized code, which is defined by the developer of the custom code. This argument can be followed by a optional string text that will be passed as an argument to the DLL. The dial script command actually calls a function in the DLL called DialScriptExternalCommand(). The following example uses this function to send a BREAK signal to the port. The BREAK signal code is represented by a 1, and it accepts a string which represents the number of milliseconds to send the BREAK signal. For example: DLLCALL 1 "1000" would turn the BREAK signal “ON” for 1 second (1000 milliseconds). /======* * FILE: rwsdsext.c - Dial Script External Command DLL source file. * *======*/ #include #include #include "rwsdsext.h"

#define DEFAULT_DELAY 1000 //======// DialScriptExternalCommand // ------// // Parameters: // ------// HANDLE hComDev Handle to COM device // INT iCommand Command index (see below) // CHAR* pszParameters Command Paramters //

// Returns: // ------// 0 if successful, else Win32 error code. Appendix A 433

/======INT _cdecl DialScriptExternalCommand( HANDLE hComDev, INT iCommand, CHAR * pszParameters ) { ULONG ulMilliseconds = 0; INT iReturnCode = 0;

switch ( iCommand ) { case DS_COMMAND_BREAK: { iReturnCode = SetCommBreak(hComDev);

if ( iReturnCode ) { ulMilliseconds = DEFAULT_DELAY;

if ( pszParameters != NULL ) { ulMilliseconds = atol( pszParameters );

if ( ulMilliseconds == 0L ) ulMilliseconds = DEFAULT_DELAY; }

Sleep( ulMilliseconds );

iReturnCode = ClearCommBreak(hComDev); }

break; }

default: break; }

if (!iReturnCode) return GetLastError(); else return 0; } 434 RemoteWare API Manual Index

SYMBOLS ALARM_SERVER_SUSPENDED alarm type 32 ALARM_TEXT_SIZE constant 33, 34 #ifdef check 164 ALARM_USER_DEFINED alarm type 31, 33, 34 ^Z (end of file) check 148 setting with RWSSetUserAlarm() 34 _NewEnum 374, 375, 377, 378 ALARM_XSUPPORT alarm type 31 AlertChange 413, 415 NUMERICS AlertExplanation 306 0 (zero) return value 124, 126 AlertExplanation method 305 16-bit Client APIs Alerts 249, 338, 345 and Microsoft Visual C++ versions tested with 110 Alerts method 242 and RWNAPI.H 110 AllowUnregisteredClients 377, 382, 384 and RWNAPI.LIB 110 API functions troubleshooting after compiling 110 server information function 104, 107 4680 client 157, 158 worklist functions 35 8.3 filename 77, 84, 89, 90, 92, 94 APPEND file(s) to another 190, 191, 205, 206, 207, 208, 209, 210, 214, 215, 222, 223, 224, 233, 234 A ApplyESD 261, 340, 362 ApplyESD method 243 abNodeTypes member 157 ASCII text file 189 Additional information sources xvi Auto-answer string 167 Address 267, 271, 272, 322, 335 AIX client 157, 158 B Alarm API functions 31 Alarm types 31 bAppendOnly parameter 401 ALARM_CLIENT_DISK_FULL alarm type 31, 33, bClientType field 82 34 bCmd member 60 ALARM_FATAL_ERROR alarm type 31, 33, 34 bExecution field 81 ALARM_LOW_MEMORY alarm type 31 bExecution member 156 ALARM_MANUAL_CLIENTREG alarm type 32, bFilterFlag member 97 33, 34 bLaunchMode field 81 ALARM_MODEM_ERROR alarm type 31, 33, 34 bMemberType field 98 ALARM_MTA_FAILURE alarm type 32, 33, 34 BOOL data type 26 ALARM_PORT_FAILURE alarm type 31, 33, 34 bResource member 120, 130, 172, 174 ALARM_SCHEDULER_FULL alarm type 31 bRscStatus member 121, 131, 173 ALARM_SCHEDULER_LOADING alarm type 31 bSessStatus member 118, 129, 171 ALARM_SCHEDULER_OFF alarm type 31 bStatusMask field 73 ALARM_SCHEDULER_OVERRUN alarm type bStatusMask member 60, 63 31, 34 BSTR ppStatus parameter 332 ALARM_SECURITY_FAILURE alarm type 32 bType field 81, 97, 98 ALARM_SERVER_DISK_FULL alarm type 31 bType member 156 ALARM_SERVER_DOWN alarm type 31, 33 bTypeFilter member 97 ALARM_SERVER_REBOOT alarm type 31, 34 bValidMask member 61 436 RemoteWare API Manual

bWhen parameter 44, 143 Communications port bWhere parameter 43, 143 changing data rate 125 BYTE data type 26 specifying for dialed connections 123 bytes_transfered member 120, 172 compilers 164 BytesTransferred parameter 416 Compiling and linking BytesTransferredChange 413, 415 16-bit Windows APIs 110 32-bit OS/2 Client APIs 111 C DOS Client APIs 164 Component Object Model 235 C function data type 26 Connect 257, 339, 359 C string data type 26 Connect method 242 Cancel 260, 340, 361 ConnectedSystem member 121, 173 Cancel method 243 Constants case-sensitive file systems 179 XS_COUNTER_MASK 168 cb field 40 XS_RSC_LOAD_FAILED 174 cbData parameter 123, 125 COPY file(s) 195 cbInfo parameter 117, 122, 169, 174 Count 374, 376, 377, 381 cbMsg parameter 135, 138, 140, 389, 392, 394 CreateEntry 315, 317, 318 cbObjInfoRec parameter 155 cRecsToRead parameter 59, 62, 71 cbObjQueryRec parameter 159 CurrentBytesTransferred 338, 348 CHAR data type 26 CurrentCommand 338, 347 CHECK DISK drive(s) 192 CurrentFileName 338, 347 CHECK FILE ServerFile ClientFile 193 CurrentFileSize 338, 348 Client Configuration and Status API functions 112 CurrentServerID 338, 344 Client Dialing Directory API 153 CurrentServerName 338, 343 Client Object API function summary 154 CurrentSWO 338, 345 Client setup data letting your program read the 123 D writing changes to 125 Client Worklist API function summary 141 Data pointer data type 26 CLIENTCMTREC structure 65, 67 Data Types 26 ClientID 242, 246 Date 322, 324 CLIENTINFOREC structure 67 DefaultClientName 377, 385 ClientName 242, 243, 244, 338, 341 DefaultEntryChange 413, 417 ClientStatus 248, 338, 342 DefaultResource 250 ClientStatus method 242 DefaultResource method 242 Clustered Server down alarm 31 DELETE file(s) 196 CNODEAPI.LIB 164 DeleteEvent 395, 406 COM 235 Dial Directory 70 COM port error alarm 31 Dial Script command 431, 432 command member 120, 172 Dial Tone 73 Command parameter 414 Dialing directory dialog box 153 CommandChange 413, 414 DialScriptExternalCommand() function 432 CommandExecuting 291 DIRectory listing 197 COMMENT 213 DirectoryChange 413, 416 Index 437

DisableESD 267, 275 388 DLLCALL command 431, 432 E_RWN_EOF error code 112, 165 Documentation related publications xiv E_RWN_PARAM error code 112, 165 DOS client 157 E_RWS_AUTOASN_FAILED error code 30 DOS Client APIs 164 E_RWS_CONFLICT error code 30 DOS Client Configuration and Status API functions E_RWS_DISABLED error code 25, 30 165, 169 E_RWS_DISABLED value 103 DOS error code 143 E_RWS_EOF error code 30 DOS NetBIOS client 157, 158 E_RWS_EOF error type 61, 64, 66, 70, 74 Drive names 179 E_RWS_EOF return value 124, 126 Duration 322, 325 E_RWS_EXISTS error code 30 E_RWS_EXISTS error type 82, 91 E E_RWS_FAILED error code 30 E_RWS_IN_USE error code 30 E 85, 94 E_RWS_IN_USE error type 84, 89, 91, 93, 94 E_FAIL result 238 E_RWS_INCOMPLETE error code 30 E_PIPE_BAD_PIPE error code 134, 388 E_RWS_INCOMPLETE error type 83, 84 E_PIPE_BROKEN error code 134, 388 E_RWS_INVALID_KEY error code 30 E_PIPE_BUFFER_FULL error code 134, 388 E_RWS_INVALID_KEY error type 84, 87, 89, 91, E_PIPE_BUSY error code 134, 388 93 E_PIPE_CONNECTING error code 134, 388 E_RWS_INVALID_OWNER error code 30 E_PIPE_INSUFFICIENT_BUFFER error code E_RWS_INVALID_OWNER error type 93, 94 134, 388 E_RWS_LICENSING error type 83 E_PIPE_INVALID_CLIENTS error code 388 E_RWS_LOW_MEMORY error code 30 E_PIPE_INVALID_DIRENTRY error code 388 E_RWS_MAX error code 30 E_PIPE_INVALID_HANDLE error code 388 E_RWS_MSG_LOGGED error code 30 E_PIPE_INVALID_HANDLES error code 134 E_RWS_MSG_LOGGED error type 93, 94 E_PIPE_INVALID_HDDIR error code 134 E_RWS_NO_RENDEL error code 30 E_PIPE_INVALID_PARAMETER error code 388 E_RWS_NO_RENDEL error type 84, 91 E_PIPE_INVALID_PARAMETERS error code 134 E_RWS_NOAPPREGFILE error code 30 E_PIPE_MORE_DATA error code 134, 388 E_RWS_NOCLIENTS error code 25, 30 E_PIPE_NO_DATA error code 134, 388 E_RWS_NOCLIENTS error type 102 E_PIPE_NODE_NOT_LOADED error code 133, E_RWS_NOT_EXISTS error code 30 387 E_RWS_NOT_EXISTS error type 84, 85, 86, 87, 89, E_PIPE_NOT_AVAILABLE error code 133, 387 91, 93, 94 E_PIPE_NOT_CONNECTED error code 134, 388 E_RWS_PARAM error code 25, 30 E_PIPE_NOT_ENOUGH_MEMORY error code E_RWS_PARAM error type 57, 61, 64, 66, 70, 74, 82, 388 89, 91, 98, 100, 102, 105 E_PIPE_NOT_FOUND error code 134, 387 E_RWS_PARAM return value 124, 126 E_PIPE_OK error code 151 E_RWS_SCHED error code 25, 30 E_PIPE_OK return value 137, 139 E_RWS_SCHED value 103 E_PIPE_OK value 390, 391, 393, 394 E_RWS_UNDEFINED error code 30 E_PIPE_TIMEOUT error code 134, 388 Electronic Software Distribution (ESD) 74 E_PIPE_TOOMANY error code 134, 388 ELSE IF 213 E_PIPE_TRANSPORT_ERROR error code 134, 438 RemoteWare API Manual

EnableAutoAnswer 267, 273 EXECUTE program 198 END IF 214 END SESSION 217 F EndTime 284, 288 FALSE return value 174 EnumerateEntryNames 315, 316 False return value 122 Enumerations, defined 418 FAR data type 26 EnumRWClientInfo Object 240 fClientMask parameter 70 Error codes 24 fCompressFile parameter 152 description 30 fFlags member 160 DOS 143 fh parameter 145, 152 DOS Client APIs 165 File names E_RWN_EOF 165 indirect 229, 232 E_RWN_PARAM 165 literal 179 OS/2 32-bit Client APIs 112 wild card 180, 182, 185, 190, 191, 195, 196, 197, Transaction Pipe function 133, 387 202 types of 24 File Transfer log 56 using 24 file_size member 120, 172 Windows 16-bit APIs 112 FileBytesTransferred 284, 294 error codes FileName 395, 398 E_PIPE_BAD_PIPE 388 filename member 120, 172 E_PIPE_BROKEN 388 FileTransferring 284, 292 E_PIPE_BUFFER_FULL 388 FL_COMPRESS value 61 E_PIPE_BUSY 388 FL_FAILED value 60 E_PIPE_CONNECTING 388 FL_FILESIZE value 61 E_PIPE_INSUFFICIENT_BUFFER 388 FL_GETFILE value 60 E_PIPE_INVALID_CLIENTS 388 FL_NO_EXECUTE value 60 E_PIPE_INVALID_DIRENTRY 388 FL_SENDFILE value 60 E_PIPE_INVALID_HANDLE 388 FL_SUCCESS value 60 E_PIPE_INVALID_PARAMETER 388 Flags E_PIPE_MORE_DATA 388 INCL_RWN_NODE 117, 123, 125, 127, 169 E_PIPE_NO_DATA 388 INCL_RWN_PIPE 135, 138, 139, 142, 145 E_PIPE_NODE_NOT_LOADED 387 XS_AUTO_ANSWER flag 167 E_PIPE_NOT_AVAILABLE 387 XS_CONNECTED 120, 121, 167, 172, 173 E_PIPE_NOT_CONNECTED 388 XS_CONNECTING 167 E_PIPE_NOT_ENOUGH_MEMORY 388 XS_DIALING 167 E_PIPE_NOT_FOUND 387 XS_DISCONNECTED 118, 167, 171 E_PIPE_TIMEOUT 388 XS_ESD_DISABLED 168 E_PIPE_TOOMANY 388 XS_LOADED 167 E_PIPE_TRANSPORT_ERROR 388 XS_PASSWORD 167 Error handler 24 XS_PORT_RELEASED 168 Error handling 24 XS_RESOURCE_READY 168 error handling 238, ??–240 fLastStatus parameter 70 EventCount 395, 399 flFlags field 80, 81 EXCEPTION worklist 229 flFlags member 156 Index 439

fLock parameter 84, 91 INCL_RWN_PIPE flag 135, 137, 138, 139, 142, 145, fMsgType member 63 152, 153, 154, 155, 159, 389, 391, 392, 393 ForceIfConnected parameter 260 INCL_RWN_WORKLIST flag 144 fReadPos parameter 59, 62, 65, 67, 71 INCL_RWS_WORKLIST flag 28 fReadType parameter 57 Include files fStopQuery member 160 RWNAPI.H 110 fulOptions parameter 135, 137, 389, 391 RWSAPI.H 28 WINDOWS.H 110 G windows.h 28 Index parameter 324, 325, 327, 329, 330, 332, 333, GET DIRectory files from Client 182, 186 335, 369, 375, 379, 405 GET file from Client 180 Indirect file 229, 232 get FILE STATUS 199 Initialize 259, 340, 360 GetEntry 315, 320 Initialize method 243 GetEvent 395, 403 InQBytesTransferred 284, 296 Guide InQCurrentMessage 284, 296, 339, 352 audience for vii INQCurrentMessageBytes 339, 353 Guide, what’s in the xiii INQCurrentMessageBytesTransferred 339, 354 InQCurrentMessageBytesTransferred 284, 298 H InQMAPIMessagesTransferred 284, 299, 339, 355 hdd parameter 153 InQTotalBytes 339, 350 HDDIR_DEFAULT value 153 INQTotalBytesTransferred 339, 351 header file InQTotalMessages 284, 295, 339, 349 RWNAPI.H 144 insert WORKLIST 232 rwnapi.h 152, 155 InsertEvent 395, 407 Header files InsertFile 411 RWNAPI.H 113, 123, 125, 127, 135, 137, 138, 391, InsertType parameter 407, 409 392 InsertWorklist 411 hq parameter 52, 53, 54 InsertWorlist 395 HRESULT 238 InstallPath 242, 245, 264, 265, 338, 344, 395 HRWNPIPE 135, 389 InstallPath() 397 hrwp parameter 137, 138, 139, 391, 392, 393 INT data type 26 hwnd parameter 154 Interactive sessions 167 hWorklist parameter 47, 48, 49 Interactive sessions and RWNodeRequest() 114 Interface Definition Language 237 I iQueryLevel parameter 104 iRecordNumber field 40 iAction parameter 146 iRecordNumber member 39, 47, 48 iCommand parameter 432 iRecordNumber parameter 48 IDL 237 IRWClient API Methods 242–263 IF previous event FALSE 219 IRWClient API methods ??–263 IF previous event TRUE 218 IRWClientDialingDirectory API 315–321 iInfoLevel parameter 127, 128, 129, 130, 131 IRWClientDialingEntry API 267–283 INCL_RWN_NODE flag 113, 117, 123, 125, 127, IRWClientDialingEntryCollection API methods 374 169 440 RemoteWare API Manual

IRWClientInfo API methods 264–266 Local Area Network (LAN) 177, 386 IRWClientInfoCollection API LONG data type 26 description 377 long Index parameter 403, 404 IRWClientSessionResultLog API 322–337 LongSessionResult 308 IRWClientStatus API 338–363 LongSessionResult method 305 IRWClientTextExplanation API 305–314 IRWClientWOSelection API 364–373 M IsLicensed 264, 266 Macintosh client 157, 158 IsLicensed method 266 MAKE DIRectory 200 ISupportInfoError interface 238 MAX_COMMENTDATA constant 65 IsUsingDefaults 364, 366 Members Item 374, 375, 377, 379 bResource 120, 130, 172 IXWorklist API bRscStatus 121, 131, 173, 174 description 394 bSessStatus 118, 129, 171, 172 bytes_transfered 120, 172 K command 120, 172 KEYLGT constant 77 ConnectedSystem 121, 173 file_size 120, 172 L filename 120, 172 last_session 118, 170 last_session member 118, 170 node_drive 120, 172 LastSessionStatus 339, 357 node_major 120, 172 LastSessionStatusText 339, 358 node_minor 120, 172 lDiskFree member 70 nRscError 121, 131 lDiskSize member 70 schedule_time 124, 126 Library files 164 StartTime 121, 173 RWNOAPI.LIB 111 status 118, 170 RWNWAPI.LIB 110 wNodeStatus 129 RWSRUNTM.LIB 29 Message Log 34, 93, 94, 229, 231 Linking libraries Message log 56, 90 CNODEAPI.LIB 164 MessageQueueChange 413, 416 LNODEAPI.LIB 164 Microsoft Visual C++ MNODEAPI.LIB 164 and DOS Client APIs 164 RWNWAPI.LIB 164 ML_DEBUG value 63 SNODEAPI.LIB 164 ML_ERROR value 63 Literal file name 179 ML_FATAL_ERROR value 63 lMemFree member 70 ML_INFO value 63 lMemSize member 70 ML_USER value 63 LNODEAPI.LIB 164 MNODEAPI.LIB 164 Load 256, 339, 358 Modem dialing 73 Load method 242 MSGLOGREC structure 62 Loader running alarm 31 MyAlert() function (example) 24 Local Area Network and Transaction Pipe API functions 132 Index 441

N O

Name 264, 267, 268, 269 OBJECTREC structure 77, 95 Named pipe 229, 230 ObjInfoRec field 160 Named Pipe Server process, and Transaction Pipe ObjInfoRec member 160 API functions 132, 386 OBJLGT constant 77 Named pipes 132, 177, 386 OBJQUERYREC structure 95, 96 Named queue 229, 230 Operating system events 189 ND_ATTRIBUTES value 70, 73 OS/2 32-bit Client APIs ND_ESD value 70 and Microsoft Visual Age versions tested with 111 ND_FAIL value 70 and RWNOAPI.LIB 111 ND_NOCONNECT value 70 compiling and linking 111 ND_SUCCESS value 70 troubleshooting after compiling 111 ND_SWOSELECTION value 70 OS/2 client 157 NewClientAlertMask parameter 415 OS/2 named pipe 229, 230 NewClientStatusMask parameter 414 OS/2 node 82 No auto-answer string 167 OutQBytesTransferred 301 Node disk full alarm 31 OUTQCurrentMessage 339, 353 Node Work Object APIs 154 OutQCurrentMessage 285, 302 node_drive member 120, 172 OUTQCurrentMessageBytes 339, 354 node_major member 120, 172 OutQCurrentMessageBytes 285 node_minor member 120, 172 OUTQCurrentMessageBytesTransferred 339, 355 Notification types OutQCurrentMessageBytesTransferred 303 Transaction Pipe 133 OUTQMAPIMessagesTransferred 339, 356 notification types OutQMAPIMessagesTransferred 285, 303 RWPN_BROKEN 387 OUTQTotalBytes 339, 351 RWPN_CALLING 387 OUTQTotalBytesTransferred 339, 352 RWPN_CONNECTED 387 OUTQTotalMessages 339 RWPN_CONNECTING 387 OutQTotalMessages 285, 300, 350 RWPN_DISCONNECTED 387 RWPN_LOADING 387 P RWPN_MESSAGE 387 pAlertMask 249 RWPN_REINITIALIZING 387 pAllow parameter 382, 384 RWPN_UNLOADING 387 pApplyResult parameter 261, 362 Transaction Pipe 387 Parameters NOTIFY command 24, 51, 54 bAppendOnly 401 NOTIFY event 53, 54, 177 BSTR ppStatus 332 NOTIFY signal 230 bWhen 143 NOTIFY WinNT server 230 bWhere 143 nRscError member 121, 131, 132 BytesTransferred 416 nRscError parameter 131 cbData 123, 125 NULL-terminated data types 26 cbInfo 117, 122, 169, 174 cbMsg 135, 138, 140, 389, 392, 394 Command 414 442 RemoteWare API Manual

fh 145 ppEvent 403 fulOptions 135, 137, 389, 391 ppFileBytes 292 hrwp 137, 138, 139, 391, 392, 393 ppFileName 398 iAction 146 pPlaySession 256 iInfoLevel 127, 128, 129, 130, 131 ppName 264, 268, 269, 290, 369 Index 324, 325, 327, 329, 330, 332, 333, 335, 369, ppPath 265, 396 379, 405 ppSWOExecuting 291 InsertType 407, 409 ppText 306, 308, 309, 311, 313 long Index 403, 404 ppUnkRWClientWOSelection 282 NewClientAlertMask 415 pReadOnly 279 NewClientStatusMask 414 pResourceError 252, 333 nRscError 131 pResourceType 278, 333 pAlertMask 249 prwpo 135, 389 pAllow 382 pSecond 325 pApplyResult 261, 362 pSelected 369 pBytesTransferred 294, 296, 298, 301, 303 pSerialNumber 289, 330 pcbActual 138, 392 pServerName 329 pcchText 128 pServerOriginated 327 pCommand 291 pSessionStatus 286 pCount 365 pStartTime 287, 288 pData 123, 125 pStatus 252, 332 pDate 324 pStatusMask 248 pDefaultSelection 369 pStsInfo 127 pDisable 275 pszClient 389 pEnable 273, 274 pszParam1 142 pEvenCount 399 pszParam2 142 pEvent 404, 407 pszPipeName 135, 389 pfh 144 pszText 127, 128 pFileName 292, 411 pszWorklistFile 142, 144 pFullPath 385 pTotalBytes 295, 300 phrwp 135, 139, 389 pTotalMessages 295, 300 pID 246 pTransferred 299, 304 pInfo 117, 169 pType 252 pMajorVersion 247 puiCount 146 pMessage 297, 302 puiReadWriteCount 146 pMessageSize 297, 302 pUseDefaults 366 pMinorVersion 247 pVal 341, 342, 343, 344 pName 317, 319, 320, 371 pVarEvent 405 pNumEntries 323 pvMsg 135, 138, 139, 389, 392, 393 ppAddress 271, 272, 335 pWorklist 411 ppClientName 385 pWorklistRec 146 ppDirectory 316 RebootIfNecessary 261, 362 pPendingOperationsMask 253 resource 308, 311, 313 ppEntry 250, 317 ResourceError 308, 311, 313, 414 Index 443

ResourceType 317 pflogBuf parameter 59 retval 376, 379 pFullPath parameter 385 RSCStatus 414 phq parameter 51 RWNOPEN 136 phrwp parameter 135, 139, 389 RWNPipeClose() 137 pID parameter 246 RWNPipeRead() 138 piError parameter 52, 53, 54, 57 RWNPOPEN 135 pInfo parameter 117, 169 RWNSTSINFO 128 pinfoBuf parameter 67 sCommand 142, 147 Pipes 177 Select 371 Placeholders 230 session 308, 311 PlayLastSessionOnNameChange 254, 255, 339, 356, status 311, 313 357 statusmask 306 PlayLastSessionOnNameChange method 242 ulOptions 143 pMajorVersion parameter 247 ulTimeout 138, 392 pMessage parameter 297, 302 VarEvent 405 pMessageSize parameter 297, 302 varEvent 409 pMinorVersion parameter 247 wRequest 114, 115, 166, 167 pmlogBuf parameter 62 XNODE_DATA 123, 125 pName parameter 317, 319, 320, 371 XNODE_DATA_SIZE 123 pNumEntries parameter 323 XNODE_INFO 117, 170 pObjectQueryRec parameter 95, 100 PASCAL data type 26 pObjectRec parameter 77, 83, 87, 89 Password 74 pObjInfoRec parameter 155 pBytesTransferred parameter 294, 296, 298, 301, 303 pObjQueryRec parameter 159 pcbActual 138 ppAddress parameter 335 pcbActual parameter 138, 392 ppClientName parameter 385 pcchText parameter 128 ppDirectory parameter 316 pcmntBuf parameter 65 pPendingOperationsMask parameter 253 pCount parameter 365 ppEntry 250 pcRecsRead parameter 59, 62, 72 ppEntry parameter 250, 251, 317, 320 pData parameter 123, 125 ppEvent parameter 403 pDate parameter 324 ppFileName parameter 398 pDefaultSelection parameter 369 pPlaySession parameter 254, 255, 256 pDisable parameter 275 pPlaySession parameters 256 PeekMessage() 116 ppName parameter 243, 244, 264, 268, 269, 290, 369 pEnable 273 ppPath 265 PendingOperations 253, 340, 361 ppPath parameter 245, 265, 396 PendingOperations method 242 ppText parameter 306, 308, 309, 311, 313 pEvenCount parameter 399 ppUnkRWClientWOSelection parameter 282 pEvent parameter 404, 407 pReadOnly parameter 279 pfCallback 96 pResourceError parameter 252, 333 pfCallBack member 159 pResourcesError 252 pfh parameter 144 pResourceType parameter 278, 333 pFileName parameter 411 PRWHANDLE data type 26 444 RemoteWare API Manual

prwpo parameter 135, 389 puiReadWriteCount parameter 146 pSeconds parameter 325 puiWriteCount parameter 47, 49 pSelected parameter 369 pUseDefaults parameter 366 pSerialNumber parameter 330 PUSHORT data type 26 pServerName parameter 329 pVal parameter 341, 342, 343, 344 pServerOriginated parameter 327 pVarEvent parameter 405 pslogBuf parameter 71 pvBuf parameter 104 pStartTime 287, 288 pvMsg parameter 135, 138, 139, 389, 392, 393 pStatus 252 pWorklist parameter 411 pStatus parameter 252, 332 pWorklistRec parameter 47, 48, 50, 146 pStatusMask parameter 248 pStsInfo parameter 127 Q PSZ data type 26 QUERYINFO1 structure 104 pszCaller parameter 77, 84, 89, 90, 92, 94 QUERYINFO2 structure 104 pszClient parameter 53, 389 pszClientName parameter 65, 67 R pszClientOrGrp parameter 102 pszClientorGrp parameter 102 ReadFile 395, 401 pszCmntData parameter 65 ReadOnly 267, 279 pszFilterAppGrp member 160 REBOOT Client at end of session 201 pszFilterUser field 160 RebootIfNecessary parameter 261, 362 pszFilterUser member 160 RefreshAlerts 243, 263, 340, 363 pszKey parameter 77, 84, 87, 89, 91, 92, 94 RefreshLog 322, 336 pszMember parameter 92, 94 ReleasePort 259, 340, 360 pszNewName parameter 90 ReleasePort method 243 pszObjectGroup parameter 92, 94, 100 RemoteWare CD-ROM xvi pszObjectName parameter 84, 85, 86, 155 RemoteWare Communications Node pszOldName parameter 90 background task 117 pszParam1 parameter 142 Node disk full alarm 31 pszParam2 parameter 142 node disk invalid 74 pszPipeName parameter 135, 389 RemoteWare Server pszQueue parameter 52 alarms pszSession parameter 102 Server rebooted 74 pszStartTime parameter 102, 104, 107 REMOVE DIRectory 201 pszText parameter 127, 128 RemoveEntry 315, 319 pszWorklistFile parameter 142, 144 RENAME file(s) 202 pTotalBytes parameter 295, 300 REPEAT IF 216 pTotalMessages parameter 295, 300 REPeat IF previous event FALSE 221 pTransferred parameter 299, 304 REPeat IF previous event TRUE 219 pType 252 Reserved field 45 pType parameter 252 Resource 322, 333 puiAppendCount parameter 50 resource parameter 308, 311, 313 puiCount parameter 146 ResourceError 313 puiDeleteCount parameter 49 ResourceError method 305 Index 445

ResourceError parameter 308, 311, 313, 414 RWCPipeWrite() 387, 393 ResourceName 311 RWHANDLE data type 26 ResourceName method 305 RWNAddWorklistRecord() function 141, 142, 176 Resources 74 RWNAPI.H 110 ResourceStatus 252 rwnapi.h 144, 152, 155 ResourceStatus methods 242 RWNAPI.H and ResourceStatusExplanation 313 16-bit Client APIs 110, 113 ResourceStatusExplanation method 305 DOS Client APIs 164 ResourceType 267, 278 OS/2 Client APIs 110, 113 ResourceType parameter 317 RWCPipeClose() 391 Return codes 24 RWCPipeRead() 392 Return values RWCPipeWrite() 393 0 (zero) 124, 126 RWNodeGetInfo() 117, 169 E_PIPE_OK 136, 137, 139 RWNodeQueryStatusText() 127 E_RWS_EOF 124, 126 RWNodeReadData() 123 E_RWS_PARAM 124, 126 RWNodeRequest() 166 FALSE 174 RWNodeWriteData() 125 False 122 RWNPipeClose 137 RWNPipeClose() 137 RWNPipeOpen() 135 RWNPipeOpen() 136 RWNPipeRead() 138 RWNPipeRead() 139 RWNPipeWrite() 139 TRUE 122, 174 rwnapi.h header file 142, 145, 153, 154, 159 zero (0) 124, 126 RWNOAPI.LIB 111 return values 309 RWNObjectQueryInfo() function 154, 155 retval parameter 375, 376, 378, 379 RWNObjectQueryObjects() function 154, 159 RP_LATESTREC value 59, 62, 71 RWNOBJQUERY structure 159 RP_NEXTREC value 59, 62, 65, 67, 71 RWNodeDialDirConnect() function 153 RP_USENAME value 65, 67 RWNodeDialDirDialog() function 153, 154 RSCStatus parameter 414 RWNodeGetInfo() 112, 117, 122, 165, 169, 174 RT_CLIENTCMT value 57 example 122 RT_CLIENTINFO value 57 RWNodeQueryStatusText() 112, 127 RT_FILELOG value 57 RWNodeReadData() 112, 123 RT_MSGLOG value 57 RWNodeRequest() 112, 113, 165, 166 RT_SESSLOG value 57 RWNodeWriteData() 112, 126 RWCAPI.H 389 RWNOF_ALLOBJECTS value 160 RWClient Object 240 RWNOF_APPINFO value 160 RWClientDialingEntry Object 241 RWNOF_DESKTOP value 160 RWClientDialingEntryCollection Object 241 RWNOF_EXPANDAPPGRPS value 160 RWClientInfo Object 240 RWNOF_NODEOBJECTS value 160 RWClientSessionStatus API 284–304, ??–304 RWNOPEN parameter 136 RWClientWOSelection Object 241 RWNPipeClose() 133, 137 RWCPipeClose() 387, 391 RWNPipeOpen() 133, 135, 138 RWCPipeOpen() 387, 389, 391, 392, 393 RWNPipeRead() 133, 138 RWCPipeRead() 387, 392 RWNPipeWrite() 133, 139 446 RemoteWare API Manual

RWNPOPEN parameter 135 RWSObjectDelete() function 76, 84 RWNSTSINFO parameter 128 RWSObjectLock() function 76, 85 RWNWAPI.LIB 164 RWSObjectQueryMembers() function 76, 99 RWNWAPI.LIB and RWSObjectQueryObjects() function 76, 95, 99, 100 16-bit Client APIs 110 RWSObjectRead() function 76, 87 RWNWorklistAction() function 141, 144, 145, 155, RWSObjectRename() function 76, 90 220, 221 RWSObjectUnassign() function 76, 94 RWNWorklistClose() function 141, 152 RWSObjectUnlock() function 76, 86 RWNWorklistOpen() function 141, 144, 145 RWSObjectWrite() function 76, 88 RWNWorkObjectSelect() function 161 RWSQuerySysInfo() function 104, 107 RWPN_BROKEN notification type 133, 387 RWSReadClientComments() function 56, 64 RWPN_CALLING notification type 133, 387 RWSReadClientInfo() function 56, 67 RWPN_CONNECTED notification type 133, 387 RWSReadClose() function 56, 57 RWPN_CONNECTING notification type 387 RWSReadFileLog() function 56, 58 RWPN_DISCONNECTED notification type 133, RWSReadMsgLog() function 56, 62 387 RWSReadSessLog() function 56, 71 RWPN_LOADING notification type 133, 387 RWSReadWorklistRecord() function 28, 36, 39 RWPN_MESSAGE notification type 133, 387 RWSResetSecurity() function 107 RWPN_REINITIALIZING notification type 133, RWSRUNTM.LIB 29 387 RWSScheduleSession 101 RWPN_UNLOADING notification type 133 RWSScheduleSession() function 24, 25, 101 RWPN_UNLOADING notification types 387 RWSSetUserAlarm() function 31, 34 RWS_ALL_ASSIGNED flag 102 RWSWorklistClose() function 28, 36, 37 RWS_ALL_ASSIGNED value 101, 102 RWSWorklistOpen() function 28, 36, 37, 38, 39, 47, RWS_ALL_CLIENTS value 101, 102 48, 49, 152 RWS_NOW value 102 RWSWorklistSave() function 28, 36, 38 RWS_QUERYLEVEL1 value 104 RWSWriteWorklistRecord() function 28, 36, 47 RWS_QUERYLEVEL2 value 104 rwwdsext.dll file 432 RWSAddWorklistRecord() function 28 RWWORKLIST structure 146 rwsapi.dll file 35, 104 RWWORKLIST type 39, 47, 50 rwsapi.h 28 RWSAppendWorklistRecord() function 28, 36, 49 S RWSClearAlarm() function 31 S_OK result 238 RWSDeleteWorklistRecord() function 28, 36, 48 SaveWorkObjectSelection 364, 373 RWSGetAlarmText() function 31 schedule function RWSGetNumberOfRecords() function 28, 36, 38 RWSScheduleSession 94 RWSIsAlarmSet() function 31, 32, 34 schedule_time member 124, 126 RWSNotifyClose() function 51, 52 Scheduled inbound session time, determining 123 RWSNotifyCreate() function 51 Scheduler disabled alarm 31 RWSNotifyPending() function 51, 54 Scheduler queues full alarm 31 RWSNotifyWait() function 24, 25, 51, 53, 54, 176, sCommand parameter 41, 142, 147 230 Select parameter 371 RWSObjectAssign() function 76, 92 SelectWorkObject 364, 371 RWSObjectCreate() function 76, 77 SEND DIRectory files to Client 185 Index 447

SEND file to Client 183 REMOVE DIRectory 201 Sentinel security failure alarm 32 RENAME file(s) 202 Serial number 74, 155, 159 REPEAT IF 216 Server Database function summary 56 REPeat IF previous event FALSE 221 Server disk full alarm 31 REPeat IF previous event TRUE 219 Server events 229 SEND DIRectory file to Client 185 Server InformationAPI 104, 107 SEND file to Client 183 Server low memory alarm 31 SET Client TIME 203 Server modem error alarm 31 SET VARriables 226 Server Node 157, 158 TEST if node is in GROUP 225 Server Object APIs 76 TEST VARiable 228 Server phone number, changing 125 USER defined ALARM 231 Server rebooted alarm 31 WAIT for file to exist 204 Server Schedule API 101 Session History Log 56, 71, 232 Server Schedule API function 101 Session Log 73 Server Worklist API function summary 35 session parameter 308, 311 Server worklist APIs 35 Session, scheduling 101 ServerName 290, 322, 329 SessionEndTime 339, 349 CommandExecuting 284 SessionError 310 ServerOriginated 322, 327 SessionError method 305 ServerSerialNumber 284, 289, 322, 330 SessionResult 308 Session Editor commands SessionResult method 305 APPEND file(s) to another 190, 191, 205, 206, 207, SessionStartTime 338, 342 208, 209, 210, 214, 215, 222, 223, 224, 233, 234 SessionStatus 284, 286 CHECK DISK drive 192 SESSLOGREC structure 71, 72 CHECK FILE ServerFile ClientFile 193 SET Client TIME 203 COMMENT 213 SET VARriables 226 COPY file(s) 195 SetAsDefaultEntry 267, 281 DELETE file(s) 196 SetEvent 395, 404 DIRectory listing 197 SetPriorityClass function 56 ELSE IF 213 SetThreadPriority function 56 END IF 214 SHORT data type 26 END SESSION 217 Signed character data type 26 EXCEPTION worklist 229 SL_BAD_DRIVE value 74 EXECUTE program 198 SL_BUSY value 73 GET DIRectory files from Client 182, 186 SL_CLIENT_PASSWORD value 74 GET file from Client 180 SL_CRITICAL value 73 get FILE STATUS 199 SL_ESD_FAIL value 74 IF previous event FALSE 219 SL_FAILED value 73 IF previous event TRUE 218 SL_FINAL value 73 insert WORKLIST 232 SL_LOSTLINK value 73 MAKE DIRectory 200 SL_MODEMERROR value 73 NOTIFY WinNT server 230 SL_NOANSWER value 73 REBOOT Client at end of session 201 SL_NOCONNECT value 73 448 RemoteWare API Manual

SL_NODIALTONE value 73 about 21 SL_NORESOURCES value 74 error handling 24 SL_OUT_OF_RANGE value 74 TEXTCOMM program 123 SL_RECOVER value 73 TOTAL_ALARMS constant 32 SL_SECURITY value 74 TotalEntries 322, 323 SL_SERIAL_NUMBER value 74 Transaction Pipe API functions 132, 386, 386–393 SL_TIMEOUT value 73 Transaction Pipe function error codes 133, 387 SL_UNDEFINED value 73 Transaction Pipe notification types 133, 387 SL_UNSCHEDULED value 74 troubleshooting SL_USER_ABORT value 74 16-bit Client API 110 SL_WRONG_CLIENT value 74 OS/2 32-bit Client APIs 111 SNODEAPI.LIB 164 TRUE return value 174 SQI_LONGSESSIONSTATUS value 127, 129, 130, True return value 122 131 SQI_NODESTATUS value 127, 128 U SQI_RESOURCENAME value 127, 130 uiBufSize parameter 104 SQI_RESOURCESTATUS value 127 ULONG data type 26 SQI_SESSERREXPLANATION value 127, 129, ulOptions member 150 130, 131 ulOptions parameter 44, 45, 143 SQI_SESSIONSTATUS value 127, 129, 130, 131 ulSerialNumber parameter 155, 159 StartTime 284, 287, 288 ulTimeout parameter 138, 392 StartTime member 121, 173 UNIX client 157, 158 Status 322, 332 UNIXWare Client 157, 158 status member 118, 170 Unload 257, 339, 359 status parameter 311, 313 Unload method 242 StatusChange 413, 414 unsigned data type 26 StatusExplanation 306 unsigned integer data type 26 StatusExplanation method 305 unsigned short data type 26 statusmask parameter 306 UseDefaults 364, 368 structures, defined 418 User alarm 31 Support Response alarm 31 setting 42 Supported computers 18 USER defined ALARM 231 Suspended Server alarm 32 User-defined alarm 31 System Fatal Error alarm 31 USHORT data type 26 szName field 87 usRecSize field 87 szParam1 parameter 45 szParam2 parameter 45 V szUserData member 160 VarEvent parameter 405 T varEvent parameter 409 VAX client 157, 158 Test bed 21 vbGetEvent 395, 405 TEST if node is in GROUP 225 vbInsertEvent 395, 409 TEST VARiable 228 vbSetEvent 395, 405 testing with APIs Index 449

VeboseStatusText 343 event 212 VerboseStatusText 338 value 149 Version 247 WL_COMPARE_EQUAL 45 Version method 242 WL_COMPARE_GREATER 45 void data type 26 WL_COMPARE_GREATEREQ 45 WL_COMPARE_LESS 45 W WL_COMPARE_LESSEG 45 WL_COMPARE_NOT EQ 45 WAIT for file to exist 204 WL_CONDITIONAL_FALSE value 45, 150, 181, Web site xvi 183, 185, 186, 190, 191, 192, 194, 195, 196, 197, Wild card 180, 182, 185, 190, 191, 195, 196, 197, 202 198, 199, 200, 201, 202, 203, 204, 217, 218, 227, Win32 Client API structure 240–241 228, 230, 231, 232 Win32 Client APIs 235–422 WL_CONDITIONAL_TRUE value 45, 150, 181, WIN32 error code 52, 53, 54, 57, 61, 64, 66, 70, 74, 183, 185, 186, 190, 191, 192, 194, 195, 196, 197, 83, 84, 86, 88, 89, 91, 93, 94, 98, 100, 103, 105 198, 199, 200, 201, 202, 203, 204, 217, 218, 227, WIN32 named queue 229, 230 228, 230, 231, 232 Windows 16-bit APIs WL_COPYFILE compiling and linking 110 event 189 error codes 112 value 41, 148 Windows client 157, 158 WL_CRITICAL value 44, 45, 150, 181, 183, 184, WINDOWS.H 28, 110 186, 190, 191, 192, 194, 195, 196, 197, 199, 200, WINXNODE program 113 202, 203, 204, 205, 206, 207, 208, 209, 211, 215, WL_AFTER value 44, 143 222, 223, 225, 226, 227, 228, 230, 231, 232, 233, WL_APPENDFILE 234 command 41 WL_CRITICAL_RETRY value 45, 150, 181, 183, event 189 184, 186, 190, 192, 194, 195, 196, 197, 199, 200, value 148 202, 203, 204, 227, 228, 230, 231, 232 WL_ASCII_APPEND WL_DELETE_AFTER value 44, 150, 181, 183, 184, command 42 186, 191, 194, 204 event 189 WL_DELETEFILE value 148 event 189 WL_BEFORE value 41, 147 value 44 WL_DIRECTORY WL_BEFORE value 143 command 41 WL_CHECK_FILE event 189 command 43 value 148 value 149 WL_DURING value 44, 143, 180, 182, 184, 185, WL_CHECKDISK 193, 201, 203 command 41 WL_ELSE_IF event 189 command 42 value 148 value 149 WL_CHECKFILE WL_ELSE_IF event 212 event 189 WL_END_IF WL_COMMENT command 43 command 43 450 RemoteWare API Manual

event 212 command 42 value 149 event 189 WL_END_REPEAT value 148 command 43 WL_NO_COMPRESS value 44, 150, 181, 183, 184, event 212 186, 187, 194 value 149 WL_NO_OVERWRITE value 44, 150, 181, 182, WL_END_SESSION 184, 185, 187, 190, 191, 192, 194, 195, 196, 197, command 42, 148 199, 200, 202, 203, 204, 205, 206, 207, 208, 209, event 212 211, 215, 222, 223, 225, 226, 227, 228, 230, 231, value 149 232, 233, 234 WL_EXCEPTION WL_NOT_NEEDED value 45, 150, 181, 183, 184, command 41 185, 186, 190, 191, 192, 194, 195, 196, 197, 198, event 229 199, 200, 201, 202, 203, 204, 227, 228, 230, 231, value 43, 149 232 WL_EXECUTE WL_NOTIFY command 41 command 42 event 189 event 176, 229 value 42, 148 events 230 WL_FILESTAT value 148 command 41 WL_ON_CLIENT value 43 event 189 WL_ON_NODE value 143, 180, 182, 184, 185, 190, value 148 191, 192, 193, 195, 196, 197, 198, 199, 200, 201, WL_GETDIR 202, 203, 204, 227, 228, 229, 230, 231, 232 command 41 WL_ON_SERVER value 43, 143, 180, 182, 184, 185, event 180 190, 191, 192, 193, 195, 196, 197, 198, 199, 200, WL_GETFILE 201, 202, 203, 204, 225, 227, 228, 229, 230, 231, command 41 232 event 180 WL_PREVIOUS_FALSE 45 value 147 WL_PREVIOUS_TRUE 45 WL_GROUP_TEST WL_REBOOT_NODE command 43 command 42 event 212 event 189 value 149 value 148 WL_IF_FALSE WL_REMOVEDIR command 42 command 42 event 212 event 189 value 149 value 148 WL_IF_TRUE WL_RENAMEFILE command 43 event 189 event 212 value 42, 147 value 42, 149 WL_REPEAT_IF_FALSE WL_INCREMENTAL_UPDATE command 43 value 150 event 212 WL_MAKEDIR 200 value 149 Index 451

WL_REPEAT_IF_TRUE WLA_DELETE value 146 command 42 WLA_READ value 146 event 212 WLA_WRITE value 146 value 149 wNodeStatus member 128, 129 WL_SAFE_SEND value 44, 150, 181, 184, 185, 187, WOCT_4690_CLIENT value 82 194 WOCT_AIX_CLIENT value 82 WL_SEND_NEWER value 45, 181, 184, 185 WOCT_ATT_CLIENT value 82 WL_SENDDIR WOCT_DOS_CLIENT value 82 command 41 WOCT_MAC_CLIENT value 82 event 180 WOCT_NB_DOS_CLIENT value 82 WL_SENDDIR command 41 WOCT_SERVER_CLIENT value 82 WL_SENDFILE WOCT_VAX_CLIENT value 82 command 41 WOCT_WIN32_CLIENT value 82 event 180 WOCT_WINDOWS_CLIENT value 82 value 147 WOCT_XENIX_CLIENT value 82 WL_SENDFILE command 41 WOEX_DEFAULT value 156 WL_SET_VARIABLE WOEX_FORCED value 81, 156 command 43 WOEX_REQUESTABLE value 81, 156 event 212 WOF_AUTO_CLIENTASN value 81 value 149 WOF_NO_MEMBER_RENDEL WL_SETTIME flag 84, 91 command 42 value 81 event 189 WOF_NO_USERASN value 81 value 148 WOF_ONEONLY value 81 WL_TEST_VARIABLE WOF_READONLY_ASN value 80, 156 command 43 WOF_READONLY_EVENTS value 81, 156 event 212 WOF_READONLY_MEMBERS value 80, 156 value 149 WOFLT_APPLICATION value 97 WL_UPDATEFILE value 44, 150, 181, 182, 184, WOFLT_APPLICATION_GROUP value 97 185, 187 WOFLT_ESD value 97 WL_USER_ALARM WOFLT_GROUP value 97 command 42 WOFLT_MEMBER value 97 event 229 WOFLT_OWNER value 97 value 148 WOFLT_TYPE value 97 WL_WAIT WOFLT_WORKLIST value 97 command 42 WOLM_NONE value 81 event 189 WONT_4680_NODE value 157, 158 value 148 WONT_AIX_NODE value 157, 158 WL_WORKLIST WONT_ANY value 157 command 42 WONT_ATT_NODE value 157, 158 event 229 WONT_DOS_NODE value 157 value 148 WONT_MAC_NODE value 157, 158 WL_WORKQUEUE 148 WONT_NB_DOS_NODE value 157, 158 WLA_APPEND value 146 WONT_OS2_NODE value 157 452 RemoteWare API Manual

WONT_SERVER_NODE value 157, 158 WAIT for file to exist 204 WONT_UNIX_NODE value 157, 158 Worklist events WONT_VAX_NODE value 157, 158 File Transfer WONT_WINDOWS_NODE value 157, 158 summary 180 WONT_XENIX_NODE value 157, 158 WL_GETDIR 182, 186 WORD data type 26 WL_GETFILE 180 Work Object Editor 35 File transfer 180 work objects 76, 155 WL_SENDDIR 185 Worklist APIs 141, 176 WL_SENDFILE 183 Worklist event Operating system 189 Session Editor commands summary 189 APPEND file(s) to another 190, 191, 205, 206, W_FILESTAT 199 207, 208, 209, 210, 214, 215, 222, 223, 224, 233, WL_APPENDFILE 189, 190, 205, 206, 207, 234 208, 209, 210, 214, 215, 222, 223, 224, 233, 234 CHECK DISK drive 192 WL_ASCII_APPEND 189, 191 CHECK FILE ServerFile ClientFile 193 WL_CHECKDISK 189, 192 COMMENT 213 WL_CHECKFILE 189, 193 COPY file(s) 195 WL_COPYFILE 189, 195 DELETE file(s) 196 WL_DELETEFILE 189, 196 DIRectory listing 197 WL_DIRECTORY 189, 197 ELSE IF 213 WL_EXECUTE 189, 198 END IF 214 WL_FILESTAT 189, 199 END SESSION 217 WL_MAKEDIR 189, 200 EXCEPTION worklist 229 WL_REBOOT_NODE 201 EXECUTE program 198 WL_REMOTE_NODE 189 GET DIRectory files from Client 182, 186 WL_REMOVEDIR 201 get FILE STATUS 199 WL_REMOVEIR 189 IF previous event FALSE 219 WL_RENAMEFILE 189, 202 IF previous event TRUE 218 WL_SETTIME 189, 203 insert WORKLIST 232 WL_WAIT 189, 204 MAKE DIRectory 200 Server Events 229 NOTIFY WinNT server 230 WL_EXCEPTION 229 REBOOT Client at end of session 201 WL_NOTIFY 230 REMOVE DIRectory 201 WL_USER_ALARM 231 RENAME file(s) 202 WL_WORKLIST 232 REPEAT IF 216 Session Control 212 REPeat IF previous event FALSE 221 WL_ELSE_IF 213 REPeat IF previous event TRUE 219 WL_END_IF 214 SEND file to Client 183 WL_END_REPEAT 216, 218 SET Client TIME 203 WL_END_SESSION 217 SET VARriables 226 WL_GROUP_TEST 225 TEST if node is in GROUP 225 WL_IF_TRUE 219 TEST VARiable 228 WL_REPEAT_IF_FALSE 221 USER defined ALARM 231 WL_REPEAT_IF_TRUE 219 Index 453

WL_SET_VARIABLE 226 XNODE_INFO_SIZE 169 WL_TEST_VARIABLE 228 XR_CANCEL request 113 session control XR_CANCEL value 114, 167 WL_COMMENT 213 XR_CONNECT1 value 114, 167 Session Control events 212 XR_CONNECT2 value 114, 167 Session Editor commands XR_DISABLE_AA value 114, 167 GET file from Client 180 XR_DISABLE_ESD value 115, 167 SEND DIRectory files to Client 185 XR_ENABLE_AA value 114, 167 worklists XR_ENABLE_ESD value 115, 167 communicating with 176 XR_REINIT value 114, 166, 167 default files and paths 179 XR_RELEASE_PORT value 114, 167 directory 179 XR_REMOVE value 114, 166 using 176 XR_STATUS value 114, 166 WorkObject 364, 369 XRSC_ASYNC value 120, 130, 172 WorkObjectCount 364, 365 XRSC_NETBIOS value 120, 130, 172 WorkObjectSelection 267, 282 XRSC_NONE value 120, 130, 173 WOTY_APPLICATION value 81, 98, 156 XRSC_SPX value 120, 130, 173 WOTY_APPLICATION_GROUP value 81, 98, 156 XRSC_TCPIP value 120, 130, 173 WOTY_ESD value 81, 97, 156 XRSC_X25 value 120, 130, 172 WOTY_GROUP value 81, 97, 156 XS_AUTO_ANSWER 115 WOTY_MEMBER_DIRECT value 98 XS_AUTO_ANSWER flag 167 WOTY_MEMBER_INDIRECT value 98 XS_AUTO_ANSWER value 128 WOTY_WORKLIST value 81, 97, 156 XS_CONNECTED 115 wRequest parameter 114, 115, 166, 167 XS_CONNECTED flag 120, 121, 167, 172, 173 WriteFile 395, 402 XS_CONNECTED value 128 XS_CONNECTING 115 X XS_CONNECTING flag 167 XS_CONNECTING value 128 X_RSC_OK value 121, 173 XS_COUNTER_MASK 115, 116 XC_NONE value 120, 172 XS_COUNTER_MASK constant 168 XC_RCVFILE value 120, 172 XS_DIALING 115 XC_SENDFILE value 120, 172 XS_DIALING flag 167 XC_SWO value 120, 172 XS_DIALING value 128 XcelleNet web site xvi XS_DISCONNECTED 115 XE_RSC_DLL_NOT_FOUND value 122, 132, 174 XS_DISCONNECTED flag 118, 167, 171 XE_RSC_INTERNAL value 121, 131, 174 XS_DISCONNECTED value 129 XE_RSC_INVALID_DLL value 122, 132, 174 XS_ESD_DISABLED 115 XE_RSC_NO_MEMORY value 122, 132, 174 XS_ESD_DISABLED flag 168 XE_RSC_NOT_AVAILABLE value 122, 131, 174 XS_ESD_DISABLED value 129 XENIX client 157, 158 XS_LOADED flag 167 XNODE_DATA parameter 123, 125 XS_LOADED return value 115 XNODE_DATA_SIZE constant 125 XS_LOADED value 128 XNODE_DATA_SIZE parameter 123 XS_PASSWORD 115 XNODE_INFO 169 XS_PASSWORD flag 167 XNODE_INFO parameter 117, 169, 170 454 RemoteWare API Manual

XS_PASSWORD value 128 XS_PORT_RELEASED 115 XS_PORT_RELEASED flag 168 XS_PORT_RELEASED value 129 XS_RESOURCE_READY 115 XS_RESOURCE_READY flag 168 XS_RESOURCE_READY value 129 XS_RSC_ERROR value 121, 131, 173 XS_RSC_LOAD_FAILED constant 174 XS_RSC_LOAD_FAILED value 121, 131, 173 XS_RSC_LOADING value 121, 131, 173 XS_RSC_OK value 131 XS_RSC_OPEN_FAILED value 121, 131, 173 XS_RSC_REINITING value 121, 131, 173 XS_RSC_RELEASING value 121, 131, 173 XS_RSC_UNLOADING value 121, 131, 173 XS_SESS_ABORTED value 119, 129, 171 XS_SESS_CANCELED value 119, 129, 171 XS_SESS_LOST_CONNECTION value 119, 129, 171 XS_SESS_NO_ANSWER value 119, 129, 171 XS_SESS_NODE_DISABLED value 119, 130, 171 XS_SESS_NODE_UNDEFINED value 119, 130, 172 XS_SESS_NODEREG_DISABLED value 119, 130, 172 XS_SESS_NONE value 118, 129, 171 XS_SESS_PASSWORD_FAIL value 119, 129, 171 XS_SESS_RESOURCE_ERROR value 119, 129, 171 XS_SESS_SCHEDULER_OFF value 119, 130, 171 XS_SESS_SERVER_DOWN value 119, 130, 171 XS_SESS_SERVER_SUSPENDED value 119, 130, 171 XS_SESS_SUCCESSFUL value 118, 129, 171 XS_SESS_TIMEOUT value 119, 129, 171 XWorkList Object 240

Z

Zero (0) return value 124, 126