DocuShare

Windows Client SDK

Publication date: August 2006

This document supports the following: DocuShare Release 5/DocuShare CPX Release 5

Prepared by:

Xerox Corporation
DocuShare Business Unit
3400 Hillview Avenue
Palo Alto, California 94304
USA

Copyright © 2006 Xerox Corporation. All Rights Reserved. Xerox ® and DocuShare® are trademarks of
Xerox Corporation. All other trademarks are the property of their respective companies and are hereby
acknowledged.
Table of Contents
Chapter 1 DocuShare Windows Client SDK
1.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1–2
1.1.1 DSServerMap Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1–2
1.1.2 DSItem EnumLib Item Object and Item Enumerator Library . . . . . . . . . . . . . . . . . . . 1–2
1.1.3 DSGateway Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1–3
1.1.4 Properties and Permissions Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1–3
1.1.5 DSAxess Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1–3

Chapter 2 SDK Programming

2.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–2
2.2 Programming Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–3
2.2.1 IItemObj and Supported Item Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–5
2.3 DocuShare Client Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–13
2.3.1 Common Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–13
2.3.2 Basic Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–13
2.3.3 Advanced Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–13
2.4 Opening a DocuShare session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–14
2.5 Creating a new DocuShare item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–16
2.5.1 Updating a DocuShare item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–16
2.5.1.1 Updating certain properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–17
2.6 Updating a DocuShare file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–19
2.6.1 Moving, copying and deleting an item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–21
2.7 Creating a new user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–24
2.8 Running a selection dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–25
2.9 Managing multiple DocuShare objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–29
2.10 Log into a DocuShare server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–31
2.10.1 Login Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–31
2.10.1.1Simple server login . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–31
2.10.1.2A set address login . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–32
2.10.1.3Set username and server address . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–32
2.10.1.4Automatic login . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–33
2.10.1.5Select and log into server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–34
2.11 Navigating a DocuShare server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–36
2.11.1 Server Root Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–37

DocuShare Windows Client SDK iii

 Table of Contents

2.11.2 Listing a Child Collection from a Parent Collection . . . . . . . . . . . . . . . . . . . . . . . . . 2–38

2.11.3 Listing File Versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–40
2.11.4 Selecting a Collection from Server List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–41
2.11.5 Selecting a File from Server List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–42
2.11.6 Get a Collection by HandleNum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–44
2.11.7 Get a File by HandleNum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–45
2.12 Working with properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–46
2.12.1 IItemObj methods and properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–46
2.12.1.1Icons and thumbnails . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–49
2.12.2 IItemObj and custom properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–53
2.12.3 IEnumObj methods and properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–55
2.13 Uploading documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–57
2.13.1 A Simple Upload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–57
2.13.2 A Version Upload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–58
2.13.3 A Directory Upload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–59
2.13.4 A Directory Upload to a Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–60
2.13.5 A Wildcard Upload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–61
2.13.6 A Wildcard Upload to Target Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–62
2.14 Performing basic searches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–64
2.15 Managing server connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–71
2.15.1 Creating a server map database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–71
2.15.2 Enumerating server maps stored in the database . . . . . . . . . . . . . . . . . . . . . . . . . . 2–73
2.16 Accessing the DocuShare objects using C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–75
2.16.1 Using the stubs from the Include directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–75
2.16.2 Generating Your Own Includes and Stubs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–76
2.17 Event handling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–77
2.17.1 Event handling in Visual Basic application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–77
2.17.2 Event Handling in C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–78
2.17.3 Implementing the DIID_DDsAxessEvents Interface . . . . . . . . . . . . . . . . . . . . . . . . 2–78

Chapter 3 DSGateway Library

3.1 Object model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–2
3.2 Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–4
3.2.1 GatewayHandler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–4
3.2.1.1 GatewayHandler methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–6
AwaitCompletion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–6
Cancel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–7

iv DocuShare Windows Client SDK

Table of Contents

ClearCollectionCache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–8
DoLoginDialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–9
Download . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–10
GetAuthToken . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–12
GetItemProplds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–14
GetLastError . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–15
GetMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–19
GetProps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–20
GetStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–21
GetTransferInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–22
GoOffline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–23
GoOnline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–24
InitiateBulkDownload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–26
InitiateBulkReplicate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–29
InitiateBulkUpload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–31
InitiateCollectionCreate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–33
InitiateCollectionOpen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–34
InitiateContainerOpen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–38
InitiateCopy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–41
InitiateCreateObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–42
InitiateDelete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–43
InitiateDisown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–44
InitiateDownload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–45
InitiateGet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–47
InitiateHistory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–48
InitiateLock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–50
InitiateMove . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–51
InitiatePost . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–52
InitiateRename . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–56
InitiateSchema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–58
InitiateUserAuth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–60
OpenContainer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–62
OpenCollection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–63
RegisterClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–65
Search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–67
SetItemProplds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–68
SetMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–71
SetProps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–77
SetShellNotification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–78
Submit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–79
Upload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–80
Wait . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–82

DocuShare Windows Client SDK v

 Table of Contents

3.2.1.2 GatewayHandler Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–83

DSCollHandle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–83
DSContainerHandle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–84
DSContent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–85
DSCreatedTimeFrom . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–85
DSCreatedTimeTo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–85
DSDisplayName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–86
DSFileHandle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–86
DSFileName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–86
DSFileType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–86
DSHandle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–87
DSHandleList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–89
DSItemListFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–90
DSItemProp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–92
DSKeywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–92
DSMaxItems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–92
DSModifiedTimeFrom . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–93
DSModifiedTimeTo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–93
DSObjectHandle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–94
DSObjectTypeNum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–96
DSOwner . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–96
DSTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–97
DSVersion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–97
LocalTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–98
PropAttrlds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–98
Proplds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–99
GatewayClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–100
GatewaySettings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–101
DSAccessData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–102
ClientRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–103
ServerResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–105
3.2.2 GatewayClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–109
3.2.2.1 GateClient Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–109
3.2.2.2 GatewayClient Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–109
CancelCode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–109
CancelWindow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–110
ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–110
IPAddress . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–111
Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–111
Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–112
WindowHandle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–112

vi DocuShare Windows Client SDK

Table of Contents

3.2.3 GatewaySettings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–113

3.2.3.1 GatewaySettings methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–113
3.2.3.2 GatewaySettings properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–114
AddDSCGI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–114
Asynchronous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–114
AutoSetWWWAuth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–115
CacheExpireMinutes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–115
CanKeepAlive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–116
CompressRequestData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–116
CompressResponseData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–117
CopyAllVersions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–117
DefNewFileMaxVersions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–118
EnableCache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–118
ErrorDisplayStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–119
ErrorReportObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–119
File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–119
FileFilter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–120
HttpRequestTimeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–121
IgnoreFileTypeOnCompress . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–122
IgnoreMIMEType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–123
ItemDescriptorArrayFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–123
ItemDescriptorArrayStorage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–124
LanguageTag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–124
LoadablePropIds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–125
LoadablePropIdsCore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–125
LoadablePropsStore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–125
LoadDefaultProps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–126
NameConflictResolver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–127
NoErrorDialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–127
NoServerStatusQuery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–127
PromptOnDownloadNameClash . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–128
PromptOnUploadNameClash . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–128
PropertyAttributeIDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–129
QueriedProperties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–130
QueriedPropertyIDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–131
ReceptionTimeOut . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–132
RenameFirstReplicate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–132
Silent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–133
StatusObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–133
StorageMedium . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–133
TransmissionBufferSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–134
TransmissionPause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–134

DocuShare Windows Client SDK vii

 Table of Contents

TransmissionTimeOut . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–135
UploadAlwaysAsNewDoc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–135
3.2.4 DSAccessData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–136
3.2.4.1 DSAccessData methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–136
3.2.4.2 DSAccessData properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–136
AuthToken . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–136
BrokerMap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–137
CapabilityFlags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–137
DocuShareAddress . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–138
Domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–138
DSVersionNumber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–138
GatewaySettings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–138
HostName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–139
IPAddress . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–139
IsUserLoggedIn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–139
Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–140
Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–140
Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–140
ProxyAddress . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–140
ServerMap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–141
SupportDS1x . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–141
UseProxy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–142
UserHandle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–142
UserName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–143
VirtualRoot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–143
3.2.5 ClientRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–144
3.2.5.1 ClientRequest methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–144
Clear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–144
3.2.5.2 ClientRequest properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–144
Action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–144
ActionId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–145
Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–145
ContentData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–146
ContentType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–147
Cookie . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–147
DispatchedTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–148
Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–148
HTTPVersionMajor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–149
HTTPVersionMinor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–149
MessageHeader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–150
Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–151

viii DocuShare Windows Client SDK

Table of Contents

Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–152
RequestURI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–152
URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–153
3.2.6 ServerResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–156
3.2.6.1 ServerResponse methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–156
Clear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–156
3.2.6.2 ServerResponse properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–157
ContentData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–157
ContentEncoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–157
ContentLength . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–157
ContentType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–158
Cookie . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–158
DSError . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–158
DSHandle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–158
DSUser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–159
DSVersion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–159
ErrorCode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–159
ErrorDescription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–160
HasTextualContent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–160
Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–160
HTTPResultCode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–161
MessageHeader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–161
ReceivedTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–162
RemoteTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–162
StatusCode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–163
StatusLine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–164
3.2.7 ContentData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–165
3.2.7.1 ContentData methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–165
Add . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–165
DeclareXML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–168
ParseDirectory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–169
ParseProperties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–171
ParsePropertiesAsDsxInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–173
ParseQueryResults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–175
ParseSchema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–176
ParseVersionHistory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–178
ParseUploadResult . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–180
Verify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–184
3.2.7.2 ContentData properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–187
CleanText . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–187
DataCompression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–187

DocuShare Windows Client SDK ix

 Table of Contents

Delta . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–188
File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–189
ParsedResultHandle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–189
ParsedResultType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–190
StorageMedium . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–191
Stream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–191
Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–192
XMLDOM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–192
ItemDescriptorArray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–193
ItemProperties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–194
3.2.8 PropertyIDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–195
3.2.8.1 PropertyIDs methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–195
Add . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–195
Clear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–195
Remove . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–196
3.2.8.2 PropertyIDs properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–197
Count . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–197
List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–197
PropertyID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–198
3.2.9 PropertyID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–199
3.2.9.1 PropertyID methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–199
3.2.9.2 PropertyID properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–199
ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–199
ItemType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–199
Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–200
3.2.10 ItemProperties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–201
3.2.10.1ItemProperties methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–201
Add . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–201
Clear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–201
CopyTo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–202
Remove . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–203
3.2.10.2ItemProperties properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–203
Count . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–203
ItemObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–203
ItemProperty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–203
3.2.11 ItemProperty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–204
3.2.11.1ItemProperty methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–204
3.2.11.2ItemProperty properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–204
DisplayName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–204

x DocuShare Windows Client SDK

Table of Contents

ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–204
Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–205
3.2.12 ItemDescriptorArray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–206
3.2.12.1ItemDescriptorArray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–206
3.2.12.2ItemDescriptorArray properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–206
Enumerator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–206
ErrorDescription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–206
File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–207
StorageMedium . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–207
3.2.13 SearchRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–208
3.2.13.1SearchRequest methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–209
3.2.13.2SearchRequest properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–209
MaxHits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–209
QueriedProperties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–209
Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–211
SearchTermsCollection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–212
3.2.14 SearchTermsCollection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–213
3.2.14.1SearchTermsCollection methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–213
Add . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–213
Remove . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–213
3.2.14.2SearchTermsCollection properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–214
Count . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–214
Conjunct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–214
Terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–214
XMLText . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–215
3.2.15 SearchTerms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–217
3.2.15.1SearchTerms methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–217
Add . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–217
Remove . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–218
3.2.15.2SearchTerms properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–218
Count . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–218
Conjunct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–218
ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–219
NestedTerms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–219
Term . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–219
XMLText . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–219
3.2.16 SearchTerm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–220
3.2.16.1SearchTerm methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–220

DocuShare Windows Client SDK xi

 Table of Contents

3.2.16.2SearchTerm properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–220

Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–220
Operator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–221
Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–221
XMLText . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–221
3.3 Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–222
3.3.1 Special handle values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–222
3.3.2 DSGateway DSX_OBJTYPE object types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–222
3.3.3 DSX_CMDID Command IDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–223
3.3.4 DSX_STGMEDIUM Storage medium types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–224
3.3.5 DSX_DATCOMPR Data compression flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–224
3.4 Submit method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–225
3.4.1 Submit code examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–225
3.5 Non-file object creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–234
3.6 Compound document support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–237
3.6.1 Advantages of a compound document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–237
3.6.2 Effect on a Windows file uploaded to DocuShare . . . . . . . . . . . . . . . . . . . . . . . . . 3–237
3.6.3 Uploading a compound document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–238
3.6.3.1 Storing content elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–238
3.6.4 Downloading a compound document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–241
3.6.5 File Management Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–242

Chapter 4 DSServerMap Library

4.1 Object model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–2
4.2 Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–3
4.2.1 Store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–3
4.2.1.1 Store methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–4
Add . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–4
CanAdd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–5
Clone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–6
Close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–6
DoSelectDialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–7
Find . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–9
Load . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–10
Protect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–12
Remove . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–13
Reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–14
Save . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–15
Unprotect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–17

xii DocuShare Windows Client SDK

Table of Contents

4.2.1.2 Store properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–18

BaseRegistryKey . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–18
ISProtected . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–19
NextItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–19
NextPos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–20
Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–21
SelectDialogOption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–22
4.2.2 Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–24
4.2.2.1 Browser methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–24
Init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–24
NavigateTo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–25
View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–27
ViewProps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–29
4.2.2.2 Browser properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–30
Cookie . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–30
DocuShareAddress . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–30
Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–31
OwnerHwnd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–31
ProxyAddress . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–31
4.2.3 Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–32
4.2.3.1 Wizard methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–32
Init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–32
Run . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–33
4.2.3.2 Wizard properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–34
Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–34
4.2.4 Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–35
4.2.4.1 Server methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–36
AuthenticateUser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–37
BroadcastEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–38
CacheCredentials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–39
Compare . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–40
CopyTo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–41
CreateObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–42
EnsureWIPFolderExist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–43
Load . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–44
Logoff . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–45
Logon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–47
Open . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–48
Protect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–49
Save . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–50

DocuShare Windows Client SDK xiii

 Table of Contents

Unprotect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–51
UpdateSchemaCache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–52
4.2.4.2 Server properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–53
AuthDigest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–53
AuthToken . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–53
ClassSchemaEnumerator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–53
CheckinServiceManager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–54
CustomProps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–54
CustomPropName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–55
CustomPropValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–55
DBAccessToken . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–56
DocuShareAddress . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–56
Domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–57
ErrorDescription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–57
FolderHandle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–58
FolderType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–58
GuestAccess . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–59
HostServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–60
Icon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–61
Instanceld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–62
IsLoggedOn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–63
IsProtected . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–63
IsSelected . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–64
LastError . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–64
MapIndex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–65
Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–65
Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–66
OwnerHwnd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–67
Param . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–67
Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–68
ProgramFolder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–68
ProtocolScheme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–69
ProxyAddress . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–69
ProxyAuth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–69
ReadOnly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–70
SessionFlags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–70
SHItemDescriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–71
ShortcutStore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–72
TypeIndex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–74
UseProxy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–74
UserHandle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–75
UserName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–75
UseWindowsAuth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–75

xiv DocuShare Windows Client SDK

Table of Contents

Version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–76
WIPFolder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–76
WorkFolder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–77
WWWAuth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–77
WWWSecure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–77
4.2.5 CheckinServiceManager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–78
4.2.5.1 CheckinServiceManager methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–78
OpenUIService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–78
IsCheckinFormRequired . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–78
4.2.5.2 CheckinServiceManager properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–78
4.2.6 PropCollection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–79
4.2.6.1 PropCollection methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–79
Add . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–79
Close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–80
Find . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–80
Load . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–81
Next . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–82
Remove . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–83
Reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–83
Save . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–83
4.2.6.2 PropCollection properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–84
ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–84
Length . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–84
Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–84
NextItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–85
NextPos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–85
4.2.7 CustomProp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–86
4.2.7.1 CustomProp methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–86
4.2.7.2 CustomProp properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–86
Attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–86
Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–87
Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–87
ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–88
Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–88
Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–88

Chapter 5 DSItemEnumLib Library

5.1 Object model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–2
5.2 Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–4
5.2.1 ItemObj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–4

DocuShare Windows Client SDK xv

 Table of Contents

5.2.1.1 ItemObj methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–7

Attach . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–7
AttachGateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–8
AttachParents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–9
CancelTask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–10
Compare . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–11
CopyTo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–13
CreateObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–14
DetachGateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–15
DSCopy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–16
DSCreate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–18
DSDelete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–20
DSDownload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–22
DSEdit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–25
DSFind . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–27
DSLoadChildren . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–30
DSLoadProps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–34
DSLock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–36
DSMove . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–37
DSSaveProps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–38
DSSelect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–40
DSUpload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–43
GetPropStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–47
GetStateInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–48
IsChildOf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–49
LoadDefaultProps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–50
OpenGateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–51
PreloadCustomProps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–51
SaveDefaultProps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–52
SetPropStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–54
UpdateLinks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–54
EnumObjects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–55
EnumPresets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–56
EnumProps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–57
5.2.1.2 ItemObj properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–59
SchemaEnumerator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–59
DSErrorCode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–60
DSGatewayMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–64
DSServerMapld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–64
Reload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–65
Abstract . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–65
AccessControlGrants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–66

xvi DocuShare Windows Client SDK

Table of Contents

AlternateRendition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–67
Author . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–67
AutoDelete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–67
BackgroundImage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–68
BaseType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–68
BaseTypeNum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–68
ClientProp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–69
Comment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–70
CompoundContainer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–70
ContainerItemObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–70
Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–71
CorePropIds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–72
CustomProp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–73
Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–74
Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–74
ExcludedCoreProps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–75
ExcludedProps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–76
Filename . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–77
Handle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–77
HandleNum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–77
HighestVersionUsed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–78
Icon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–78
IsContainer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–79
IsCustomType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–79
IsLocked . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–79
IsPrivate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–80
IsReadOnly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–82
Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–82
Length . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–83
LocalProp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–83
LockedBy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–84
LockedByNum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–84
Logo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–84
MaxVersions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–84
MimeType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–85
ModifiedBy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–85
ModifiedbyNum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–85
Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–86
ObjectTypeNum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–86
Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–87
Owner . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–91
OwnerNum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–91
Parent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–91

DocuShare Windows Client SDK xvii

 Table of Contents

ParentCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–91
ParentHandle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–92
ParentHandleNum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–92
ParentItemObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–92
ParentType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–93
ParentTypeNum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–93
PreferredRendition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–94
Picture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–94
Prop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–95
PropIds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–96
ReferrerItemObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–97
RequiredPropsAreSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–97
Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–98
SortOrder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–98
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–98
TaskStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–99
Thumbnail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–100
TimeAccessed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–100
TimeCreated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–100
TimeModified . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–101
Title . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–101
Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–101
TypeId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–102
TypeIndex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–102
TypeNum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–103
URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–103
User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–103
UserNum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–103
ValidatedFileHandle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–104
VersionNum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–105
5.2.2 EnumObj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–106
5.2.2.1 EnumObj methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–106
Attach . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–106
Attach2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–107
Clear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–108
CopyTo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–108
GetLengthOf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–109
GetNode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–109
Load . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–110
NewItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–111
RemoveItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–112
Reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–112

xviii DocuShare Windows Client SDK

Table of Contents

Sort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–113
5.2.2.2 EnumObj properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–115
Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–115
Length . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–115
NextItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–116
NextPos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–116
5.2.3 EnumSchema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–117
5.2.3.1 EnumSchema methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–117
NewItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–117
Reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–117
RemoveItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–117
Load . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–117
5.2.3.2 EnumSchema properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–118
Length . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–118
NextItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–118
NextPos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–118
5.2.4 ItemSchema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–119
5.2.4.1 ItemSchema methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–120
ResetMenu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–120
NewMenuItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–120
RemoveMenuItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–120
ClearMenu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–120
CopyTo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–120
5.2.4.2 ItemSchema properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–121
Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–121
Label . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–121
TypeNum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–121
HelpText . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–121
IsSystem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–122
IsRequired . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–122
IsReadOnly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–122
DefaultValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–122
MinimumValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–123
MaximumValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–123
MenuLength . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–123
NextMenuItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–123
NextMenuPos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–124
TypeStr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–124
PropsEnumerator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–124
IsMultivalued . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–124
ItemTypeNum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–125

DocuShare Windows Client SDK xix

 Table of Contents

Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–125
ItemObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–125
5.2.5 EnumSchemaProps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–125
5.2.5.1 EnumSchemaProps methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–125
Reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–126
Next . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–126
5.2.5.2 EnumSchemaProps properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–126
Length . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–126
NextItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–127
NextPos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–127
5.2.6 SchemaProp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–127
5.2.6.1 SchemaProp methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–127
5.2.6.2 SchemaProp properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–127
Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–127
TypeNum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–128
Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–128
5.2.7 EnumItemProps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–129
5.2.7.1 EnumItemProps methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–129
Clear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–129
NewItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–129
Next . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–129
RemoveItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–129
Reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–130
5.2.7.2 EnumItemProps properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–131
Item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–131
Length . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–131
NextPos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–131
NextItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–131
5.2.8 ItemProp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–133
5.2.8.1 ItemProp methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–133
CreateControl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–133
CopyTo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–133
EnumValues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–133
5.2.8.2 ItemProp properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–134
ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–134
ItemSchema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–134
Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–134
Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–135
Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–135

xx DocuShare Windows Client SDK

Table of Contents

XMLName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–135
Label . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–136
Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–136
5.2.9 EnumPropValues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–137
5.2.9.1 EnumPropValues methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–137
Clear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–137
Next . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–137
NewItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–137
RemoveItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–137
Reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–138
5.2.9.2 EnumPropValues properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–139
Item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–139
Length . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–139
NextItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–139
NextPos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–140
5.2.10 PropValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–141
5.2.10.1PropValue methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–141
5.2.10.2PropValue properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–141
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–141
Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–141
XMLValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–142
5.2.11 ErrorReportObj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–143
5.2.11.1ErrorReportObj methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–143
Init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–143
Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–143
SetErrorInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–144
ShowDialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–144
5.2.11.2ErrorReportObj properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–145
AttemptedCommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–145
ClientRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–145
DSAccessData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–145
ErrorCode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–145
ErrorDescription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–146
ErrorDisplayType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–146
ErrorPhrase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–146
GatewaySettings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–147
LogFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–147
ServerResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–148
Silent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–148
StatusCode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–148

DocuShare Windows Client SDK xxi

 Table of Contents

5.2.12 NameConflictResolver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–149

5.2.12.1NameConflictResolver methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–149
Rename . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–149
ResolveLocalName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–151
ResolveRemoteName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–153
ResolveRemoteName2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–155
RunCommentDialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–157
5.2.12.2NameConflictResolver properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–158
AutoComment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–158
CollectionObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–158
ErrorDisplayType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–158
FixedComment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–159
ForceRename . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–159
ForceReplace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–159
ReplacedItemHandle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–160
VersionComment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–160
5.2.13 StatusObj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–161
5.2.13.1StatusObj methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–161
HideDialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–161
HideProgress . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–161
ShowDialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–162
ShowProgress . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–162
Subscribe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–163
5.2.13.2StatusObj properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–165
CanCancel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–165
CancelCode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–165
CanReportNetworkProgress . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–165
CanReportNetworkStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–166
CanShowStatusAsBalloonTip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–166
CreateThread . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–166
GatewayEventWindow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–167
IconPath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–167
LowerLimit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–167
ParentWindow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–168
Progress . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–168
SubLowerLimit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–168
SubText . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–169
SubUpperLimit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–169
Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–169
Title . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–169
TopMostDialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–170

xxii DocuShare Windows Client SDK

Table of Contents

UpperLimit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–170
Visible . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–170
WindowHandle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–170
5.2.14 CommentUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–171
5.2.14.1CommentUI methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–171
RunDialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–171
5.2.14.2CommentUI Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–171
WindowHandle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–171
5.2.15 RenameUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–172
5.2.15.1Rename methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–172
RunDialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–172
5.2.15.2Rename properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–172
WindowHandle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–172
5.2.16 EnumPresets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–173
5.2.16.1EnumPresets methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–173
Function Next . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–173
Function Reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–173
Property Length . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–174
Property nextItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–174
Property NextPos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–174
5.2.16.2EnumPresets properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–174
DefaultPreset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–174
UsePersonalPreset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–174
5.2.17 IPreset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–175
5.2.17.1IPreset properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–175
5.3 Compound document support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–176
5.3.1 Constituent File Layout of Compound Document in PC . . . . . . . . . . . . . . . . . . . . 5–176
5.3.2 Alternate Layout—IE-style Connected File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–176
5.3.3 Downloading Compound Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–177
5.3.4 Finding Out Content Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–177

Chapter 6 Properties and Permission Controls

6.1 PropObj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6–2
6.1.1 IPropCtrl Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6–2
6.1.2 IPropCtrl properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6–3
6.1.3 IPropCtrlEvents Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6–3
6.2 DsPropsObj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6–4
6.2.1 IDsPropsCtrl Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6–5

DocuShare Windows Client SDK xxiii

 Table of Contents

6.2.2 IDsPropsCtrl Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6–6

6.2.3 IDsPropsCtrlEvents Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6–6
6.3 PermObj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6–7
6.3.1 IPermCtrl Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6–7
6.3.2 IPermCtrl Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6–7
6.3.3 _IPermCtrlEvents Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6–7

Chapter 7 DSAxess Console

7.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–2
7.1.1 Console variables and program flow control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–2
7.2 Script Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–4
7.3 DSAxess console enhancements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–5
7.3.1 Custom property support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–5
7.3.1.1 Replicate command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–5
7.3.1.2 GetProps command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–5
7.3.1.3 Login context switching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–5
7.3.2 Custom Object Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–6
7.3.3 Object specification by title . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–7
7.4 Script Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–8
7.4.1 Login . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–8
7.4.2 Navigation and Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–9
7.4.3 Uploading Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–11
7.4.4 Downloading Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–13
7.5 Console commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–14
Command notations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–14
CD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–15
Clearcache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–15
CLS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–16
Copy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–16
Createuser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–17
Delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–19
DeleteUser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–21
Dir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–22
Disown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–23
Echo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–24
Edit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–24
Errordlg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–25
Eventlog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–25
Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–25

xxiv DocuShare Windows Client SDK

Table of Contents

Get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–26
GetHandle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–29
GetParam . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–30
GetProps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–34
GetSchema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–36
Goto . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–38
Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–38
History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–38
If Then . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–39
LCD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–40
Let . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–41
Lineage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–43
ListRenditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–44
Lock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–45
Login . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–45
Logout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–45
Lopen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–46
Mapserver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–46
Mkdir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–47
Move . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–47
Newversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–48
Open . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–49
Progress . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–49
Prompt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–49
Put . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–50
RemoveProps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–54
Rename . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–54
Replicate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–55
ResumeOnError . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–56
Search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–58
Setparam . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–61
SetProps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–62
StatusCheck . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–63
Switchto . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–64
Tree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–65
Unlock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–67
Unmapserver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–67
Updateschema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–67
WebLogin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–68
Writelog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–68

DocuShare Windows Client SDK xxv

 Table of Contents

xxvi DocuShare Windows Client SDK

 DocuShare Windows Client SDK
Welcome to the DocuShare Windows Client Software Development Kit Guide. This guide will
assist you in designing custom Windows applications that utilize the features and functionality
of a DocuShare Server.

DocuShare Windows Client SDK 1–1

Overview DocuShare Windows Client SDK

1.1 Overview
The DocuShare Windows Client SDK is a collection of ActiveX OLE Automation and COM interfaces for
programming in the Windows environment. The DocuShare Windows Client, DocuShare Outlook Client,
and PaperPort Link applications were developed with the DocuShare Windows Client SDK. Other
DocuShare Client applications and macros can be constructed using Microsoft Visual Basic, Visual Basic
for Applications, Visual Basic Script, or C++.

In addition to the COM interfaces, the DocuShare Windows Client SDK contains a DocuShare script
interpreter and language. The script is designed to assist the administrator in accomplishing common
repetitive tasks.

The DocuShare Windows Client SDK provides a Windows OLE Automation layer over the DocuShare
HTTP/XML interface. The SDK consists of three main interface modules:

• Server Mapping (ServerMap)—the interface that creates server mapping of DocuShare servers into
Client cache and user accounts.
• Item Access and Enumeration (ItemEnum)—the high level interface that provides a simple object,
enumeration, and property access interface to the various DocuShare object types.
• Gateway Provider (Client Gateway)—the low level interface that translates API parameters into
XML commands and manages the socket connection to the server. Most operations are
accomplished through the ItemEnum interface without using the Client Gateway.
Additonal components in the DocuShare Windows Client SDK include:

• Properties and Permission Controls—visual ActiveX controls that provide intuitive user interfaces
for viewing and editing DocuShare object properties and permissions.
• DSAxess Console—a command line interface to the DocuShare server. Commands can be entered
interactively or from batch scripts.
• SDK Help—provides a printable (PDF) version of this guide which contains comprehensive
information for the API calls, parameters, return values, and error conditions.
• Samples—sample utilities and macros using the DocuShare Windows Client SDK. Samples include
Visual Basic programs, Office macros, and MFC applications.
DocuShare Windows Client SDK requires Microsoft Internet Explorer 4 or higher installed on the local PC.
The SDK uses the XML parser bundled with IE for decoding responses from the server.

1.1.1 DSServerMap Library

The DocuShare Windows Client, DocuShare Outlook Client, and PaperPort Link share a cache of mapped
DocuShare servers. This interface provides administrative interfaces to manage this cache and to add,
modify, or delete servers from the registry. Interfaces for creating user accounts on a server are also
provided. Refer to Chapter 4, DSServerMap Library for details.

1.1.2 DSItem EnumLib Item Object and Item Enumerator Library

The DocuShare Windows Client SDK provides a dual interface for enumerating objects on the DocuShare
server and inspecting object properties. Most Visual Basic applications can make all their calls through the
synchronous methods for this interface. In cases where additional functionality is required, the Gateway
Provider interface can be accessed. Refer to Chapter 5, DSItemEnumLib Library for details.

1–2 DocuShare Windows Client SDK

DocuShare Windows Client SDK Overview

1.1.3 DSGateway Library

This underlying component of the DocuShare Windows Client SDK manages all socket and XML
communication with the DocuShare server. Supplied parameters are transposed into the HTTP/XML
requests supported by the server; and the XML response body parses back into object classes managed
by the Gateway. Both standard HTTP and SSL encrypted connections are supported. Only complex
applications need to access the Gateway layer directly. Refer to Chapter 3, DSGateway Library for details.

1.1.4 Properties and Permissions Controls

Properties and Permissions Controls are visual ActiveX controls that provide intuitive user interfaces for
viewing and editing DocuShare object properties and permissions. The user interface provides
programmers with an easy-to-use component for rendering a DocuShare property in a consistent, user-
friendly representation. Refer to Chapter 6, Properties and Permission Controls for details.

1.1.5 DSAxess Console

In addition to the programmatic interfaces provided in the DocuShare Windows Client SDK, DSAxess
Console provides an interactive shell to connect to a DocuShare server. The console can be used to
access, update, and query server objects. Command batch files can also be passed to the command
console for automated scripting. Refer to Chapter 7, DSAxess Console for details.

DocuShare Windows Client SDK 1–3

Overview DocuShare Windows Client SDK

1–4 DocuShare Windows Client SDK

 SDK Programming
The Windows Client SDK assists you in designing custom Windows applications that utilize
the features and functionality of a DocuShare Server. This chapter provides the most common
features of the DocuShare Windows Client API.

• Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–2
• Programming Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–3
• DocuShare Client Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–13
• Opening a DocuShare session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–14
• Creating a new DocuShare item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–16
• Updating a DocuShare file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–19
• Creating a new user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–24
• Running a selection dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–25
• Managing multiple DocuShare objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–29
• Log into a DocuShare server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–31
• Navigating a DocuShare server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–36
• Working with properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–46
• Uploading documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–57
• Performing basic searches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–64
• Managing server connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–71
• Accessing the DocuShare objects using C++. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–75
• Event handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–77

DocuShare Windows Client SDK 2–1

Overview SDK Programming

2.1 Overview
The Windows SDK supplies four ActiveX libraries:

• Server Map library

• Item Object and Enumerator library
• Gateway library
• Support library
The Server Map library is used to manage a database of server maps. A server map is a persistent
collection of server access information, such as the home URL of the server and username.

The Item Object and Enumerator library is used to discover, create, and update existing DocuShare items
(such as files and collections) and their properties.

The Gateway library is used internally by both the Server Map and Item Object and Enumerator libraries to
establish network connections with a DocuShare server and to translate client requests to DocuShare
HTTP/XML protocol commands. The Gateway library may be used to perform advanced functions such as
searching DocuShare items and asynchronous file uploading. For common tasks, the Gateway library is
not required.

The support library consists of ActiveX controls for high-level functions, for example, display DocuShare
item properties and permissions.

In this chapter, specific terminology is used:

• server—specifies a user session consisting of a series of DocuShare service processes created by

an HTTP web server.
• item—specifies a resource that physically exists in a DocuShare server. An example item may be a
file.
• object—specifies a class object defined and implemented by a client application. An object may or
may not represent a DocuShare item.
• interface—specifies a programmable COM interface exposed by an object.
• local—refers to the client machine running the SDK libraries.

2–2 DocuShare Windows Client SDK

SDK Programming Programming Model

2.2 Programming Model

The functional relationship of the objects defined and implemented by the Windows Client SDK is
illustrated in Figure 2–1.

Figure 2–1: SDK Programming Model

In the Windows Client SDK programming model, DocuShare servers and server items (such as files and
collections) are logically represented by the IServer and IItemObj COM interfaces.

An IServer object encapsulates a server map and opens and closes a DocuShare session; an IItemObj
item object describes a DocuShare item. To discover an existing DocuShare item, an IItemObj object
representative of an item is created, and an appropriate query method is utilized. Depending on the
queried item, the query result may involve enumeration of child items.

DocuShare Windows Client SDK 2–3

Programming Model SDK Programming

The IEnumObj enumerator object is used to perform item enumeration. Enumeration yields child IItemObj
objects; each object represents a child item of the queried parent item.

An IServer object may be created as a stand-alone object. A temporary IServer object is created and then
deleted when access to a particular server is no longer needed or when your application terminates. Also,
an IServer object may be made persistent by saving it to a permanent database for reuse. This is useful
when there is a need to present the same list of servers to an end user each time your application is run.
The database is called the Server Map database and its contents (server maps) are managed by the IStore
object. The Windows Client SDK uses the Windows system registry to maintain this database.

The IStore object exposes the IStore COM interface. This interface is used to discover existing IServer
objects. The IStore interface manages a server map database. With IStore, you can create a new server
map database, load an existing database, and add or remove a new server map to an existing database.
The IStore enumeration of existing server maps yields IServer objects; each object logically represents a
DocuShare server.

To create a new server map, the SDK supplies an IWizard helper object. You can use this helper object to
collect server mapping information from a user and to add the new server map to an existing IStore object.

You can locate an IServer object programmatically, such as a DocuShare server, and then utilize the
IServer user authentication method to open an active session against the selected DocuShare server. To
locate a specific IServer object, use the IStore query method, or use the IStore selection dialog to choose
an IServer object.

The DocuShare Client application uses the IStore service to maintain the collection of mapped servers
presented in Windows Explorer. By using the default IStore, any application can use these ready mapped
servers. It is also possible to create an independent database for access from your application.

The IItemObj interface is used to represent a DocuShare item. An IItemObj object is typically created from
an authenticated IServer object and is given a specific item type and an optional DocuShare handle for a
known existing item. A child IItemObj object can be created from a parent IItemObj object of a container
type.

• To create an IServer object from an IStore object:

Open a user session by calling the IServer logon method. Create an IItemObj object with the
authenticated IServer CreateObject method and supply the handle to the item represented by the
IItemObj interface.
• To create a physical instance of the object item (without contents) in DocuShare:
Set the necessary IItemObj properties to values that describe the new item, and make a call to the
IItemOb DSCreate method.
• To query properties of the object item:
Make a call to the IItemObj DSLoadProps method.
• To modify properties:
Modify the values of IItemObj properties, and make a call to the IItemObj DSSaveProps method.
• To update the contents of a file item:
Specify the IItemObj's name property to the location (path) of a local file, and make a call to the
IItemObj DSUpload method.
• To retrieve the contents of a file item:
Make a call to the IItemObj DSDownload method.
• To discover items in a DocuShare collection:
Create an IItemObj object for the collection, make a call to the collection object DSLoadChildren,
and utilize IEnumObj enumeration methods and properties.

2–4 DocuShare Windows Client SDK

SDK Programming Programming Model

The enumeration returns IItemObj interfaces for the child items of the collection. With these interfaces, you
can proceed to perform item specific tasks such as query properties for each item (DSLoadProps) and
updating its contents (DSUpload). By repeating the steps of the DSLoadChildren call and the child
enumeration, you can browse nested collections.

The IItemObj object provides limited search functionality. See method of object ItemObj, DSFind on page
5–27. For advanced search capability, you need to use the gateway object. Also, the network accessing
methods of the object are synchronous, so control does not return from a network call until the call
completes. Therefore, you cannot use methods of IItemObj, such as performing an upload task in the
background and updating a progress display in the foreground, at the same time. To do so, you need to
use asynchronous methods exposed by the gateway object and subscribe to the gateway's event
notification service.

2.2.1 IItemObj and Supported Item Types

IItemObj can be used to represent the following DocuShare item types:

• Server (root folder—corresponding to the home URL of a DocuShare server)

• Collection
• File (document)
• Version (version of a document)
• Saved Query Collection
• Calendar
• Bulletin board
• URL
• User
• Group
Depending on the item type prescribed for an IItemObj object, the properties of IItemObj may or may not
be meaningful. Also, a specific property may be different. For example, an IItemObj object representing a
collection does not use the IsLocked property which describes whether or not a file item is currently locked.
You may reference or modify the property value, but calling DSSaveProps with the modified property will
not cause any change in the actual collection. Using IItemObj's property Name for a user object, indicates
that Name refers to the username of the represented user or account; but property Name, when used by a
file object, refers to the filename of the represented file item.

Table 2–1 shows the applicability of the IItemObj interface properties with respect to the supported item
types.

DocuShare Windows Client SDK 2–5

Programming Model SDK Programming

Table 2–1: IItemObj Interface Properties

DSLoadProps
DSSaveProps

Bulletinboard
SavedQuery

Description
Collection
Data Type

Calendar
Property

Version
Access

Server

Group
User
URL
File
Abstract String R/W A A Machine generated
summary
Author String R/W A A A Author of file item
BackgroundImage String R/W A A A URL of background
image
Comment String R/W A A File item version
comments
Description String R/W A A A A A A A A A A A A Long description of
item
Handle String R/W A A A A A A A A A A DocuShare item
handle, for
example, File-123
HandleNum Integer R/W A A A A A A A A A A Item’s handle
number
IsLocked Boolean R/W A A File item is locked
or not
IsReadOnly Boolean R/W A A Item is read-only or
not
Keywords String R/W A A A A A A A A A A A A Keywords for item
Length Integer R/W A A A A A A A Length of collection
or file item
Logo String R/W A A A Length of collection
or file item
MaxVersions Integer R/W A A A Maximum number
of file item versions
MimeType String R/W A A A A File item MIME type
Name String R/W A A A A A File or user item
Name
Owner String R/W A A1 A A A A A A A A A A Owner’s
DocuShare handle
OwnerNum Integer R/W A A1 Owner’s handle
number
ParentHandle Integer R/W A A A A A A A A A A Primary parent’d
(Parent2) Item handle
ParentType String R/W A A A A A A A A A A A Primary parent’s
item type ID
ParentTypeNum Integer R/W A A A A A A A A A A A Numeric parent
type ID

2–6 DocuShare Windows Client SDK

SDK Programming Programming Model

Table 2–1: IItemObj Interface Properties

DSLoadProps
DSSaveProps

Bulletinboard
SavedQuery

Description
Collection
Data Type

Calendar
Property

Version
Access

Server

Group
User
URL
File
ParentHandleNum Integer R/W A A A A A A A A A A A Numeric parent
handle
ParentCount Integer R A A A A A A A A A A Number of parents
SortOrder String R/W A A Collection item’s
sort order
Summary String R/W A A A A A A A A A A A A Brief summary of
item
TimeAccessed Date R/W A A A A A A A A A A A Time when item
was last accessed
TimeCreated Date R/W A A A A A A A A A A A Time when item
was created
TimeModified Date R/W A A A A A A A A A A A Time when item
was last modified
Title String R/W A A A A A A A A A A A A Display name of
item
Type String R A A A A A A A A A A Returns a string
description of the
ItemObj type
TypeNum Integer R/W A A A A A A A A A A Item's type number
URL String R/W A A A URL value of URL
item
User String R/W A A A A A A A A A A A User’s DocuShare
handle
UserNum Integer R/W A A A A A A A A A A A User’s handle
number
ValidatedFileName String R A A A File item’s qualified
filename
VersionNum Integer R/W A File item’s version
number
Icon Object R A A A A A A A A A A Icon resource of
item
Thumbnail Object R/W A Thumbnail picture
of file item
TypeIndex Integer R A A A A A A A A A A Item’s Icon type
index
CustomProp Variant R/W A A A A A A A A A A A A Custom property’s
arbitrary type
Data Variant R/W A A A A A A A A A A Custom data for
private use

DocuShare Windows Client SDK 2–7

Programming Model SDK Programming

Table 2–1: IItemObj Interface Properties

DSLoadProps
DSSaveProps

Bulletinboard
SavedQuery

Description
Collection
Data Type

Calendar
Property

Version
Access

Server

Group
User
URL
File
ExcludedCoreProps Integer R/W A A A A A A A A A A A A Set of flags for
common properties
ExcludedProps Integer R/W A A A A A A A A A A A A Set of flags for type-
specific properties
AutoDelete Boolean R/W A Can delete attached
downloaded file
DSErrorCode Integer R A A A A A A A A A A Gateway error code
DSGatewayMode Integer R/W A A A A A A A A A A Gateway mode
settings
DSServerMapId Integer R/W A A A A A A A A A A A A Instance ID of
associated server
map
Reload Boolean R/W A Can reload
Thumbnail, Picture,
or VersionNum; or
causes
DSDownload to call
DSLoadProps
internally for
downloading a
compound
document.
TaskStatus Integer R A A A A A A A A A A Status of the current
asynchronous task
ModifiedBy String R/W A A A A A A A A A A Name of the user
who last modified
the item
ModifiedByNum Integer R/W A A A A A A A A A A Handle of the user
who last modified
the item
LockedBy String R/W A A A Name of the user
who locked the item
LockedByNum Integer R/W A A A Handle of the user
who locked the item
AccessControlGrants Integer R/W A A This user’s access
control grants for
the parent object
SchemaEnumerator Object R/W A A A A A A A A A Property schema
enumerator
XMLDOM Object R/W A A A A A A A A A A XML representation
of properties

2–8 DocuShare Windows Client SDK

SDK Programming Programming Model

Table 2–1: IItemObj Interface Properties

DSLoadProps
DSSaveProps

Bulletinboard
SavedQuery

Description
Collection
Data Type

Calendar
Property

Version
Access

Server

Group
User
URL
File
IsPrivate Boolean R/W A A A A A A A A A A A DocuShare
property ’private’
StatusObject Object R/W A A A A A A A A A A Displays progress
in DocuShare
processing
ErrorReportObject Object R/W A A A A A A A A A A Holds error
information from
DocuShare
NameConflictResolver Object R/W A A A A A A A A A A Runs a resolution
dialog
Options Integer R/W A A A A A A A A A A Controls ItemObj
behavior
Contents Variant R/W A A Content data of file
item
AlternateRendition Object R/W A A Alternate (2nd)
rendition of a
compound
document
PreferredRendition Object R/W A A Preferred (1st)
rendition of a
compound
document
ReferrerItemObject Object R/W A A File that refers to
this ItemObj
ParentItemObject Object R/W A A A A A A A A A A ItemObj
representation of
primary parent item
CompoundContainer Object R/W A A A Collection that
holds attachments
ClientProp String R/W A A A A A A A A A A Special property
defined by a client
application and
stored in
DocuShare
client_data property
CorePropIds Integer R A A A A A A A A A A Core property IDs
for this object
PropIds Integer R A A A A A A A A A A Type specific
property IDs for this
object
Server Object R/W A A A A A A A A A A Server object

DocuShare Windows Client SDK 2–9

Programming Model SDK Programming

Table 2–1: IItemObj Interface Properties

DSLoadProps
DSSaveProps

Bulletinboard
SavedQuery

Description
Collection
Data Type

Calendar
Property

Version
Access

Server

Group
User
URL
File
Picture Object R A A Visual
representation of an
image file
Prop Variant R/W A A A A A A A A A A Accesses a
property of ItemObj
by name
Filename String R/W A A A DocuShare
property ’document’
IsContainer Boolean R A A A A A A A A A A True, if the item is a
container type
IsCustomType Boolean R A A A A A A A A A A True, if the item is a
custom object type
derived from a
standard object
type, for example,
File
HighestVersionUsed Integer R/W A A DocuShare
property
’highest_version_us
ed’
RequiredPropsAreSet Boolean R A A A A A A A A A Indicates whether
all required
DocuShare
properties have a
non-empty value
ObjectTypeNum Integer R A A A A A A A A A DSX_OBJTYPE
number that
corredponds to this
ItemObj
BaseTypeNum Integer R/W A A A A A A A A A A Numeric base type
ID
BaseType String R/W A A A A A A A A A A Base type from
which this ItemObj
item was derived
ContainerItemObject Object R/W A A A A A A A A A A Container of this
ItemObj item
LocalProp Variant R/W A A A A A A A A A A A property
temporary in scope
and local to this
ItemObj
TypeId String R/W A A A A A A A A A A Numeric type ID of
this ItemObj item

2–10 DocuShare Windows Client SDK

SDK Programming Programming Model

Table 2–1: IItemObj Interface Properties

DSLoadProps
DSSaveProps

Bulletinboard
SavedQuery

Description
Collection
Data Type

Calendar
Property

Version
Access

Server

Group
User
URL
File
ExpirationDate Date R/W A A A A A A A A A A A DocuShare
property
’expiration_date’
Legend: A = Applicable, R = Read-only, R+W = Read/Write. 1 = The applicability depends on a server’s schemata for
the DocuShare entityowner property. DocuShare 5 typically supports write access to Owner. 2 = Property Parent is
retained for backward compatibility. ParentHandle should be used in a new application.

NOTE: In Table 2–1, item properties that have read and write accessibility is not always modifiable via
the DSSaveProps method. Also, a number of properties including Data and DSErrorCode do
not participate in either the DSLoadProps or DSSaveProps methods. They are private
properties of IItemObj.

The methods of IItemObj also have item type dependency. Refer to Table 2–2.

Table 2–2: IItemObj Interface Methods

Bulletinboard
SavedQuery

Description
Collection

Calendar
Version
Method

Server

Group
User
URL
File

CreateObject A A A A A A A Create a child object

DSCopy A A A A A A A1 A1 Copy reference of item

DSCreate A A A A A A A A Create representing item in

DocuShare

DSDelete A A A A A A A A Delete or disown item

DSDownload A A A A Download contents of file item

DSEdit A Run an associated editor*

DSLoadChildren A A A A A A A Load child items of container item

DSLoadProps A A A A A A A A A A Load properties of item

DSLock A Lock or unlock file item

DSMove A A A A A A A1 A1 Move item

DSSaveProps A A A A A A A A A A Save properties of item

DSSelect A A A A A A A A Select item from browser dialog

DSUpload A A A Upload contents of file item

DocuShare Windows Client SDK 2–11

Programming Model SDK Programming

Table 2–2: IItemObj Interface Methods

Bulletinboard
SavedQuery

Description
Collection

Calendar
Version
Method

Server

Group
User
URL
File
GetPropStruct A A A A A A A A A A Get internal property structure

SetPropStruct A A A A A A A A A A Set internal property structure

Attach A A A A A A A A A A Attach a child item list

AttachParents A A A A A A A A A A Attach a parent item list

Compare A A A A A A A A A A Compare to another IItemObj by

property

CopyTo A A A A A A A A A A Copy all IItemObj properties

EnumObjects A A A A A A A Generate enumerator for child

items

IsChildOf A A A A A A A Determines if child of a container

item

AttachGateway A A A A A A A A A A Attach server map object

DetachGateway A A A A A A A A A A Detach server map object

Legend: A = Applicable; * = requires DSClient installation.

1= these methods do not work for DocuShare 3.x due to a change in the DocuShare HTTP/XML protocol.

2–12 DocuShare Windows Client SDK

SDK Programming DocuShare Client Tasks

2.3 DocuShare Client Tasks

All DocuShare Client applications share some common, basic, and advanced tasks. The following sections
detail the various methods to accomplish these tasks.

2.3.1 Common Tasks

• Opening a DocuShare session on page 2–14
• Creating a new DocuShare item on page 2–16
• Updating a DocuShare item on page 2–16
• Moving, copying and deleting an item on page 2–21
• Updating a DocuShare file on page 2–19
• Creating a new user on page 2–24
• Running a selection dialog on page 2–25
• Managing multiple DocuShare objects on page 2–29

2.3.2 Basic Tasks

• Log into a DocuShare server on page 2–31
• Navigating a DocuShare server on page 2–36
• Working with properties on page 2–46
• Uploading documents on page 2–57
• Performing basic searches on page 2–64

2.3.3 Advanced Tasks

• Managing server connections on page 2–71
• Accessing the DocuShare objects using C++ on page 2–75
• Event handling on page 2–77

DocuShare Windows Client SDK 2–13

Opening a DocuShare session SDK Programming

2.4 Opening a DocuShare session

To administer any DocuShare server, you need to obtain a session handle from the server. This process is
called user authentication. To achieve this, your application creates an IServer instance which represents a
user attempting to login to a DocuShare server.

As a simple example, create a stand-alone IServer object and assign a known home URL and other
necessary parameters to the object. Refer to Managing server connections on page 2–71 on permanently
storing and loading IServer objects.

dim server
set server = CreateObject("DSServerMap.Server")
server.Name = "DocuShare XYZ"
server.DocuShareAddress = http://my.docushare.com/
With an IServer object instantiated and server accessing information set, you can create a client
representation of the server's home page by substantiating an IItemObj object for Server.

dim root
set root = server.CreateObject("Server")
The Server object is used to find the top level collections of a DocuShare server. It corresponds to the
home page of the server when viewed in a web browser window. Enter the following to find the top level
collections.

status = root.DSLoadChildren
When this statement is executed, the method runs a login dialog automatically. It is possible to explicitly
call IServer.Logon prior to the DSLoadChildren call. Examples of various login techniques to a DocuShare
server can be found in the section Log into a DocuShare server on page 2–31.

Following a successful completion of the login process, the method executes an HTTP/XML PROPFIND
command against DocuShare to discover the child items. A return value of zero indicates that the
command was successful and the resultant top level collection list correctly loaded into the Server object.

Now you can obtain an enumerator and print the collection titles.

dim topList
set topList = root.EnumObjects(DSCONTF_CHILDREN)
topList.Reset
while topList.NextPos <> 0
dim topCollection
set topCollection = topList.NextItem
Print topCollection.Title
wend
If desired, you can output other properties relevant to the iterated item. Instead of outputting more
properties, apply the following to browse the child items.

dim list
set list = root.EnumObjects(DSCONTF_CHILDREN)
list.Reset

2–14 DocuShare Windows Client SDK

SDK Programming Opening a DocuShare session

while list.NextPos <> 0

dim topCollection
set topCollection = list.NextItem
status = topCollection.DSLoadChildren
if status = 0 then
dim subCollection
set subCollection = topCollection.EnumObjects
subCollection.Reset
while ...
...
wend
end if
wend
This is an example of bad code; it is redundant and certainly not practical if you want to extend the iteration
to discover all items of the collection tree. However, this example is to illustrate the point that the
IItemObj.DSLoadChildren method and IEnumObj enumeration properties are used in tandem to achieve
browsing nested collections. An additional browse example can be found at Navigating a DocuShare
server on page 2–36.

DocuShare Windows Client SDK 2–15

Creating a new DocuShare item SDK Programming

2.5 Creating a new DocuShare item

To create a new DocuShare item, a representation of the object is created from an IServer object.

dim file
set file = server.CreateObject("File")
For example, to create an MS Word file, preset the MIME type property and identify a container, such as
Collection-123, where the file will be placed. Make these assignments and include the title property.

file.Title = "New file"

file.MimeType = "application/msword"
file.ParentHandle = "Collection-123"
If no MIME type is specified, the default binary MIME type is used. Make a call to IItemObj DSCreate.

status = file.DSCreate
If the originating IServer object was not supplied with a password, the DSCreate method runs a login
dialog and proceeds to upload a copy of MS Word's template file to DocuShare. Successful creation
generates a file handle, and the handle property of the IItemObj file object holds the generated handle
value. At this time, you can call DSLoadProps to synchronize the IItemObj with the actual item in
DocuShare.

To edit the created file, follow the DSCreate call with a call to DSEdit. To lock the file, call DSLock with the
flag parameter set to boolean TRUE.

IItemObj supports all standard DocuShare item types. For example, to create a blank bulletin board, call
IServer.CreateObject with the handle parameter set to Bulletinboard. The following code is a sample for
creating a bulletin board.

dim bboard
set bboard = server.CreateObject("BulletinBoard")
bboard.Title = "Test bulletinboard"
bboard.ParentHandle = "Collection-123"
status = bboard.DSCreate
Other item types can be created in the same way. The differences are that a different handle or item type is
given to IServer.CreateObject and properties applicable to the particular item type needs to be set. As an
example, an URL item can be created by calling IServer.CreateObject with the handle parameter set to
URL. Also, you need to set the URL property of IItemObj to a valid URL which the item references, before
calling the DSCreate method. For a list of required properties, refer to CreateObject on page 5–14.

2.5.1 Updating a DocuShare item

To update an item, set one or more IItemObj item properties and save the updated properties to
DocuShare by calling IItemObj.DSSaveProps. The following section explains how to update the contents
of an item, such as a file item.

An example of updating a DocuShare item is changing the password, a user item, for a user account.
Refer to Creating a new user on page 2–24.

2–16 DocuShare Windows Client SDK

SDK Programming Creating a new DocuShare item

To change the user account password:

1. Get a new password from a dialog.

password = InputBox "Enter new password"
confirmation = InputBox "Enter password confirmation"
2. If the password is confirmed, set the item password property. Because the password property is
not formally defined by the IItemObj interface, the password is saved as a custom property.
user.CustomProp("password", 1) = password
3. Change the password in DocuShare.
status = user.DSSaveProps

NOTE: By default, DSSaveProps updates all properties known to IItemObj.

2.5.1.1 Updating certain properties

IItemObj defines two flag properties, ExcludedCoreProps and ExcludedProps. ExcludedCoreProps refers
to the properties common to all item types, and ExcludedProps refers to properties only applicable to the
item type in question. A different set of flag values is defined for each item type.

To prevent DSSaveProps from updating a certain property, set a bitfield in one of the flag properties
corresponding to the property. To exclude multiple properties, you can combine appropriate bitfields using
a bit-wise OR operation.

To update certain DocuShare properties

1. Create a file object for an existing DocuShare file and load it with up-to-date properties from the
server.
dim file
set file = server.CreateObject("File-123")
status = file.DSLoadProps

NOTE:This example assumes that file "File-123" exists in the server.

2. Modify the summary and keywords properties.

file.Summary = "This is a modified test summary"
file.Keywords = "Test, Modified"
3. If the rest of the properties are up-to-date, exclude them from DSSaveProps.
file.ExcludedCoreProps = DSAXES_PROPID_CORE_TITLE Or [...]
file.ExcludedProps = DSAXES_PROPID_FILE_MIMETYPE Or [...]

DocuShare Windows Client SDK 2–17

Creating a new DocuShare item SDK Programming

NOTE: In real code the [...] placeholders are replaced with other property bit-masks.

4. Call the save method to update the file's properties.

status = file.DSSaveProps

2–18 DocuShare Windows Client SDK

SDK Programming Updating a DocuShare file

2.6 Updating a DocuShare file

To update a DocuShare file, download and place a lock on a file so that another user cannot modify it while
you are updating it. After you edit and save the local copy of the file, upload the updated file back to
DocuShare. Use the following to lock the file.

status = file.DSDownload( DSAXES_FLAG_DOWNLOADLOCKED )

The file is locked and ready for editing. The location of the local copy is in the IItemObj.Name property of
the file object. As an example, MyEditFunction, which is defined somewhere else, edit the contents with
the following:

status = MyEditFunction( file.Name )

The file is updated and ready to be saved. It is recommended, but optional, to supply version comments.

file.Comment = "Second draft"

status = file.DSUpload
If you are updating a file item with locally generated contents, you set the IItemObj.Name property of the
file object to the location (path) of the local file. As in the above example, when you call
IItemObj.DSDownload without first setting the Name property to a known local location, DSDownload uses
a work folder under the SDK install directory and automatically generates a unique filename for it. If you
want to download the contents to a particular location, make sure you first set the Name property.

Remember that DSCreate can be used to create an empty item in DocuShare. With regards to a file item,
DSCreate creates an empty file. To create a file with contents, you use DSUpload. You need to create a
new file object which has not been assigned a DocuShare handle. Also, you need to identify the collection
to which the file will be copied, and set the Name property to where the local file resides. For example:

dim newFile
set newFile = server.CreateObject("File")
newFile.ParentHandle = "Collection-123"
newFile.Title = "Test document"
newFile.Summary = "This is a test document"
newFile.Name = "c:\My Documents\test.doc"
status = newFile.DSUpload
To update the contents of a file:

1. Create an IItemObj file object representing the file item to update.

2. Set the handle property.
3. Locate the updated local copy of the file.
4. Call IItemObj.DSUpload against the local copy.
You can use DSUpload for a collection object as well. This is useful when uploading all files contained in a
folder on your PC. The DSUpload creates a new collection in the parent collection you specified in the
collection object and uploads all files including nested sub-folders and sub-folder contents to the new
collection. On return, the Handle parameter of the new collection object holds the DocuShare handle of the
created collection. DSUpload can also generate an enumerator for the items (files and nested collections)
that are created in the target collection. The enumerator can be used to count the uploaded files and
collections using the standard enumeration technique.

DocuShare Windows Client SDK 2–19

Updating a DocuShare file SDK Programming

Here is an example of copying all files in the local folder, My Documents, to a new collection in DocuShare.

dim newCollection
set newCollection = server.CreateObject("Collection")
newCollection.ParentHandle = "Collection-123"
newCollection.Title = "Copy of My Documents"
newCollection.Name = "c:\My Documents"
status = newCollection.DSUpload

NOTE: The parent collection must be specified for the upload call to succeed. The new collection is
created under this collection.

To find all items created by DSUpload, use the DSAXES_MODE_CREATERESULTENUM flag. For
example, change the above script and enumerate the uploaded items.

dim newCollection
set newCollection = server.CreateObject("Collection")
newCollection.ParentHandle = "Collection-123"
newCollection.Title = "Copy of My Documents"
newCollection.Name = "c:\My Documents"
newCollection.DSGatewayMode = DSAXES_MODE_CREATERESULTENUM
status = newCollection.DSUpload
if status = 0 then
dim uploadedList
set uploadedList = collObj.EnumObjects(DSCONTF_CHILDREN)
uploadedList.Reset
Print "Number of items created: " +CStr(uploadedList.Length)
i = 1
while uploadedList.NextPos <> 0
dim uploadedItem
set uploadedItem = uploadedList.NextItem
Print "Uploaded Item #"+CStr(i) + ": " + uploadedItem.Handle + " in
Server-" + CStr(uploadedItem.DSServerMapId)
i = i + 1
wend
end if
The item objects that are obtainable from the result enumerator have only the Handle and DSServerMapId
properties set to valid values. No other properties contain valid values. Follow the NextItem assignment
with a call to DSLoadProps to obtain any other properties.

2–20 DocuShare Windows Client SDK

SDK Programming Updating a DocuShare file

The order of the result items corresponds to the order of item creation. The target collection is created first.
Therefore, the first item object that the enumerator yields describes the target collection. The second item
object describes the first file or sub-collection that was created in the target collection.

Suppose you want to copy a certain kind of file, for example, files created by MS Word. Instead of setting
the Name property to the path of the container folder, you set it to a file filter pattern such as c:\My
Documents\*.doc. At this time, the collection object representing the pattern-matched files must be
assigned with a valid, existing DocuShare collection handle. Assuming that Collection-123 exists in the
server, the above code is changed to the following:

dim collection
set collection = server.CreateObject("Collection-123")
collection.Name = "c:\My Documents\*.doc"
status = collection.DSUpload
If you know in advance, the multiple files by name (path) instead of supplying a file pattern, you supply a
list of file paths.

dim collection
set collection = server.CreateObject("Collection-123")
collection.Name = ""c:\My Documents\test1.doc" "c:\My Documents\test2.doc""
status = collection.DSUpload
In summary, a file object is used to update or create a single file item in DocuShare. A collection object is
used to update or create multiple files as well as the container collection.

2.6.1 Moving, copying and deleting an item

If you know the item by its DocuShare handle, you can call DSMove, DSCopy, or DSDelete directly. This
example moves a file from its current parent container (Collection-456) to another collection.

dim file
set file = server.CreateObject("File-123")
file.ParentHandle = "Collection-456"
status = file.DSMove(destCollection)
On a successful return, the file object's Parent property is changed to the DocuShare handle of the
destCollection.

NOTE: The example assumes there is a valid collection object called destCollection (representing an
existing DocuShare collection).

The object, destCollection, can be generated manually by a call to IServer.CreateObject or generated

automatically by the collection enumeration.

DocuShare Windows Client SDK 2–21

Updating a DocuShare file SDK Programming

The copying of an item is similar. Instead of using DSMove, you use DSCopy.

dim file
set file = server.CreateObject("File-123")
file.ParentHandle = "Collection-456"
status = file.DSCopy(destCollection)
The copy operation does not replace the Parent handle. The new parent, destCollection, is added to the
list of parents that the item object holds internally. By obtaining a parents enumerator, you can rediscover
all parents related to the item. Refer to the discussion on multiple parents below.

DSCopy, by default, copies the item's reference to the target collection. To make a physical copy of the
item, set the DSAXES_MODE_COPYCONTENTS flag before calling DSCopy. For example, the script
below copies the item's contents and properties.

dim file
set file = server.CreateObject("File-123")
file.DSGatewayMode = file.DSGatewayMode Or DSAXES_MODE_COPYCONTENTS
status = file.DSCopy(targColl)

NOTE: In the copy contents mode, DSCopy works only for file and collection. DSCopy replicates the
contents and standard properities of source items. It does not replicate custom properties.

When replicating contents, you can use the DSAXES_MODE_CREATERESULTENUM flag to instruct
DSCopy to generate an item enumerator for the original source items and copied target items.

srcColl.DSGatewayMode = srcColl.DSGatewayMode Or DSAXES_MODE_COPYCONTENTS Or

DSAXES_MODE_CREATERESULTENUM
status = srcColl.DSCopy(targColl)
if status = 0 then
dim copiedList
set copiedList = srcColl.EnumObjects(DSCONTF_CHILDREN)
copiedList.Reset
Print "Total of "+CStr(copiedList.Length/2)+" were copied"i = 1
while copiedList.NextPos <> 0
dim srcItem
set srcItem = copiedList.NextItem
Print "Copied Source Item #" + CStr(i) + ": " + srcItem.Handle + " in
Server-" + CStr(srcItem.DSServerMapId)
i = i + 1
dim targItem
set targItem = copiedList.NextItem
Print "Copied Target Item #" + CStr(i) + ": " + targItem.Handle + " in
Server-" + CStr(targItem.DSServerMapId)
i = i + 1

2–22 DocuShare Windows Client SDK

SDK Programming Updating a DocuShare file

wend
end if
When enumerating the result items, note that the copied item in the source collection and the created item
in the target collection appear in pairs. The first item object pair refers to the first original item in the source
collection and the first copied item in the target collection. The second pair refers to the second original
and copy, and so on. The total number of copied items is obtained by dividing the Length property of the
enumerator by two. Also, note that if the target collection is in a different server, the copied item's
DSServerMapId is different from the original item's DSServerMapId. The copied item's DSServerMapId
refers to the target server.

The deletion of an item is similar except that no destination collection is needed.

dim file
set file = server.CreateObject("File-123")
file.ParentHandle = "Collection-456"
status = file.DSDelete
There is a complication when the item is parented by multiple collections. In such a case, DSDelete
executes a disown operation instead of permanent deletion. The disown operation involves removing a
primary parent, IItemObj.Parent, from the parents list. The result is that the item still exists in DocuShare,
but the item no longer appears in the collection corresponding to the removed parent. The rest of the
parents continue to list the item. Permanent deletion happens if the item object contains a single parent. If
DocuShare actually has multiple parents assigned to a particular item, and you did not account for the
mulitplicity in your IItemObj representation of the item, calling DSDelete will perform a permanent deletion.
If you are not sure about the accuracy of the parent list, you should use DSLoadProps before calling
DSDelete to resynchronize the parents list. If the item is obtained automatically from a collection
enumeration, the item object already has an up-to-date parent list, and a call to DSLoadProps is not
needed.

As an example, modify the example to account for the possibility of having multiple parents.

dim file
set file = server.CreateObject("File-123")
status = file.DSLoadProps
status = file.DSDelete

DocuShare Windows Client SDK 2–23

Creating a new user SDK Programming

2.7 Creating a new user

Creating a user is the same as creating any item.

• Create an IItemObj representation from an IServer object

• Set relevant IItemObj properties
• Call IItemObj.DSCreate
There are minor differences. Unlike the media types, the user type takes unique properties such as
password and email. These special properties are not defined explicitly by the IItemObj interface.
Therefore, the custom property mechanism of IItemObj is used to hold and pass the values of the special
properties. Also, you need to connect to the server without requiring authentication. You cannot login
unless you have an user account.

To open a server session without authentication, enable the optional IServer setting which controls
IServer's authentication behavior upon user login. When enabled, the optional setting causes the login
management to skip the normal authentication step and open a gateway to the server immediately. The
setting must be selected before DSCreate is called.

server.Options = SVRMAP_OPTION_OPENWITHOUTAUTH
set user = server.CreateObject("User")
user.Name = "joecool"
user.CustomProp("password", 1) = "coolguy"
user.CustomProp("first_name", 1) = "Joe"
user.CustomProp("last_name", 1) = "Cool"
user.CustomProp("email", 1) = "joecool@my.docushare.com"
status = user.DSCreate

NOTE: Except for the Name property which holds the username, IItemObj's custom property is used
to assign the rest of the required user properties.

2–24 DocuShare Windows Client SDK

SDK Programming Running a selection dialog

2.8 Running a selection dialog

The IItemObj interface defines the DSSelect method that runs a browse dialog to enable a user to select a
DocuShare item. The selected item is loaded into the item object. If the DocuShare Windows Client is
installed, the method uses the shell namespace extension library of the Client to realize the browse dialog.
If the DocuShare Client is not installed, the method uses a default browse dialog of a simpler user
interface.

The ItemObj object must be one that is derived from a globally mapped Server object. This means that the
mapped server appears in the DocuShare folder in Windows Explorer, or that the server was mapped
programmatically based on calls to Store methods using DSClient SDK methods. This method may not
work correctly if you created the ItemObj object from a stand-alone Server object.

The DSSelect method can run a folder browse dialog for selecting a collection, a file browse dialog for
selecting a file or other non-container items. The dialog method used depends on the media type of the
item object. If the item object is a collection, DSSelect runs a folder browse dialog; otherwise, the method
runs the file browse dialog.

The following example creates an empty collection object, runs a browse dialog, and opens the selected
collection.

dim collection
set collection = server.CreateObject("Collection")
status = collection.DSSelect(0)
if status = 0 then
status = collection.DSLoadChildren
...
end if
For a collection object, the flags parameter of DSSelect is not used and should be set to zero. Because the
calling collection object belongs to a particular server, the example above displays collections for this
server only. Note that the server object is opened from the DocuShare Client server map database. Refer
to Chapter 4, DSServerMap Library for more information on opening an existing server object from a
server store.

If the originating server object did not perform a user authentication, a login dialog will run as soon as the
user attempts to open a collection. If your application needs to control the authentication process, make
sure you perform the authentication before calling DSSelect.

To display all existing server objects of the DocuShare Client, use a collection object not associated with a
server object.

dim collection
set collection = CreateObject("DSITEMENUMLib.ItemObj")
collection.Handle = "Collection"
collection.LocalProp("Caption", "DSSelect") = "Select a collection folder"
status = collection.DSSelect(0)
if status = 0 then
status = collection.DSLoadChildren
...

DocuShare Windows Client SDK 2–25

Running a selection dialog SDK Programming

end if
When this code is run, the user will see all the DocuShare Client server folders and be able to expand and
view any of the listed servers (provided that the user is authenticated). Also, the IItemObj-specific local
property, DSSelect Caption, is set as a caption string. The caption is shown in the browse dialog to provide
a short description.

In the above example, the collection object loaded properties of the selected collection, including the
server map association. Because of the server association, the subsequent DSLoadProps call,
successfully contacts DocuShare and completes the property query.

The next example selects a collection in a pre-selected server and creates an empty MS Word file.

dim collObj
set collObj = server.CreateObject("Collection")
collObj.LocalProp("Caption", "DSSelect") =
"Select a collection to create a new file"
status = collObj.DSSelect(0)
if status = 0 then
dim fileObj
set fileObj = collObj.CreateObject("File")
fileObj.Title = InputBox( "Enter Title","Create Docushare file 1/2", "New
File" )
fileObj.MimeType = InputBox( "Enter Mime Type","Create Docushare file 2/2",
"application/msword" )
status = fileObj.DSCreate
...
end if
To run a browse dialog for selecting a file, use a file object. The next example runs a file browse dialog and
lists the available versions of the selected file. It uses ITEMOBJ_SELFLAG_READONLY to disallow
selection of the Lock option in the browse dialog. Locking a file is not necessary when showing version
history.

dim file
set file = CreateObject("DSITEMENUMLib.ItemObj")
file.Handle = "File"
file.LocalProp("Caption", "DSSelect") = "Select Document For Version History"
status = file.DSSelect(ITEMOBJ_SELFLAG_READONLY)
if status = 0 then
status = file.DSLoadChildren
dim versions
set versions = file.EnumObjects(0)
versions.Reset
while versions.NextPos <> 0
dim version

2–26 DocuShare Windows Client SDK

SDK Programming Running a selection dialog

set version = versions.NextItem

Print "Version " + CStr(version.VersionNum) + " " + version.User
wend
end if
The scope of file browsing is not limited to a single server. To limit browsing to a single server, create the
file object using IServer.CreateObject. If you set the Parent file property to a valid collection, DSSelect
limits browsing to that collection and the collection's descendant collections. To permit browsing outside
the selected server or collection, set the DSSelect flags paramter to:

ITEMOBJ_SELFLAG_NAVFREE
If the user checks the Lock option in the dialog, the IItemObj.IsReadOnly file object property is set to False.
Your application should take this as an indicator for locking the file. The example warns the user if the
option was not selected. The DSEdit call, if necessary, locks the file and opens the file using an associated
editor program. DSEdit delegates the edit task to the file monitor services of the DocuShare Client. Once
this is done, the file item belongs to DocuShare Client. The delegating application should not perform any
modifying operation on the file item, such as calling DSUpload. Once the user finishes editing the file,
DocuShare Client saves the updated contents to DocuShare.

Another way to provide document edit support is to use an OLE automation server of an associated editor.
MS Word, for instance, supplies such an object. You can use the automation object to programmatically
open the downloaded file and present the contents to the end user for editing purposes. When the editor
object terminates, or when your event handler handles a file update event fired by the editor, use
DSUpload to update the file item in DocuShare.

So far, DSSelect has been used to open an item. If you want to use DSSelect to run a Save as dialog, use
the ITEMOBJ_SELFLAG_SAVE flag for the DSSelect call. Here is an example that browses for a
collection and saves a file.

dim file
set file = CreateObject("DSITEMENUMLib.ItemObj")
file.Handle = "File"
file.LocalProp("Caption", "DSSelect") = "Save File"
status = file.DSSelect(ITEMOBJ_SELFLAG_SAVE)
if status = 0 then
...
file.Name = "c:\My Documents\proposal.doc"
status = file.DSUpload
end if
The DSSelect method can be used to browse for a non-file item. Here is an example that selects a URL
item and navigates to the referenced URL.

dim urlObj
set urlObj = CreateObject("DSITEMENUMLib.ItemObj")
urlObj.Handle = "URL"
urlObj.LocalProp("Caption", "DSSelect") = "Select URL Object"
status = urlObj.DSSelect( ITEMOBJ_SELFLAG_NONFILE or

DocuShare Windows Client SDK 2–27

Running a selection dialog SDK Programming

ITEMOBJ_SELFLAG_READONLY )
if status = 0 then
status = urlObj.DSLoadProps
if status = 0 then
dim webBrowser
set webBrowser = CreateObject("DSServerMap.Browser")
status = webBrowser.NavigateTo(urlObj.URL, "", "")
end if
end if
In the example, ITEMOBJ_SELFLAG_NONFILE allows selection of a non-file item and
ITEMOBJ_SELFLAG_READONLY disallows selection of the Lock option in the browse dialog. Note that
URL navigation was achieved using the IBrowser helper function of the SDK server map library.

The following example uses the file and folder browse dialogs to choose the source file and destination
collection.

dim file
set file = CreateObject("DSITEMENUMLib.ItemObj")
file.Handle = "File"
file.LocalProp("Caption", "DSSelect") = "Select File To Copy"
status = file.DSSelect(ITEMOBJ_SELFLAG_READONLY)
if status = 0 then
dim coll
set coll = CreateObject("DSITEMENUMLib.ItemObj")
coll.Handle = "Collection"
coll.LocalProp("Caption", "DSSelect") = "Select Target Collection"
status = coll.DSSelect(0)
if status = 0 then
status = file.DSCopy(collObj)
end if
end if
By using a similar scheme and a file system object provided by Visual Basic, you can also write a user-
driven script that interacts with the file system of the client machine.

2–28 DocuShare Windows Client SDK

SDK Programming Managing multiple DocuShare objects

2.9 Managing multiple DocuShare objects

Some DocuShare items appear in multiple collections. In an earlier section, you saw that a multi-parented
item needs extra care. For example, a delete call may perform a disown or delete operation depending on
the parents list. This section describes how parents of an item are discovered and utilized.

To list the parents of a DocuShare file, enter DSLoadProps (in the example, File-123, has more than one
parent).

dim file
set file = server.CreateObject("File-123")
status = file.DSLoadProps
At this point, the file object holds an up-to-date parents list. To enumerate the parents, obtain an
enumerator from the file object.

dim parentList
set parentList = file.EnumObjects(DSCONTF_PARENT)
parentList.Reset
Now, we can walk the list.

while parentList.NextPos <> 0

dim parent
set parent = parentList.NextItem
' do whatever task you want to do here
...
wend
A parent item object generated this way holds a limited set of valid properties. They are IItemObj.Title and
IItemObj.Handle. All other IItemObj properties are undefined. To find the complete properties of a parent
item, execute DSLoadProps against the parent object.

At times, your application requires creating a list of parents and attaching it to a manually created item
object. The following example shows how this is achieved.

dim parentList
set parentList =
server.CreateObject("DSITEMENUMLib.EnumObj")
dim coll1, coll2, coll3
set coll1 = server.CreateObject("Collection-123")
set coll2 = server.CreateObject("Collection-124")
set coll3 = server.CreateObject("Collection-125")
parentList.Attach(coll1)
parentList.Attach(coll2)
parentList.Attach(coll3)

DocuShare Windows Client SDK 2–29

Managing multiple DocuShare objects SDK Programming

dim file
set file = server.CreateObject("File-123")
file.AttachParents(parentList)
The AttachParents call, internalizes the new parents list in the file object.

2–30 DocuShare Windows Client SDK

SDK Programming Log into a DocuShare server

2.10 Log into a DocuShare server

The following examples assumes the following declarations within the General.Declaration section of the
Visual Basic code.

Option Explicit
' Constants
' DsServerMap Constants
Const SVRMAP_RESULT_SUCCESS = 0
Const SVRMAP_RESULT_CANCEL = 2
Const SVRMAP_SELDLGFLAG_SINGLESEL = &H1
Dim objServer as Object
Dim objStore as Object

2.10.1 Login Examples

• Simple server login on page 2–31
• A set address login on page 2–32
• Set username and server address on page 2–32
• Automatic login on page 2–33
• Select and log into server on page 2–34

2.10.1.1 Simple server login

This example is the simplest procedure to log into a DocuShare server. It prompts the user for a server http
address, username, and password.

Sub SimpleLogon()
' Create a Server object
Set objServer = CreateObject("DsServerMap.Server")
' Perform logon
Dim lResult As Long
lResult = objServer.Logon
' Test logon success
Select Case lResult
Case SVRMAP_RESULT_SUCCESS
MsgBox "Simple Logon successful."
Case SVRMAP_RESULT_CANCEL
MsgBox "Simple Logon canceled by user."
Case Else
MsgBox "Simple Logon failed with result: " + CStr(lResult)
End Select
End Sub

DocuShare Windows Client SDK 2–31

Log into a DocuShare server SDK Programming

2.10.1.2 A set address login

For applications that need to restrict login to a single server, the following example demonstrates how to
preset the server address before invoking the login dialog.

Sub SetAddressLogon()
' Create a Server object
Set objServer = CreateObject("DsServerMap.Server")
' Preset the DocuShare server address
objServer.DocuShareAddress = "http://my.docushare.com/"
' Ensure you enter a valid server address for you site above
' Perform logon
Dim lResult As Long
lResult = objServer.Logon
' Test logon success
Select Case lResult
Case SVRMAP_RESULT_SUCCESS
MsgBox "Set Address Logon successful."
Case SVRMAP_RESULT_CANCEL
MsgBox "Set Address Logon canceled by user."
Case Else
MsgBox "Set Address Logon failed with result: " + CStr(lResult)
End Select
End Sub

2.10.1.3 Set username and server address

There are instances where a developer wishes to limit not only the server that needs to be logged into, but
the username as well.

Sub SetNameAndAddressLogon()
' Create a Server object
Set objServer = CreateObject("DsServerMap.Server")
' Preset the user name and DocuShare server address
objServer.UserName = "AUserName"
objServer.DocuShareAddress = "http://my.docushare.com/"
' Ensure you enter a valid user name and
' server address for you site above
' Perform logon
Dim lResult As Long
lResult = objServer.Logon
' Test logon success

2–32 DocuShare Windows Client SDK

SDK Programming Log into a DocuShare server

Select Case lResult

Case SVRMAP_RESULT_SUCCESS
MsgBox "Set Name and Address Logon successful."
Case SVRMAP_RESULT_CANCEL
MsgBox "Set Name and Address Logon canceled by user."
Case Else
MsgBox "Set Name and Address Logon failed with result: " + CStr(lResult)
End Select
End Sub

2.10.1.4 Automatic login

For the application that requires an automatic login method.

Sub AutoLogon()
' Create a Server object
Set objServer = CreateObject("DsServerMap.Server")
' Preset the user name, password and DocuShare server address
objServer.UserName = "AUserName"
objServer.Password = "APassword"
objServer.DocuShareAddress = "http://my.docushare.com/"
' Ensure you enter a valid user name, password and
' server address for you site above
' Perform logon
Dim lResult As Long
lResult = objServer.Logon
' Test logon success
Select Case lResult
Case SVRMAP_RESULT_SUCCESS
MsgBox "Auto Logon successful."
Case Else
MsgBox "Auto Logon failed with result: " + CStr(lResult)
End Select
End Sub

DocuShare Windows Client SDK 2–33

Log into a DocuShare server SDK Programming

2.10.1.5 Select and log into server

To allow a user to select from a list of servers, use a Store object. This example utilizes the default Store
object which is created by the DocuShare Windows Client environment. To create a custom Store object
refer to Managing server connections on page 2–71.

' This subroutine selects and then logs in a selected server

Sub SelectAndLogon()
If SelectServer Then
' Perform Logon
Dim lResult As Long
lResult = objServer.Logon
' Test logon success
Select Case lResult
Case SVRMAP_RESULT_SUCCESS
MsgBox "Simple Logon successful."
Case SVRMAP_RESULT_CANCEL
MsgBox "Simple Logon canceled by user."
Cse Else
MsgBox "Simple Logon failed with result: " + CStr(lResult)
End Select
End If
End Sub
' This function is used to make a single server selection
Function SelectServer() As Boolean
' First we load the default Store object from which
' to make our server selection
Set objStore = CreateObject("DsServerMap.Store")
Dim lResult As Long
lResult = objStore.Load
If lResult = SVRMAP_RESULT_SUCCESS Then
' Now we can select a server
Dim strTitle As String, strDesc As String
strTitle = "Select and Logon"
strDesc = "Select a server to logon."
Dim lFlag As Long
lFlag = SVRMAP_SELDLGFLAG_SINGLESEL ' Allow only a single selection
lResult = objStore.DoSelectDialog(0, strTitle, strDesc, "", 0, lFlag)
Select Case lResult
Case SVRMAP_RESULT_SUCCESS

2–34 DocuShare Windows Client SDK

SDK Programming Log into a DocuShare server

' Ok, now iterate through the servers

' and find the selected one
objStore.Reset ' Set to first server
Dim TempServer
While 0 <> objStore.NextPos
Set TempServer = objStore.NextItem
If TempServer.IsSelected = 1 Then
Set objServer = TempServer ' Return the selected server
SelectServer = True
Exit Function
End If
Wend
MsgBox "Selected server never found"
SelectServer = False
Case SVRMAP_RESULT_CANCEL
SelectServer = False
Case Else
MsgBox "Server select failed with result: " + CStr(lResult)
SelectServer = False
End Select
Else
' Error occurred in objStore.Load
MsgBox "Store object load failed with result: " + CStr(lResult)
SelectServer = False
Exit Function
End If
End Function

DocuShare Windows Client SDK 2–35

Navigating a DocuShare server SDK Programming

2.11 Navigating a DocuShare server

The following examples assumes the following declaration within the General.Declaration section of the
Visual Basic code.

Option Explicit
' IItemObj and IEnumObj Constants
Const DSAXES_SUCCESS = 0
Const DSAXES_E_CANCEL = -1
Const DSAXES_NOITEMS = 259
Const DSCONTF_FOLDERS = &H2
Const DSCONTF_DOCUMENTS = &H4
Const DSCONTF_NONDOCUMENTS = &H8
Const DSCONTF_CHILDREN = (DSCONTF_FOLDERS Or DSCONTF_DOCUMENTS Or
DSCONTF_NONDOCUMENTS)
Const DSXITEMTYPE_COLLECTION = 2
Const DSXITEMTYPE_DOCUMENT = 3
Dim objServer As Object
Dim lstDisplay As Object
The objServer object is assumed to be valid and logged in. To instantiate a valid objServer refer to Log into
a DocuShare server on page 2–31.

For navigation display, the code assumes that VB Form exists with a list object named lstDisplay. This list
object is referenced throughout the sample code.

Navigation Examples:

• Server Root Collection on page 2–37

• Listing a Child Collection from a Parent Collection on page 2–38
• Listing File Versions on page 2–40
• Selecting a Collection from Server List on page 2–41
• Selecting a File from Server List on page 2–42
• Get a Collection by HandleNum on page 2–44
• Get a File by HandleNum on page 2–45

2–36 DocuShare Windows Client SDK

SDK Programming Navigating a DocuShare server

2.11.1 Server Root Collection

This example demonstrates how to get a handle to a DocuShare server root object.

' This subroutine will display the root collection

' of a DocuShare server
Sub DisplayServerRoot()
' To begin, we need to get get an Item handle to
' the server object.
Dim objRootItem as Object
Set objRootItem = objServer.CreateObject("Server")
' Next, we need to load the children items of
' the root directory from the server
Dim lResult As Long
lResult = objRootItem.DSLoadChildren
If lResult <> DSAXES_SUCCESS Then
MsgBox "objServerRoot.DSLoadChildren failed with result: " + CStr(lResult)
Exit Sub
End If
' To enumerate all of the roots children, we need to create
' the appropriate enumerator
Dim objRootEnum As Object
Set objRootEnum = objRootItem.EnumObjects(DSCONTF_CHILDREN)
' Now we enumerate through the children and list them by name
Dim objChildItem As Object
objRootEnum.Reset
While 0 <> objRootEnum.NextPos
Set objChildItem = objRootEnum.NextItem
Dim strTitle As String
strTitle = objChildItem.Title
lstDisplay.AddItem strTitle
Wend
End Sub

DocuShare Windows Client SDK 2–37

Navigating a DocuShare server SDK Programming

2.11.2 Listing a Child Collection from a Parent Collection

The following example is composed of two functions:

• DisplayCollection—displays the contents of a server root collection and determines which objects
are Collections and then passes them to the subroutine ListChildCollection.
• ListChildCollection—lists the contents of the server root collection.
' This subroutine will display a listing collection
' of a DocuShare server
Sub DisplayRootCollection()
' To begin, we need to get an Item handle to
' the server object.
Dim objRootItem As Object
Set objRootItem = objServer.CreateObject("Server")
' Next, we need to load the children items of
' the root directory from the server
Dim lResult As Long
lResult = objRootItem.DSLoadChildren
If lResult <> DSAXES_SUCCESS Then
MsgBox "objRootItem.DSLoadChildren failed with result: " + CStr(lResult)
Exit Sub
End If
' To enumerate all of the roots children, we need to create
' the appropriate enumerator
Dim objRootEnum As Object
Set objRootEnum = objRootItem.EnumObjects(DSCONTF_CHILDREN)
' Now we enumerate through the children and list them by name
Dim objChildItem As Object
objRootEnum.Reset
While 0 <> objRootEnum.NextPos
Set objChildItem = objRootEnum.NextItem
Dim strTitle As String
strTitle = objChildItem.Title
lstDisplay.AddItem strTitle
' Let's display the contents for all items that are collections
If DSXITEMTYPE_COLLECTION = objChildItem.TypeNum Then
ListChildCollection objChildItem
End If
Wend
MsgBox "Finished displaying child collections"

2–38 DocuShare Windows Client SDK

SDK Programming Navigating a DocuShare server

End Sub
' List the child collection of the root
Private Sub ListChildCollection(ByRef objChildCollection As Object)
Dim lResult As Long
lResult = objChildCollection.DSLoadChildren
If DSAXES_SUCCESS <> lResult Then
If DSAXES_NOITEMS = lResult Then
lstDisplay.AddItem objChildCollection.Title + " has no children items."
Else
MsgBox "Failed objChildCollection.DSLoadChildren. Failure = " +
CStr(lResult)
End If
Exit Sub
End If
Dim objChildEnum As Object
Set objChildEnum = objChildCollection.EnumObjects(DSCONTF_CHILDREN)
Dim objChildItem As Object
objChildEnum.Reset
While 0 <> objChildEnum.NextPos
Set objChildItem = objChildEnum.NextItem
Dim strTitle As String
strTitle = objChildCollection.Title + " - " + objChildItem.Title
lstDisplay.AddItem strTitle
Wend
End Sub

DocuShare Windows Client SDK 2–39

Navigating a DocuShare server SDK Programming

2.11.3 Listing File Versions

The following example is composed of two functions:

• SelectFileAndListVersions—allows the user to select a file.

• ListVersions—lists the selected file versions.
' Select and list versions of a file
Public Sub SelectFileAndListVersions()
' Create a ItemObj to utilize in file selection
Dim objFileItem As Object
Set objFileItem = CreateObject("DSITEMENUMLib.ItemObj")
' Set the objFileItem properties to select file
objFileItem.Handle = "File"
objFileItem.LocalProp("Caption", "DSSelect") = "Select a file"
' Now we can instantiate the selection dialog
Dim lResult As Long
lResult = objFileItem.DSSelect(0)
Select Case lResult
Case DSAXES_SUCCESS
ListVersions objFileItem
Case DSAXES_E_CANCEL
' User canceled selection
Case Else
MsgBox "objFileItem.DSSelect failed with result: " + CStr(lResult)
End Select
End Sub
' List the versions of a file
Private Sub ListVersions(ByRef objFile As Object)
Dim lResult
lResult = objFile.DSLoadChildren
If DSAXES_SUCCESS <> lResult Then
MsgBox "Failed objChildCollection.DSLoadChildren. Failure = " +
CStr(lResult)
Exit Sub
End If
Dim objVersionEnum As Object
Set objVersionEnum = objFile.EnumObjects(0)
Dim objVersion As Object
objVersionEnum.Reset
While 0 <> objVersionEnum.NextPos

2–40 DocuShare Windows Client SDK

SDK Programming Navigating a DocuShare server

Set objVersion = objVersionEnum.NextItem

Dim strTitle As String
strTitle = objFile.Title + " - Version " + CStr(objVersion.VersionNum)
lstDisplay.AddItem strTitle
Wend
End Sub

2.11.4 Selecting a Collection from Server List

The following example demonstrates how to select a single collection from the default DocuShare Client
Store. The user is presented with a selection of the currently mapped servers. This example calls the
function, ListChildCollection, which is shown in Listing a Child Collection from a Parent Collection on page
2–38 .

' Select and list a collection

Public Sub SelectAndListCollection()
' Create a ItemObj to utilize in collection selection
Dim objCollectionItem As Object
Set objCollectionItem = CreateObject("DSITEMENUMLib.ItemObj")
' Set the objCollectionItem properties to select collection
objCollectionItem.Handle = "Collection"
objCollectionItem.LocalProp("Caption", "DSSelect") = "Select a collection
folder"
' Now we can instantiate the selection dialog
Dim lResult As Long
lResult = objCollectionItem.DSSelect(0)
Select Case lResult
Case DSAXES_SUCCESS
ListChildCollection objCollectionItem
Case DSAXES_E_CANCEL
' User canceled selection
Case Else
MsgBox "objCollectionItem.DSSelect failed with result: " + CStr(lResult)
End Select
End Sub

DocuShare Windows Client SDK 2–41

Navigating a DocuShare server SDK Programming

2.11.5 Selecting a File from Server List

The following example demonstrates how to select a single file from the default DocuShare Client Store.
The user is presented with a selection of the currently mapped servers and then calls a display function to
list the properties of the file object.

' Select and list properties of a file

Public Sub SelectAndListFile()
' Create a ItemObj to utilize in file selection
Dim objFileItem As Object
Set objFileItem = CreateObject("DSITEMENUMLib.ItemObj")
' Set the objFileItem properties to select file
objFileItem.Handle = "File"
objFileItem.LocalProp("Caption", "DSSelect") = "Select a file"
' Now we can instantiate the selection dialog
Dim lResult As Long
lResult = objFileItem.DSSelect(0)
Select Case lResult
Case DSAXES_SUCCESS
ListItemProperties objFileItem
Case DSAXES_E_CANCEL
' User canceled selection
Case Else
MsgBox "objFileItem.DSSelect failed with result: " + CStr(lResult)
End Select
End Sub
' List a item properties
Private Sub ListItemProperties(ByRef objItem As Object)
lstDisplay.AddItem "***Item Obj Properties List: "
lstDisplay.AddItem "Abstract: " + objItem.Abstract
lstDisplay.AddItem "Author: " + objItem.Author
lstDisplay.AddItem "AutoDelete: " + CStr(objItem.AutoDelete)
lstDisplay.AddItem "BackgroundImage: " + objItem.BackgroundImage
lstDisplay.AddItem "Comment: " + objItem.Comment
lstDisplay.AddItem "Description: " + objItem.Description
lstDisplay.AddItem "DSErrorCode: " + CStr(objItem.DSErrorCode)
lstDisplay.AddItem "DSServerMapId: " + CStr(objItem.DSServerMapId)
lstDisplay.AddItem "ExcludedCoreProps: " + CStr(objItem.ExcludedCoreProps)
lstDisplay.AddItem "ExcludedProps: " + CStr(objItem.ExcludedProps)
lstDisplay.AddItem "Handle: " + objItem.Handle

2–42 DocuShare Windows Client SDK

SDK Programming Navigating a DocuShare server

lstDisplay.AddItem "HandleNum: " + CStr(objItem.HandleNum)

lstDisplay.AddItem "IsLocked: " + CStr(objItem.IsLocked)
lstDisplay.AddItem "IsReadOnly: " + CStr(objItem.IsReadOnly)
lstDisplay.AddItem "Keywords: " + objItem.Keywords
lstDisplay.AddItem "Length: " + CStr(objItem.Length)
lstDisplay.AddItem "Logo: " + objItem.Logo
lstDisplay.AddItem "MaxVersions: " + CStr(objItem.MaxVersions)
lstDisplay.AddItem "MimeType: " + objItem.MimeType
lstDisplay.AddItem "Name: " + objItem.Name
lstDisplay.AddItem "Owner: " + objItem.Owner
lstDisplay.AddItem "OwnerNum: " + CStr(objItem.OwnerNum)
lstDisplay.AddItem "Parent: " + CStr(objItem.Parent)
lstDisplay.AddItem "ParentCount: " + CStr(objItem.ParentCount)
lstDisplay.AddItem "Reload: " + CStr(objItem.Reload)
lstDisplay.AddItem "SortOrder: " + objItem.SortOrder
lstDisplay.AddItem "Summary: " + objItem.Summary
lstDisplay.AddItem "TimeAccessed: " + CStr(objItem.TimeAccessed)
lstDisplay.AddItem "TimeCreated: " + CStr(objItem.TimeCreated)
lstDisplay.AddItem "TimeModified: " + CStr(objItem.TimeModified)
lstDisplay.AddItem "Title: " + objItem.Title
lstDisplay.AddItem "TypeNum: " + CStr(objItem.TypeNum)
lstDisplay.AddItem "URL: " + objItem.URL
lstDisplay.AddItem "User: " + objItem.User
lstDisplay.AddItem "UserNum: " + CStr(objItem.UserNum)
lstDisplay.AddItem "VersionNum: " + CStr(objItem.VersionNum)
End Sub

DocuShare Windows Client SDK 2–43

Navigating a DocuShare server SDK Programming

2.11.6 Get a Collection by HandleNum

This example demonstrates how to get an ItemObj handle to a collection from a specific server. ItemObj
can be utilized to perform collection listing as well as to manipulate the various properties of the collection.
This example lists the properties of the collection with the ListItemProperties function defined in Selecting a
File from Server List on page 2–42.

' Get a specific collection from a server

Public Sub GetCollectionFromHandle()
' To begin, we need to get a item handle to
' the server object
Dim objCollectionItem As Object
Set objCollectionItem = objServer.CreateObject("Collection-10")
' Now we need to get the collections properties
Dim lResult As Long
lResult = objCollectionItem.DSLoadProps
If lResult <> DSAXES_SUCCESS Then
MsgBox "objCollectionItem.LoadProps failed with result: " + CStr(lResult)
Exit Sub
End If
' Now we list the collection's properties
ListItemProperties objCollectionItem
End Sub

2–44 DocuShare Windows Client SDK

SDK Programming Navigating a DocuShare server

2.11.7 Get a File by HandleNum

This example demonstrates how to get an ItemObj handle to a file from a specific server. The created
ItemObj can be utilized to perform file management. This example lists the properties of the collection with
the ListItemProperties function defined in Selecting a File from Server List on page 2–42.

' Get a specific collection from a server

Public Sub GetFileFromHandle()
' To begin, we need to get a item handle to
' the server object
Dim objFileItem As Object
Set objFileItem = objServer.CreateObject("File-12")
' Now we need to get the collections properties
Dim lResult As Long
lResult = objFileItem.DSLoadProps
If lResult <> DSAXES_SUCCESS Then
MsgBox "objFileItem.LoadProps failed with result: " + CStr(lResult)
Exit Sub
End If
' Now we list the collection's properties
ListItemProperties objFileItem
End Sub

DocuShare Windows Client SDK 2–45

Working with properties SDK Programming

2.12 Working with properties

The IItemObj interface defines methods for accessing DocuShare resources and methods which are not
related to actual DocuShare resources. This section briefly describes these methods. Also described are
some of the IItemObj properties that require special attention for their usage.

2.12.1 IItemObj methods and properties

To look at the IItemObj interface, you can refer to Table 2–2 which shows the correspondence between the
IItemObj methods and item types. The methods in this section relate to the methods in the last three rows
of this table.

The methods refer to the item object association with external-COM interfaces to Gateway and Server map
objects that are attached to an item object for carrying out DocuShare commands. For example, the
DSUpload method needs to utilize either the Gateway or Server map object to connect to DocuShare and
process a specific command, such as uploading a file and retrieving the generated DocuShare handle.
When you create an IItemObj object using IServer.CreateObject or IItemObj.CreateObject, one of the
interface attach methods is called behind the scene.

dim itemObj
set itemObj = server.CreateObject("xxx-123")
This statement is functionally equivalent to:

dim itemObj
set itemObj = CreateObject("DSITEMENUMLib.ItemObj")
itemObj.Handle = "xxx-123"
itemObj.AttachServerMap(server)
Where server is an IServer instance and is created as a stand-alone object without being derived from a
server store. If the server was created from a server store, the same CreateObject statement is functionally
the same as:

dim itemObj
set itemObj = CreateObject("DSITEMENUMLib.ItemObj")
itemObj.Handle = "xxx-123"
itemObj.DSServerMap = server.InstanceId
AttachGateway is used to connect an already opened gateway object to an item object. If your application
performs extensive network access, it is recommended to directly attach a gateway object to an item
object. At some point prior to issuing a DocuShare command, an item object creates a gateway object. If
the item object was created using IServer (as in the above two cases), a gateway object is created and
deleted each time one of the DocuShare accessing methods, such as DSLoadProps and DSUpload, is
executed. This is called implicit gateway association. By attaching a pre-existing gateway object directly to
an item object, the item object reuses the same gateway object, possibly resulting in performance gain.
This is the explicit gateway association.

dim collection
set collection = server.CreateObject("Collection-123")
dim gateway
set gateway = server.Open
collection.AttachGateway gateway

2–46 DocuShare Windows Client SDK

SDK Programming Working with properties

status = collection.DSLoadChildren
dim children
set children = collection.EnumObjects(DSCONTF_CHILDREN)
children.Reset
while children.NextPos <> 0
dim child
set child = children.NextItem
child.DSLoadProps
Print child
wend
set gateway = collection.DetachGateway
' Perform other tasks
...
The above example overrides the implicit gateway association made by the originating
IServer.CreateObject call. Once an explicit gateway association is made, DocuShare’s IItemObj methods
always use the external gateway. If necessary, you can call DetachGateway after the explicit gateway
association is no longer needed and restore the originating instance of the gateway object.

The following methods listed in Table 2–2 are used in identifying the relationship between two item objects
or used in manipulating the child and parent lists which are internally maintained by an item object.

• Attach—attaches a child list

• AttachParents—attaches a parent list
• EnumObjects—creates an enumerator for related children or parents
• CopyTo—copies properties to another item object
• Compare—compares two item objects by one or more properties
• IsChildOf—tests if an item object is a child object of another
When you do not or cannot call DSLoadProps for up-to-date information, use the Attach and AttachParents
methods to create an item representation manually to confirm the value of properties that the item should
be assigned.

Depending on the value of the flag parameter, the EnumObjects method creates an item enumerator for
child or parent items.

The CopyTo method is useful in creating a replica of an item object. This method copies all properties
except the IItemObj instance-specific properties such as Data, Icon, and Thumbnail. Refer to Chapter 5,
DSItemEnumLib Library for a complete list.

The following example makes a duplicate of a file object, changes its title, and later prints both old and new
titles.

dim fileObj, oldObj

set fileObj = server.CreateObject("File-123")
status = fileObj.DSLoadProps
status = fileObj.CopyTo( oldObj, 0 )

DocuShare Windows Client SDK 2–47

Working with properties SDK Programming

fileObj.Title = "This is the new title"

Print "Old title: "+oldObj.Title
Print "New title: "+fileObj.Title
The Compare and IsChildOf methods make a comparison of two item objects. The Compare tests
equivalence by property. The IsChildOf tests the parent-child relationship and can be used in an iteration
routine to find the parent or child of a particular item. Compare can be used in an item listing routine to sort
collected items, such as title and handle.

From the list of found items (items whose titles contain the phrase—test), IsChildOf is used in the example
below to collect all items that belong to a particular collection (theCollection).

dim gateway
set gateway = server.Open
...
gateway.DSDisplayName = "test*"
status = gateway.Search (...)
dim theList ' This will hold all items that are parented by 'theCollection'.
set theList = CreateObject("DSITEMENUMLib.EnumObj")
dim itemList ' This will hold all items found by Search.
set itemList = CreateObject("DSITEMENUMLib.EnumObj")
status = itemList.Load( DSCONTF_CHILDREN or DSCONTF_DESCENDANTS,
gateway.DSItemListFile )
itemList.Reset
while itemList.NextPos <> 0
dim nextObj
set nextObj = itemList.NextItem
' Test child-parent relationship.
if nextObj.IsChildOf( theCollection ) then
' If this next item belongs to 'theCollection', attach
' it to 'theList'.
theList.Attach(nextObj)
end if
wend
The following example list items that appear in a DocuShare collection and bubble-sorts them by title.

dim collection
set collection = server.CreateObject("Collection-123")
status = collection.DSLoadChildren
dim itemList
set itemList = collection.EnumObjects( DSCONTF_CHILDREN )
itemList.Reset
' Create a linear array of item objects from an enumerator

2–48 DocuShare Windows Client SDK

SDK Programming Working with properties

totalItems = itemList.Length
dim itemObj[totalItems]
i = 1
while itemList.NextPos <> 0
set itemObj[i] = itemList.NextItem
i = i+1
wend
for i = 1 to totalItems
for j = 1 to totalItems
' Negative result means j'th item comes ahead of i'th item.
if itemObj[i].Compare( itemObj[j], ITEMOBJ_COMPARE_TITLE ) < 0 then
' Save j'th item
dim tempObj
set tempObj = itemObj[j]
' Move up the items of i through j-1 so that item j-1 occupies the j'th slot
' and i'th item occupies the i+1'th slot.
for k = j downto i, step -1
set itemObj[k] = itemObj[k-1]
' Move j'th item to the i'th slot.
set itemObj[i] = tempObj
next k
end if
next j
next i

2.12.1.1 Icons and thumbnails

IItemObj defines properties of type objects. These are the Icon and Thumbnail properties. The Icon
property is useful when displaying an item in a list. Adding the icon picture to the item list makes it easier
for a user to identify the item type quickly. IItemObj can generate large (32 x 32 pixel) and small (16 x 16
pixel) icons. Each icon is assigned a unique index number. This number is obtained by referencing the
IItemObj.TypeIndex property. If you need indexing icons, use the TypeIndex property to create an image
list for list view generation. The Icon property outputs the icon resource as a picture object of system-
defined interface, IPictureDisp.

DocuShare Windows Client SDK 2–49

Working with properties SDK Programming

This example loads icons from an item object into four PictureBox controls such as largeIcon and
smallIcon. PictureBox is a Visual Basic control and is used to display a picture.

dim file
set file = server.CreateObject("File-456")
status = file.DSLoadProps
' Show the four icons-large, opened; small, opened;
' large, closed; and small, closed
largeIcon.Picture = file.Icon(False, False)
smallIcon.Picture = file.Icon(False, True)
largeOpenedIcon.Picture = file.Icon(True, False)
smallOpenedIcon.Picture = file.Icon(True, True)
The Thumbnail property refers to a large thumbnail picture (up to 100 by 150 pixels) that DocuShare can
generate for an image file. When referenced for the first time, the Thumbnail property downloads the
thumbnail data from the server and outputs the image data as a picture object. To retrieve the thumbnail
picture for a file item, use this code fragment:

dim imageFile
set imageFile = server.CreateObject("File-456")
status = imageFile.DSLoadProps
' Show the thumbnail in a picture box control
picBox.Picture = imageFile.Thumbnail
By default, repeat referencing of the Thumbnail property reuses a thumbnail picture object that was
created at the time of first reference. To force reloading of the thumbnail, because the original image file
was updated, you can either create a new IItemObj object for the updated file, or you can set the Reload
property to True, prior to the repeated referencing.

For a C++ application, the IPicture interface of a picture object generated by the Icon or Thumbnail
property can be used in order to extract the icon (HICON) or bitmap handle (HBITMAP). The extracted
handle can be used in calls to Win32 GDI functions to render the icon or thumbnail picture. See the SDK
sample program, TESTICON, for more details.

The IItemObj interface also defines the following instance-specific properties:

• Data
• Reload
• AutoDelete
• DSGatewayMode
• DSErrorCode
• DSServerMapId
Some of these properties have been described; those that have not been are described below.

2–50 DocuShare Windows Client SDK

SDK Programming Working with properties

The Data property can store application-defined data. To index item objects by assigning serial numbers,
you can set the Data property to a serial number. This code fragment finds the child items of a collection
and number them using the Data property.

...
set itemList = collection.EnumObjects( DSCONTF_CHILDREN )
itemList.Reset
totalItems = itemList.Length
dim itemObj[totalItems]
i = 1
while itemList.NextPos <> 0
set itemObj[i] = itemList.NextItem
itemObj[i].Data = i
i = i+1
wend
Because the Data property has the Variant data type, you can assign an integral number which can be a
real number, a text string, or a date.

The Reload property is a flag property that was described earlier. The AutoDelete property is another flag
property. It controls the behavior of IItemObj with regard to the deletion of a downloaded file. AutoDelete is
initially cleared; set it to True to let the item object perform the deletion of the downloaded file when the
item object is deleted.

dim file
set file = server.CreateObject("File-123")
status = file.DSDownload
if status = 0 then
file.AutoDelete = True
...
In this code sample, the downloaded copy of the file is automatically deleted when the file object goes out
of scope.

When DSDownload is called, the requested file is downloaded to the local location (path) specified by the
Name property. If the Name property is undefined (as in the above example), DSDownload generates a
temporary pathname and sets Name to it. If the Name property contains a filename (such as
DSLoadProps), but is missing the fully qualified pathname, DSDownload downloads the file to a work
folder in the SDK installation directory. The Name property is changed to the fully qualified pathname of the
downloaded file in the work folder.

DocuShare Windows Client SDK 2–51

Working with properties SDK Programming

DSGatewayMode is a property for controlling the behavior of an associated gateway object. This code
sample uses the mode setting property to instruct the gateway not to display the following:

• progress indicator (a dialog box with a progress bar)

• errors should an error condition arise during the download processing
...
file.DSGatewayMode = DSAXES_MODE_SILENT Or
DSAXES_MODE_NOERRORDLG
status = file.DSDownload
...
Refer to SetMode on page 3–71 for a complete list of the valid mode flags. Gateway accessing methods of
IItemObj are always synchronous, and therefore, the DSAXES_MODE_ASYNCHRONOUS flag cannot be
used. For debugging purposes, use the DSAXES_MODE_SHOWWINDOW flag to instruct the gateway to
show an event logging window. You can trace the network events taking place as a result of making a
gateway call.

DSErrorCode is a read-only property of IItemObj and is used to hold the last error code generated by an
associated gateway object. If the gateway object encounters a socket or HTTP error while processing a
DocuShare command, such as DSDownload, the calling item object saves the error code generated by the
gateway in DSErrorCode.

...
status = file.DSDownload
if status = DSAXES_E_WINSOCK then
Print "Program encountered socket error " + CStr(
file.DSErrorCode )
...
if status = DSAXES_E_HTTP then
Print "Program encountered HTTP error " + CStr( file.DSErrorCode )
Refer to Win32 documentation on the Windows sockets library for the listing of socket error codes. For
HTTP error codes, refer to Internet Draft Hypertext Transfer Protocol - HTTP/1.0.

DSServerMapId is used by an IItemObj object to associate itself with an IServer object. The IServer
association is used to obtain server access information and user credentials to open a gateway. Normally,
you do not need to use this property. It is set by IServer when you call IServer.CreateObject to create an
item object. However, if an item object was created manually, using IEnumObject.NewItem, the
DSServerMapId property is undefined (set to zero).

The following code example creates an item enumerator object and creates two item objects (calendars)
attached to the enumerator object. One of the item objects is associated to one server while the other is
associated to another server. The DSServerMapId property is used to make the association. The
association is later checked to perform a server-dependent task. Finally, an iteration loop deletes the
DocuShare calendars represented by the two item objects.

...
dim itemList
set itemList = CreateObject("DSITEMENUMLib.EnumObj")

2–52 DocuShare Windows Client SDK

SDK Programming Working with properties

dim itemObj1, itemObj2

set itemObj1 = itemList.NewItem
set itemObj2 = itemList.NewItem
itemObj1.DSServerMapId = server1.InstanceId
itemObj1.Handle = "xxx-100"
itemObj2.DSServerMapId = server2.InstanceId
itemObj2.Handle = "xxx-100"
...
if itemObj1.DSServerMapId = server1.InstanceId then
' Do server1-specific task
...
if itemObj2.DSServerMapId = server2.InstanceId then
' Do server2-specific task
...
itemList.Reset
while itemList.NextPos <> 0
dim itemObj
set itemObj = itemList.NextItem
status = itemObj.DSDelete
wend
This example assumes that both server1 and server2 were instances of IServer and mapped to different
DocuShare servers.

2.12.2 IItemObj and custom properties

In earlier examples CustomProp property of IItemObj were used. In one example, it was used to define
user account properties in creating a user account. CustomProp can also be used by the following
DocuShare command methods:

• DSCreate
• DSUpload
• DSLoadProps
• DSSaveProps
DSCreate uses the CustomProp property to pass user account properties not explicitly defined by
IItemObj. DSUpload and DSCreate for a file object, uses CustomProp to allow the caller to pass-in custom
DocuShare properties in creating a DocuShare document. DSLoadProps can be used to load custom
DocuShare properties identified by corresponding CustomProp declarations, while DSSaveProps can be
used to save them in DocuShare.

DocuShare Windows Client SDK 2–53

Working with properties SDK Programming

The following rules and techniques apply when defining custom properties and using them to create and
update DocuShare items.

1. Define a property name and set the first Name argument of CustomProp to it.
2. Choose an automation type identifier supported by both the OLE Variant syntax and the IItemObj
library.
3. Set the second TypeId argument of CustomProp to the corresponding IItemObj type identifier
(DSAXES_PROPTYPE_...).
4. Assign the value data in the chosen automation type (VT_...) to CustomProp.
The following examples illustrate the application of the rules for custom properties. This C++ code sample
declares a custom property named MyCustomName and assigns a text value MyValue to it.

VARIANT myProp;
myProp.vt = VT_BSTR;
myProp.bstrVal = SysStringAlloc(L"MyValue");
SetCustomProp(L"MyCustomName", DSAXES_PROPTYPE_STRING, &myProp);
VariantClear(&myProp);
To do the same thing in Visual Basic, simply make this assignment.

CustomProp("MyCustomProp", DSAXES_PROPTYPE_STRING) = "MyValue"

The Visual Basic interpreter performs the necessary Variant structural transformation. For an integer
assignment, the above C++ code may be changed to:

...
myProp.vt = VT_I4;
myProp.lVal = 123;
SetCustomProp(L"MyCustomName", DSAXES_PROPTYPE_INTEGER, &myProp);
...
In Visual Basic, use this entry.

CustomProp("MyCustomProp", DSAXES_PROPTYPE_INTEGER) = 123

The valid data types for CustomProp are listed in Table 2–3.

Table 2–3: CustomProp Data Types

Data Type of Assigned Automation Type for

Corresponding SDK Type ID
Value Assigned Value

Boolean VT_BOOL DSAXES_PROPTYPE_BOOLEAN

Integer VT_I2 or VT_I4 DSAXES_PROPTYPE_INTEGER

Float VT_R4 or VT_R8 DSAXES_PROPTYPE_FLOAT

Date VT_DATE DSAXES_PROPTYPE_DATE

Text VT_BSTR DSAXES_PROPTYPE_STRING

Binary VT_ARRAY DSAXES_PROPTYPE_BINARY

2–54 DocuShare Windows Client SDK

SDK Programming Working with properties

To load custom properties from DocuShare:

itemObj.CustomProp("custom_prop_1", 1) = ""
itemObj.CustomProp("custom_prop_2", 1) = ""
status = itemObj.DSLoadProps
Print "custom_prop_1: "+itemObj.CustomProp("custom_prop_1", 1)
Print "custom_prop_2: "+itemObj.CustomProp("custom_prop_2", 1)

NOTE: The DocuShare server must understand what custom_prop_1 and custom_prop_2 are for this
code to work correctly.

itemObj.CustomProp("custom_prop_1", 1) = "New value for prop 1"

itemObj.CustomProp("custom_prop_2", 1) = "New value for prop 2"
status = itemObj.DSSaveProps
To supply a custom property for an uploaded file, you can use the following:

itemObj.CustomProp("custom_prop_for_upload", 1) = "This is a special value"

status = fileObj.DSUpload
For this code to work, your DocuShare server must know what to do with the custom property you specify.

If, for some reason, you do not want to pass pre-declared custom properties to DocuShare, you can set the
DSAXES_PROPID_CORE_CUSTOM bitfield of ExcludedCoreProps to True.

2.12.3 IEnumObj methods and properties

The IEnumObj object implements the SDK item enumerator object. The enumerator object is typically used
to load an item list generated by a gateway object and to iterate the item objects contained in the list. The
enumerator object can also create an item list, either by creating a blank item object and attaching it to the
internal item list or by attaching existing item objects to the list.

The IEnumObj interface defines the following properties:

• NextPos—enumeration position; zero when there are no more item objects

• NextItem—item object at current enumeration; enumeration position is advanced
• Length—number of item objects held by the enumerator
The Length property lists the number of item objects the enumerator holds. The next example uses the
Length property to print the total number of items that appear in a collection.

dim collection
set collection = server.CreateObject("Collection-123")
status = collection.DSLoadChildren
dim itemList
set itemList = collection.EnumObjects(DSCONTF_CHILDREN)
Print "Number of items in Collection-123: "+CStr( itemList.Length )
The IEnumObj interface defines the following methods:

DocuShare Windows Client SDK 2–55

Working with properties SDK Programming

• Load—loads an item list from a file output by a gateway object

• Reset—resets the enumeration counter
• NewItem—creates a blank item object and attaches it to the internal list
• RemoveItem—removes an item object from the internal list
• Attach—attaches an existing item object to the internal list
• CopyTo—copies all item objects of another enumerator
• GetLengthOf—counts sub-item objects of a specified type belonging to an item object
• GetNode—outputs an item object of a specified collection handle number
The Load and Reset methods are used in enumeration tasks. Together with the NextPos and NextItem
properties, these methods provide SDK core enumeration functionality.

The NewItem, RemoveItem, and Attach methods are used to manually generate a new item list or update
an existing list.

The CopyTo method copies the item list to another enumerator object. You can use it to create a backup
copy of an item object list for later comparison purposes before modifying the list.

The GetLengthOf method can be used to check if the list contains one or more items of a specific type.
This example uses GetLengthOf to find the number of file items that appear in a particular collection
(theCollection).

dim gateway
set gateway = server.Open
...
gateway.DSDisplayName = "test*"
status = gateway.Search (...)
dim itemList
set itemList = CreateObject("DSITEMENUMLib.EnumObj")
status = itemList.Load( DSCONTF_ALL, gateway.DSItemListFile )
count = itemList.GetLengthOf(theCollection, ENUMOBJ_GLOTYPE_FILE)
If you want the count, in all child items, that appear in collection theCollection, set the type flag
GetLengthOf to ENUMOBJ_GLOTYPE_ALL.

2–56 DocuShare Windows Client SDK

SDK Programming Uploading documents

2.13 Uploading documents

All of the following code assumes the following declaration within the General.Declaration section of the
Visual Basic code.

The objServer object is assumed be valid and logged in. To instantiate a valid objServer, refer to Log into a
DocuShare server on page 2–31.

For upload result display, the code assumes that a Visual Basic Form exists with a list object named
lstDisplay. This list object is referenced throughout the sample code.

Upload Examples.

• A Simple Upload on page 2–57

• A Version Upload on page 2–58
• A Directory Upload on page 2–59
• A Directory Upload to a Collection on page 2–60
• A Wildcard Upload on page 2–61
• A Wildcard Upload to Target Collection on page 2–62

2.13.1 A Simple Upload

This example demonstrates how to perform an upload and lists the properties of the uploaded file with the
ListItemProperties function defined in Selecting a File from Server List on page 2–42.

' A simple file upload

Public Sub SimpleUpload()
' First we need a ItemObj to hold the upload file info
Dim objFileItem As Object
Set objFileItem = CreateObject("DSITEMENUMLib.ItemObj")
' Next we set the minimum file properties
objFileItem.TypeNum = DSXITEMTYPE_DOCUMENT
objFileItem.Name = "C:\Path\Document.txt" ' The file to upload
objFileItem.Title = "The File Title" ' The title that will displayed
objFileItem.ParentHandle = "Collection-12" ' The collection to upload the
file to
' Now we can attempt the upload
Dim lFlags As Long
lFlags = 0
Dim lResult As Long
lResult = objFileItem.DSUpload(lFlags)
If lResult <> DSAXES_SUCCESS Then
MsgBox "objFileItem.DSUpload failed with result: " + CStr(lResult)
Exit Sub
End If

DocuShare Windows Client SDK 2–57

Uploading documents SDK Programming

' It's always safe to have the latest properities

lResult = objFileItem.DSLoadProps
If lResult <> DSAXES_SUCCESS Then
MsgBox "objFileItem.DSLoadProps failed with result: " + CStr(lResult)
Exit Sub
End If
ListItemProperties objFileItem
End Sub

2.13.2 A Version Upload

' Upload a new version of document
Public Sub VersionUpload()
' First we need a ItemObj to hold the upload version info
Dim objFileItem As Object
Set objFileItem = objServer.CreateObject("File-150")
' Next we set the minimum version properties
objFileItem.Name = "C:\Temp\wecerr.txt" ' The file to upload
' Now we can attempt to upload the new version
Dim lResult As Long
lResult = objFileItem.DSUpload()
If lResult <> DSAXES_SUCCESS Then
MsgBox "objFileItem.DSUpload failed with result: " + CStr(lResult)
Exit Sub
End If
' Now let's list out the version for the file
lResult = objFileItem.DSLoadChildren
If lResult <> DSAXES_SUCCESS Then
MsgBox "objFileItem.DSLoadChildren failed with result: " + CStr(lResult)
Exit Sub
End If
Dim objVersionEnum As Object
Set objVersionEnum = objFileItem.EnumObjects(0)
Dim objVersion As Object
objVersionEnum.Reset
While 0 <> objVersionEnum.NextPos
Set objVersion = objVersionEnum.NextItem
Dim strTitle As String
strTitle = objFileItem.Title + " - Version " + CStr(objVersion.VersionNum)

2–58 DocuShare Windows Client SDK

SDK Programming Uploading documents

lstDisplay.AddItem strTitle
Wend
End Sub

2.13.3 A Directory Upload

' Upload a directory to a server
' This will utilize the directory name to create a
' collection within the designated parent specified
' in the property Parent
Public Sub DirectoryUpload()
' First we need a ItemObj to hold the directory upload info
Dim objDirItem As Object
Set objDirItem = objServer.CreateObject("Collection")
' Next we set the minimum directory upload info
objDirItem.Name = "C:\Validation" ' The directory path
objDirItem.ParentHandle = "Collection-12" ' The target parent collection
' Now we can attempt to upload the directory
Dim lResult As Long
lResult = objDirItem.DSUpload()
If lResult <> DSAXES_SUCCESS Then
MsgBox "objDirItem.DSUpload failed with result: " + CStr(lResult)
Exit Sub
End If
' Let's get the latest props for the created collection
' Note that the objDirItem.HandleNum has been set
' to the newly created collection
lResult = objDirItem.DSLoadProps
If lResult <> DSAXES_SUCCESS Then
MsgBox "objDirItem.DSLoadProps failed with result: " + CStr(lResult)
Exit Sub
End If
' Finally we list the properties of the new collection
' and list out the newly created files.
ListItemProperties objDirItem
lResult = objDirItem.DSLoadChildren
If lResult <> DSAXES_SUCCESS Then
MsgBox "objDirItem.DSLoadChildren failed with result: " + CStr(lResult)
Exit Sub

DocuShare Windows Client SDK 2–59

Uploading documents SDK Programming

End If
Dim objFilesEnum As Object
Set objFilesEnum =objDirItem.EnumObjects(DSCONTF_DOCUMENTS)
Dim objFile As Object
objFilesEnum.Reset
While 0 <> objFilesEnum.NextPos
Set objFile = objFilesEnum.NextItem
lstDisplay.AddItem objFile.Name
Wend
End Sub

2.13.4 A Directory Upload to a Collection

' Upload the contents of a directory to a specified
' collection. The target collection is passed in
' the property HandleNum
Public Sub Dir2CollUpload()
' First we need a ItemObj to hold the directory upload info
Dim objSourceDirItem As Object
Set objSourceDirItem = objServer.CreateObject("Collection-12")
' Next we set the minimum directory upload info
objSourceDirItem.Name = "C:\Validation" ' The directory path
' Now we can attempt to upload the directory contents
Dim lResult As Long
lResult = objSourceDirItem.DSUpload()
If lResult <> DSAXES_SUCCESS Then
MsgBox "objSourceDirItem.DSUpload failed with result: " + CStr(lResult)
Exit Sub
End If
' Finally we list the properties of the new collection
' and list out the newly created files.
ListItemProperties objSourceDirItem
' Load the target collection
lResult = objSourceDirItem.DSLoadChildren
If lResult <> DSAXES_SUCCESS Then
MsgBox "objSourceDirItem.DSLoadChildren failed with result: " +
CStr(lResult)
Exit Sub
End If
Dim objFilesEnum As Object

2–60 DocuShare Windows Client SDK

SDK Programming Uploading documents

Set objFilesEnum = objSourceDirItem.EnumObjects(DSCONTF_DOCUMENTS)

Dim objFile As Object
objFilesEnum.Reset
While 0 <> objFilesEnum.NextPos
Set objFile = objFilesEnum.NextItem
lstDisplay.AddItem objFile.Name
Wend
End Sub

2.13.5 A Wildcard Upload

' Wild card upload to a parent directory
' In this example the directory name of the wild card source
' will be utilized to create a collection in the parent collection
' designated in the Parent property
Public Sub Wild2ParUpload()
' First we need a ItemObj to hold the directory and wildcard info
Dim objWildItems As Object
Set objWildItems = objServer.CreateObject("Collection")
' Next we set the minimum wildcard upload info
objWildItems.Name = "C:\Validation\*.txt" ' The directory path and wild card
objWildItems.ParentHandle = "Collection-12" ' The target parent collection'
Now we can attempt to create the dir
' and upload the wildcards
Dim lResult As Long
lResult = objWildItems.DSUpload()
If lResult <> DSAXES_SUCCESS Then
MsgBox "objWildItems.DSUpload failed with result: " + CStr(lResult)
Exit Sub
End If
' Let's get the latest props for the created collection
' Note that the objWildItems.HandleNum has been set
' to the newly created collection
lResult = objWildItems.DSLoadProps
If lResult <> DSAXES_SUCCESS Then
MsgBox "objWildItems.DSLoadProps failed with result: " + CStr(lResult)
Exit Sub
End If
' Finally we list the properties of the new collection

DocuShare Windows Client SDK 2–61

Uploading documents SDK Programming

' and list out the newly created files

ListItemProperties objWildItems
lResult = objWildItems.DSLoadChildren
If lResult <> DSAXES_SUCCESS Then
MsgBox "objWildItems.DSLoadChildren failed with result: " + CStr(lResult)
Exit Sub
End If
Dim objFilesEnum As Object
Set objFilesEnum = objWildItems.EnumObjects(DSCONTF_DOCUMENTS)
Dim objFile As Object
objFilesEnum.Reset
While 0 <> objFilesEnum.NextPos
Set objFile = objFilesEnum.NextItem
lstDisplay.AddItem objFile.Name
Wend
End Sub

2.13.6 A Wildcard Upload to Target Collection

' Wild card upload to a target collection
' In this example the files in the source directory that meet
' the wild card, will be upload to the target collection
' designated by the property HandleNum
Public Sub Wild2CollUpload()
' First we need a ItemObj to hold the collection and wildcard info
Dim objTargetColl As Object
Set objTargetColl = objServer.CreateObject("Collection-12")
' Next we set the minimum wildcard upload info
objTargetColl.Name = "C:\Validation\*.txt" ' The directory path and wild
card
' Now we can attempt to upload the wildcards
Dim lResult As Long
lResult = objTargetColl.DSUpload()
If lResult <> DSAXES_SUCCESS Then
MsgBox "objTargetColl.DSUpload failed with result: " + CStr(lResult)
Exit Sub
End If
' Let's load the children of the target collection
lResult = objTargetColl.DSLoadChildren
If lResult <> DSAXES_SUCCESS Then

2–62 DocuShare Windows Client SDK

SDK Programming Uploading documents

MsgBox "objTargetColl.DSLoadChildren failed with result: " + CStr(lResult)

Exit Sub
End If
Dim objFilesEnum As Object
Set objFilesEnum = objTargetColl.EnumObjects(DSCONTF_DOCUMENTS)
Dim objFile As Object
objFilesEnum.Reset
While 0 <> objFilesEnum.NextPos
Set objFile = objFilesEnum.NextItem
lstDisplay.AddItem objFile.Name
Wend
End Sub

DocuShare Windows Client SDK 2–63

Performing basic searches SDK Programming

2.14 Performing basic searches

To search items in DocuShare:

• Create an instance of the gateway object

• Define search criteria by setting appropriate query properties of IDsAxes
• Call the IDsAxes.Search method
• Perform a post-process by loading the returned item list in an enumerator object and iterating the
found items
The following example searches items whose titles contain the phrase test, and prints the found items.

dim gateway
set gateway = server.Open
gateway.DSMaxItems = 100
gateway.DSDisplayName = "test"
status = gateway.Search( DSSRCH_BY_TITLE, "" )
dim itemList ' This will hold all items found by Search.
set itemList = CreateObject("DSITEMENUMLib.EnumObj")
status = itemList.Load( DSCONTF_ALL, gateway.DSItemListFile )
itemList.Reset
while itemList.NextPos <> 0
dim nextObj
set nextObj = itemList.NextItem
Print nextObj.Title+" ("+nextObj.Handle+")"
wend
DSMaxItems sets an upper limit for search hits returned by the server. It is a required search parameter.
The above example defines a search term using DSDisplayName. Table 2–4 lists the searchable
properties that the IDsAxes gateway interface defines.

Table 2–4: IDsAxes Gateway Searchable Properties

Searchable Property Property Selection Flag

DSDisplayName DSSRCH_BY_TITLE

DSFileName DSSRCH_BY_FILENAME

DSFileType DSSRCH_BY_MIMETYPE

DSContent DSSRCH_BY_CONTENT

DSKeywords DSSRCH_BY_KEYWORD

DSOwner DSSRCH_BY_OWNER

DSCreatedTimeFrom DSSRCH_BY_CREATETIME

DSCreatedTimeTo DSSRCH_BY_CREATETIME

2–64 DocuShare Windows Client SDK

SDK Programming Performing basic searches

Table 2–4: IDsAxes Gateway Searchable Properties

Searchable Property Property Selection Flag

DSModifiedTimeFrom DSSRCH_BY_MODIFTIME

DSModifiedTimeTo DSSRCH_BY_MODIFTIME

To create compound search criteria, assign values to the searchable properties listed in the table and
combine the corresponding property selection flags. The Search method finds items that meet any one of
the search terms. For example, the search terms are logically ORed. By specifying the
DSSRCH_CONJUNCT_AND flag, you can instruct Search to combine the search terms by logical AND
operators. The method will find items that meet the criteria set by all of the search terms.

gateway.DSMaxItems = 100
gateway.DSContent = "test"
gateway.DSModifiedTimeFrom = #1/1
gateway.DSModifiedTimeTo = #1/3
status = gateway.Search(DSSRCH_BY_CONTENT Or DSSRCH_BY_MODIFTIME,"" )
This example finds all items containing the phrase test and modified between 1/1 and 1/3.

To negate the search term, use DSSRCH_OP_NEGATE. The next example finds items which do not have
the phrase test in their titles.

gateway.DSDisplayName = "test"
status = gateway.Search(DSSRCH_BY_TITLE Or DSSRCH_OP_NEGATE,"" )
If multiple search terms are set, DSSRCH_OP_NEGATE negates all of them.

The previous examples have been searches of items by any type. You can limit search by item type using
the type selection flags listed in Table 2–5.

Table 2–5: Selection Flag Type

Item Type Type Selection Flag

File DSSRCH_TYPE_FILE

Collection DSSRCH_TYPE_COLLECTION

Calendar DSSRCH_TYPE_CALNDR

Bullitin Board DSSRCH_TYPE_BBOARD

User DSSRCH_TYPE_USER

Group DSSRCH_TYPE_GROUP

Custom Type DSSRCH_AS_TYPE

DocuShare Windows Client SDK 2–65

Performing basic searches SDK Programming

To limit the title search to files and collections:

gateway.DSDisplayName = "test"
status = gateway.Search(
DSSRCH_TYPE_FILE Or
DSSRCH_TYPE_COLLECTION Or
DSSRCH_BY_TITLE,
"" )
To search items of a type not pre-defined by the gateway object, use the DSSRCH_AS_TYPE flag, and set
the query data argument of the Search method to the type identifier.

gateway.DSDisplayName = "test"
status = gateway.Search(
DSSRCH_AS _TYPE Or
DSSRCH_BY_TITLE,
"special_type" )
This example searches items of type, special_type.

By default, the Search method finds items in all DocuShare collections. You can limit the search to a
particular collection. For example, to find items in Collection-10 and its child collections, set the
DSCollHandle property of IDsAxes to 10, and use the DSSRCH_SCOPE_COLL flag in the Search call.

gateway.DSDisplayName = "test"
gateway.DSCollHandle = 10
status = gateway.Search(
DSSRCH_TYPE_FILE Or
DSSRCH_SCOPE_COLL Or
DSSRCH_BY_TITLE,
"" )
The Gateway inteface defines only a limited set of searchable properties. The Gateway interface defines
the following set of flags that instruct the Search method to regard the query data parameter as the value
of a user-defined searchable property.

• DSSRCH_AS_TITLE*
• DSSRCH_AS_FILENAME*
• DSSRCH_AS_KEYWORD*
• DSSRCH_AS_OWNER*
• DSSRCH_AS_SUMMARY
• DSSRCH_AS_DESCRIPTN
• DSSRCH_AS_AUTHOR
• DSSRCH_AS_LASTUSER
• DSSRCH_AS_CUSTOM

2–66 DocuShare Windows Client SDK

SDK Programming Performing basic searches

NOTE: Flags marked with an asterisk duplicate the searchable properties specified by the
corresponding DSSRCH_BY_... flags.

DSSRCH_AS_... flags cannot be combined; only one value can be specified using the query data
parameter.

To find files whose summary properties contain a certain phrase:

status = gateway.Search(
DSSRCH_TYPE_FILE Or
DSSRCH_AS_SUMMARY,
"business proposal" )
You can use the DSSRCH_AS_... flags to specify a compound criteria that is still limited to a single
searchable property.

gateway.DSDisplayName = "test"
status = gateway.Search(
DSSRCH_TYPE_FILE Or
DSSRCH_BY_TITLE Or
DSSRCH_AS_TITLE Or
DSSRCH_CONJUNCT_AND,
"more" )
This example searched files by title. However, the search only found files whose titles contained both test
and more.

To search items by custom property, set the DSItemProp property to the name of the custom property, use
the DSSRCH_AS_CUSTOM flag, and set the query data argument to the value of the custom property.
The next example finds files whose custom property special_prop contains the phrase, special.

gateway.DSItemProp = "special_prop"
status = gateway.Search(
DSSRCH_AS _CUSTOM Or
DSSRCH_TYPE_FILE,
"special" )
For a more complex query, use DSSRCH_ALREADY_XML. When this flag is set in the Search flags
parameter, the Search method regards the query data argument as a description for search criteria written
in the DocuShare XML/WebDAV query syntax. Use DSSRCH_ALREADY_XML only if the query data
supplies a complete XML query form including search scope, search criteria, and a list of queried property
names. Combine DSSRCH_ALREADY_XML with DSSRCH_USE_TEMPLATE if the query data supplies
search criteria only. The Search method supplies an upper limit for search hits (set to the current value of
DSMaxItems) and a list of queried properties (those set by assignments made to PropIds).

DocuShare Windows Client SDK 2–67

Performing basic searches SDK Programming

When using DSSRCH_ALREADY_XML without DSSRCH_USE_TEMPLATE, you cannot use other flags
except DSSRCH_ASYNC. If DSSRCH_USE_TEMPLATE is also set, DSSRCH_SCOPE_COLL may be
used to limit the search scope. Regarding the use of the DSSRCH_ASYNC flag, the flag should be used
only if your application has subscribed to the gateway notification service.

If DSSRCH_ALREADY_XML without DSSRCH_USE_TEMPLATE is set, you are responsible for

identifying all queried properties that refer to IItemObj representations of the found items. Thus, if you are
interested in the IItemObj.Title and IItemObj.TimeCreated properties, you need to include the XML
property tags, <displayname/> and <creationdate/> in the <select>...</select> statement of your XML form
data.

The following example supplies a complete XML search request form:

formdata =
"<?xml version="1.0" ?>
<searchrequest>
<simplesearch>
<select>
<prop>
<displayname/>
...
</prop>
</select>
<from>
<scope>
<href>http://my.docushare.com/</href>
</scope>
</from>
<limit>
<nresults>100</nresults>
</limit>
<where>
<contains>
<prop><displayname/></prop>
<literal>test</literal>
</contains>
</where>
</simplesearch>
</searchrequest>"
status = gateway.Search(
DSSRCH_ALREADY_XML,
formdata )

2–68 DocuShare Windows Client SDK

SDK Programming Performing basic searches

This example searched for items of any types and whose titles contain test in all the DocuShare server
collections.

If you need to use XML form data, it is recommended that you use it with the DSSRCH_USE_TEMPLATE
flag. This way, all standard item properties are automatically queried.

When using DSSRCH_USE_TEMPLATE, you only need to supply search terms in XML. The Search
method uses the following XML formatting template in generating a query request form.

• %1 is the placeholder for inserting a list of names of queried properties

• %2 is the placeholder for a search scope
• %3 is the placeholder for a search hit’s upper ceiling
<?xml version="1.0"?>
<searchrequest>
<simplesearch>
<select>
<prop>%1</prop>
</select>
<from>
<scope><href>%2</href></scope>
</from>
<limit>
<nresults>%3</nresults>
</limit>
<where>
<and>%4</and>
</where>
</simplesearch>
</searchrequest>
The Search method supplies the values for the %1, %2 and %3 placeholders. The XML search term
statements you supply in the query data argument replaces the %4 placeholder.

The following example uses DSSRCH_USE_TEMPLATE to search files created since 1/1/2000 12:00
GMT and whose titles contain phrase test.

criteria =
"<contains>
<prop><entitytype/></prop>
<literal>File</literal>
</contains>
<gte>
<prop><creationdate/></prop>
<literal>2000-01-01T12:00:00Z-00:00</literal>

DocuShare Windows Client SDK 2–69

Performing basic searches SDK Programming

</gte>
<contains>
<prop><displayname/></prop>
<literal>test</literal>
</contains>"
status = gateway.Search(
DSSRCH_ALREADY_XML Or DSSRCH_USE_TEMPLATE,
criteria )
Refer to Performing basic searches on page 2–64 for description of the XML query syntax used by
DocuShare.

2–70 DocuShare Windows Client SDK

SDK Programming Managing server connections

2.15 Managing server connections

IStore manages a collection of IServer objects and saves it in permanent storage for later use. If your
application needs to reuse one or more server objects every time the application is run, you can use the
services of IStore and design a persistent server map database. If the application uses the server map
database already created and maintained by the DocuShare Client application, the application must
adhere to the same rules and techniques for using IStore as does the DocuShare Client.

2.15.1 Creating a server map database

IStore can be used to create and access a server map database.

1. Create an instance of the IStore object.

2. Direct the IStore to create the server map database using a registry sub-key called
MyApp\Servers.
The database is created at the location,
HKCU\Software\Xerox\DocuShare Client\MyApp\Servers, in the current user section of the
Windows system registry.
dim store
set store = CreateObject("DSServerMap.Store")
store.BaseRegistryKey = "MyApp\Servers"
3. Create a server map and attach it to the store.
dim server
set server = CreateObject("DSServerMap.Server")
server.Name = "My DocuShare"
server.DocuShareAddress = "http://my.docushare.com/"
server.UserName = "joecool"
status = store.Protect
status = store.Add( server )
status = store.Save
status = store.Unprotect
The IStore.Protect call is necessary to prevent a concurrent application from modifying the database while
the attach job completes. After IStore.Save is called, to save the new database in the system registry, use
the call IStore.Unprotect to release the database. In the example, status check is skipped to keep the code
as simple as possible.

Instead of manually assigning server map properties as was done in the above code fragment, you could
use the IWizard helper object to create a server map. IWizard runs a series of Windows wizard-style
dialogs and collects user account information from an end user. To change to IWizard-based code, enter
the following:

dim server
set server = CreateObject("DSServerMap.Server")
dim wiz
set wiz = CreateObject("DSServerMap.Wizard")
wiz.Init( server )

DocuShare Windows Client SDK 2–71

Managing server connections SDK Programming

status = wiz.Run
status = store.Protect
status = store.Add( server )
status = store.Save
status = store.Unprotect
This example pertains to creating a new server map database. To add a server map to an existing one,
simply add a call to IStore.Load prior to calling IStore.Protect. The Load method loads the existing
database in the IStore object. To modify the store creation code, enter the following:

dim store
set store = CreateObject("DSServerMap.Store")
store.BaseRegistryKey = "MyApp\Servers"
store.Load
dim server
set server = CreateObject("DSServerMap.Server")
...
if store.CanAdd( server, SVRMAP_CANADDFLAG_SHOWERROR ) then
status = store.Protect
status = store.Add( server )
status = store.Save
status = store.Unprotect
end if
It is permissible to call IStore.Load even if a database does not exist at the BaseRegistryKey location.
Therefore, the above code can be used for both first-time database creation and subsequent database
updating. At this time, you can use IStore.CanAdd to make sure that the database does not contain the
new server map that you want to add. The SVRMAP_CANADDFLAG_SHOWERROR flag is used to
display a name conflict error to the end user.

If you need to remove a server map from the database, identify the server map, with the following:

...
status = store.Protect
status = store.Remove( server )
status = store.Save
status = store.Unprotect
If the undefined IStore.BaseRegistryKey was not set in the first code fragment, the database that would
have loaded or created would be the default database for the DocuShare Client. In other words, if your
application wants to share the DocuShare Client server map database, you simply leave the
BaseRegistryKey property undefined. The rest of IStore usage techniques stay the same regardless of the
source database.

If you do not want to create a persistent server map database, set the
SVRMAP_STOREOPT_STANDALONE bitfield of IStore.Options to True. The Load and Save methods of
IStore will return immediately without performing database re-synchronization.

2–72 DocuShare Windows Client SDK

SDK Programming Managing server connections

2.15.2 Enumerating server maps stored in the database

IStore is an enumerator object. Its interface defines the Reset method and the NextPos and NextItem
properties as does IEnumObj. To discover the server maps, use these methods and properties. Here is an
example of server enumeration.

status = store.Load
store.Reset
while store.NextPos <> 0
dim server
set server = store.NextItem
Print server.Name
wend
To find a particular server, you can explicitly compare server objects in terms of one or more server
properties within an enumeration loop. If required, use one of the following methods without enumeration:

Find
DoSelectDialog
Use the Find method to locate a server object by server map property. Use the DoSelectDialog method to
have the end user select a server object.

The Find method takes in the following:

• A Variant parameter describing the value of a search criteria.

• A flag parameter describing what the search criteria represents. The flag parameter is set using a
SVRMAP_COMPARE_... constant. Here is an example of finding a server by name.
status = store.Load
set server = store.Find( "My DocuShare", SVRMAP_COMPARE_NAME )
The DoSelectDialog method runs a dialog and lists the available server objects. The method marks a
server object that the end user chooses by setting the server object's IServer.IsSelected property to True.

status = store.Load
status = store.DoSelectDialog( 0,
"Select Servers",
"Servers you select will be opened",
"",
0,
0 )

DocuShare Windows Client SDK 2–73

Managing server connections SDK Programming

If the status code is zero, indicating that the user has successfully selected one or more servers, you can
use the enumeration technique to see which servers a user has selected.

store.Reset
while store.NextPos <> 0
dim server
set server = store.NextItem
if server.IsSelected then
Do whatever you need to do with the selected server
...
end if
wend
If you want to limit the selection to a single server, use SVRMAP_SELDLGFLAG_SINGLESEL when
calling the DoSelectDialog. If you want to limit the selection to a limited set of servers, pre-select the
servers and use SVRMAP_SELDLGFLAG_SHOWPRESEL. Here is an example of pre-selecting and
listing only those servers that do not use proxy servers.

status = store.Load
store.Reset
while store.NextPos <> 0
dim server
set server = store.NextItem
if server.UseProxy = False then
server.IsSelected = True
end if
wend
status = store.DoSelectDialog( 0,
"Select Servers",
"Servers you select will be opened",
"",
0,
SVRMAP_SELDLGFLAG_SHOWPRESEL )
The IStore interface defines a Close method. Calling the method performs unconditional logout for all
mapped servers.

2–74 DocuShare Windows Client SDK

SDK Programming Accessing the DocuShare objects using C++

2.16 Accessing the DocuShare objects using C++

This section outline mechanisms for C++ programming using MS Developer Studio to utilize the
DocuShare API. Using the steps outlined in this section, a C++ application can make use of the binding
COM model of programming. The resulting application you write can contain one or more C++ files that
provide client-side stubs classes that are used by the application. The classes and methods in these stubs
are described in this section. These stubs use the COM IDispatch interfaces to redirect the calls made by
your application to the DocuShare COM code that implements them.

The remainder of this section outline two mechanisms by which you can access DocuShare stubs from
your application. You can select one of these mechanisms that best fits your style of programming.

2.16.1 Using the stubs from the Include directory

The installed client toolkit provides an Include directory with definitions for the classes that you access in
your application.

Xerox DocuShare has provided Include files and client-side stubs in this directory, \Program
Files\Xerox\DSClient\Inc. To access them from your application, perform the following steps:

1. Direct your Developer Studio to look in the Include directory for definitions to the classes that you
require. The following classes are defined in these Include files:
• class IServer in idssvrmap.h—Server interface
• class IStore in idssvrmap.h—Store interface
• class IWizard in idssvrmap.h—Wizard interface
• class IBrowser in idssvrmap.h—Browser interface
• class IEnumObj in iitemenum.h—IEnumObj interface
• class IItemObj in iitemenum.h—IItemObj interface
• class IDsAxes in idsaxess.h—Gateway interface
a. To direct your Developer Studio to the Include directory, click the Project menu and select the
Settings menu item.
b. From the resulting dialog, click the C++ tab and select the Preprocessor category.
c. In the field labeled Additional Include directories, enter the pathname of the directory of your
DSClient Include.
d. In the source files that uses a DSClient class, include the appropriate Include file from the
above list.
2. Add the corresponding stub code to your project. This code resides in your application's
executable file and provides the necessary instructions to get from a local C++ call in your code to
the actual COM object that implements the call. The following classes are implemented in these
stubs:
• class IServer in idssvrmap.cpp—Server interface
• class IStore in idssvrmap.cpp—Store interface
• class IWizard in idssvrmap.cpp—Wizard interface
• class IBrowser in idssvrmap.cpp—Browser interface
• class IEnumObj in iitemenum.cpp—IEnumObj interface
• class IItemObj in iitemenum.cpp—IItemObj interface

DocuShare Windows Client SDK 2–75

Accessing the DocuShare objects using C++ SDK Programming

• class IDsAxes in idsaxess.cpp—Gateway interface

a. To add a stub to your project, click the Project menu and drag to the cascading menu Add to
Project.
b. Select the menu called Files.... The resulting dialog should be called Insert Files into
Project.
c. Use this dialog to select the appropriate stub file from the above list and insert it into your
project.
This does not move the file, but configures your project so that it points to the Include directory to
which the file was installed.
The advantage of this mechanism is that you do not create copies of the client Include and Stub files. This
might be useful if you have a large number of applications that use all these interfaces. The disadvantage
is that you must have the Include file present in your Include path in order to compile your application. The
Include path must be the same for each developer working on your application.

2.16.2 Generating Your Own Includes and Stubs

The installed client toolkit include Type Libraries that describe the COM interfaces to the DSClient objects.
Type libraries reside in the DSClient directory: \Program Files\Xerox\DSClient

The following classes are available from the Type library files:

• class IServer in DsSvrMap.tlb—Server interface

• class IStore in DsSvrMap.tlb—Store interface
• class IWizard in DsSvrMap.tlb—Wizard interface
• class IBrowser in DsSvrMap.tlb—Browser interface
• class IEnumObj in Itemenum.tlb—IEnumObj interface
• class IItemObj in Itemenum.tlb—IItemObj interface
• class IDsAxes in Dsaxess.tlb—Gateway interface
You can access these classes by means of the MFC Class Wizard.

To start the class wizard

1. Press Ctrl+W, or click View.

2. Select Class Wizard.
3. On the Class Wizard dialog, click Add Class.
4. On the popup menu, select From a type library.... A file chooser dialog displays.
5. In the dialog window, navigate to where you have installed DSClient and select the TLB files from
the above list of choices.
The advantage of this mechanism is that your application is self-contained. When you select a TLB file,
MFC automatically creates an Include and .CPP file with the stubs and stub definition and inserts these
files into your application. This can be considered a disadvantage if you have a large number of
applications that use these interfaces since there could be a large number of identical copies of the Include
and stub files.

2–76 DocuShare Windows Client SDK

SDK Programming Event handling

2.17 Event handling

The gateway object implements an event notification service. By subscribing to this service, a client
application can receive notification of the following gateway events:

• Connect—connection to a web server was created

• Connect Complete—the web server was contacted
• Receive—the gateway has received a data packet from the server
• Send—the gateway has sent a data packet to the server
• Close—the network connection was closed
Your application may use the notification service to update the form displayed in the foreground while the
network call completes in the background. Should the end user elect to cancel the on-going call, such as
selecting a cancel button, your application can decide whether to cancel the network call or not. An event
of Connect Complete, Receive, or Send is accompanied with a cancel flag. If the application sets the flag,
the gateway aborts the network call.

To subscribe to this service, your application must implement the DDsAxessEvents event Sink interface.
The Gateway Type library defines the Sink interface. For a compiled Visual Basic application, this is
equivalent to declaring a form class and defining and implementing event handlers for the events fired by
the gateway object. An interpreted VB application, such as a VBScript application, does not correctly
interface with the gateway's connection point, therefore cannot use the notification service. For a C++
application, the subscription is accomplished by performing the standard connection point query, OLE
Automation.

2.17.1 Event handling in Visual Basic application

Here is a skeletal implementation of a Visual Basic form with event handlers for the gateway events.

Private gateway As DsAxess.Handler

Private WithEvents mDsAxess As DsAxess.Handler
Private Sub UserForm_Initialize()
Set gateway = server.Open
Set mDsAxess = gateway
&ldots;
End Sub
Private Sub mDsAxess_Connect(ByVal Data As Long)
&ldots;
End Sub
Private Sub mDsAxess_ConnectComplete(Cancel As Boolean)
&ldots;
End Sub
Private Sub mDsAxess_Receive(ByVal dataSize As Long, ByVal BytesReceived As
Long, Cancel As Boolean)
&ldots;
End Sub

DocuShare Windows Client SDK 2–77

Event handling SDK Programming

Private Sub mDsAxess_Send(ByVal dataSize As Long, ByVal BytesSent As Long,

Cancel As Boolean)
&ldots;
End Sub
Private Sub mDsAxess_Close(ByVal status As Long, ByVal error As Long)
&ldots;
End Sub
Typically, the form initialization routine resets the progress display (progress bar), and your event handlers
update the display whenever a gateway event is fired. See the source code for the Visual Basic sample
program, DSClient3/SDK/Samples/VB/Basics/NotifTestDlg, for more details.

2.17.2 Event Handling in C++

This section applies to C++ programs that use the DocuShare SDK programming interface. By
implementing a DocuShare Event Notification interface, an application receive callbacks while various
SDK calls are in progress. For example, using this programming model, an application can request a file to
be uploaded using the standard SDK Gateway API. The application receives numerous callbacks from the
SDK runtime libraries that provide the progress of the upload operation and the number of bytes that was
moved.

An advanced application can use the Event Notification mechanism to implement progress dialogs that
allow long operations to be canceled, or it could use Event Notification to simply log the state of an
operation.

The DocuShare SDK provides both the Item Object interface (see the class IItemObj) and the Gateway
interface (see the class IDsAxes) for similar operations. The IItemObj operations are simpler to use and
are synchronous, sometimes providing their own progress indicators. This interface is recommended for
most C++ and Visual Basic applications. The IItemObj interface, however, does not support Event
Notification usage. As a consequence, the event notification mechanism described in this document
applies only to functionality provided by the Gateway interface.

2.17.3 Implementing the DIID_DDsAxessEvents Interface

In order to receive gateway events, an application must provide an object that implements the
DIID_DDsAxessEvents interface and properly register that object with the gateway object. The remainder
of this section describes how this is done using MS Developer Studio 6.0.

void OnClose(long status, long error);

void OnConnect(long dataType);
void OnConnectComplete(BOOL FAR* cancel);
void OnReceive(long dataSize, long bytesReceived, BOOL FAR* cancel);
void OnSend(long dataSize, long bytesSent, BOOL FAR* cancel);
These methods are implemented by your application and are called by the DocuShare SDK Gateway
object.

2–78 DocuShare Windows Client SDK

SDK Programming Event handling

Here is an example application that logs into a server and uploads a file.

// Initialize a server object and tell it where to find DocuShare

IServer server;
if (! server.CreateDispatch( "DSServerMap.Server" ) )
return;
server.SetDocuShareAddress( "http://pounce.xsoft.pa.xerox.com/");
// Assure that the user is logged on.
if ( !server.Logon() )
{
AfxMessageBox( "Couldn't log in!" );
return;
}
// Attach a gateway object to the server and upload a file
IDsAxes gateway;
gateway.AttachDispatch( server.Open() );
long ret = gateway.InitiateUpload( 0, 14, "C:\\memos\\1115.txt", "My Uploaded
File", "My Title", "This is the summary of my document", "This is the
Abstract of my document", "Keyword", "John Doe", "", "", "","" );
if ( ret == 0 )
ret = gateway.AwaitCompletion();
To implement Event Notification, you must implement a class that exposes the DIID_DDsAxessEvents
interface through COM; add a few lines of code to the example above so after the call to
gateway.InitiateUpload, your event handler is called.

WIth event notification implemented, the gateway.AwaitCompletion call is not necessary. Provided that the
scope for the gateway instance continues to be valid, your application can do another task and let the
event handler respond to the network progress asynchronously. When the event handler is notified of the
Close event, the application resumes the upload processing for anything that needs to be done after the
file is successfully uploaded.

To implement the class, in the menu New Class&ldots on your main Developer Studio toolbar, select
Insert. The class should derive from CCmdTarget and support Automation. The name of the class is
MyEventHandler. This class must support the five methods of the DIID_DDsAxessEvents interface listed
previously.

To add these methods

1. Open the class wizard and click the Automation tab on the resulting dialog.
2. Click Add Method and add the five methods in the order as listed previously.

NOTE: Be careful to enter the parameter types correctly.

DocuShare Windows Client SDK 2–79

Event handling SDK Programming

The resulting dialog should look like this:

static const IID IID_IMyEventHandler = { 0x3471a966, 0xa813, 0x11d3, { 0xa6,

0x1c, 0x0, 0x10, 0x5a, 0x12, 0xa0, 0xdc } };
BEGIN_INTERFACE_MAP(MyEventHandler, CCmdTarget)
INTERFACE_PART(MyEventHandler, IID_IMyEventHandler, Dispatch)
END_INTERFACE_MAP()
As a result of this dialog, the Developer Studio generates code to expose your C++ class to COM. To allow
your class to expose the DIID_DDsAxessEvents interface, change the following lines of code (new code in
red):

//static const IID IID_IMyEventHandler = { 0x3471a966, 0xa813, 0x11d3, {

0xa6, 0x1c, 0x0, 0x10, 0x5a, 0x12, 0xa0, 0xdc } };
BEGIN_INTERFACE_MAP(MyEventHandler, CCmdTarget)
INTERFACE_PART(MyEventHandler, DIID_DDsAxessEvents, Dispatch)
END_INTERFACE_MAP()
In the above change, the declaration of the GUID for this class is commented out. The new interface does
not expose a unique interface. Note that your GUID differs from the one in the above example. The main
change is to modify IID_ImyEventHandler as the exposed interface to DIID_DDsAxessEvents. This
allows COM to return a pointer to your class when the SDK gateway object does a QueryInterface for the
DIID_DDsAxessEvents interface. You need to include the DsAxessEvents.h file to get the definition of this
GUID.

Before using this notification class, you need to connect it to your gateway object. In steps that are
modeled after the Subscribe and Unsubscribe model of OLE Event Sinks, these two server methods can
be added to your class.

BOOL MyEventHandler::Subscribe(IDsAxes& gateway)

{
ASSERT(gateway.m_lpDispatch);
HRESULT hr = gateway.m_lpDispatch->QueryInterface( IID_IUnknown,
(LPVOID*)&m_punkSrc );
ASSERT(hr == S_OK);
LPUNKNOWN punkSink = GetIDispatch(FALSE);
ASSERT(punkSink);
// Connect to gateway's connection point.
BOOL success = AfxConnectionAdvise( m_punkSrc, DIID_DDsAxessEvents,
punkSink,
TRUE, &m_dwCookie );
return success;
}
void MyEventHandler::Unsubscribe()
{
if (!m_dwCookie)

2–80 DocuShare Windows Client SDK

SDK Programming Event handling

return;
ASSERT(m_punkSrc);
TRY {
LPUNKNOWN punkSink = GetIDispatch(FALSE);
ASSERT(punkSink);
// Disconnect.
BOOL success = AfxConnectionUnadvise( m_punkSrc, DIID_DDsAxessEvents,
punkSink, TRUE, m_dwCookie );
// Release IE.
m_punkSrc->Release();
}CATCH_ALL(e) {
char szError[256];
e->GetErrorMessage(szError, sizeof(szError));
e->Delete();
CString strText;
strText.Format("The program encountered an error while closing gateway
connection.\n\nError: %s", szError);
AfxMessageBox(strText);
}END_CATCH_ALL
m_dwCookie = 0;
}
You need to add these declarations and the following private data to hold the information that is obtained
prior to the call AfxConnectionAdvise and needed for AfxConnectionUnadvise.

private:
DWORD m_dwCookie;
LPUNKNOWN m_punkSrc;
In order to compile the declaration that uses the IDsAxess interface, you need to include idsaxess.h. In
order to compile the calls to AfxConnectionAdvise and AfxConnectionUnadvise, you need to include
afxctl.h.

The remaining changes to your source file are to add code that is called during an event.

// MyEventHandler message handlers

void MyEventHandler::OnClose(long status, long error)
{
// TODO: Add your dispatch handler code here
}
void MyEventHandler::OnConnect(long dataType)
{
// TODO: Add your dispatch handler code here
}

DocuShare Windows Client SDK 2–81

Event handling SDK Programming

void MyEventHandler::OnConnectComplete(BOOL FAR* cancel)

{
// TODO: Add your dispatch handler code here
}
void MyEventHandler::OnReceive(long dataSize, long bytesReceived, BOOL FAR*
cancel)
{
// TODO: Add your dispatch handler code here
}
void MyEventHandler::OnSend(long dataSize, long bytesSent, BOOL FAR* cancel)
{
// TODO: Add your dispatch handler code here
}
Implementating these methods could make use of a pointer to a progress dialog box or log information to a
log file. It is with these functions that you use to respond to events sent by the SDK.

In your application, such as in the OnCreate for your main window, you need to instantiate an event
handler object.

// Instantiate the event sink object to receive notifications from gateway.

CRuntimeClass* pRuntimeClass = RUNTIME_CLASS( MyEventHandler );
CObject* pProxy = pRuntimeClass->CreateObject();
eventHandler = ( MyEventHandler * ) pProxy;
For this example, the pointer to the event handler is kept in eventHandler.

You need to hook up the event handler to your gateway object by adding the following line of code to the
example code above.

eventHandler ->Subscribe( gateway );

Make the above call before the InitiateUpload call is made on the gateway. After the AwaitCompletion call,
make this call to stop receiving notification.

eventHandler ->Unsubscribe();
In a more typical application, the gateway object remains alive for the duration of the application, and the
event handler remains attached to it.

2–82 DocuShare Windows Client SDK

 DSGateway Library
This chapter contains the following:

• Object model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–2

• Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–4
• Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–222
• Submit method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–225
• Non-file object creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–234
• Compound document support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–237

DocuShare Windows Client SDK 3–1

Object model DSGateway Library

3.1 Object model

Method or property used to derive

DSGatewayLib an object precedes the name of
the object in italics.

GatewayHandler

GatewayClient
GatewayClient

GatewaySettings
GatewaySettings

ErrorReportObject
ErrorReportObj

NameConflictResolver
NameConflictResolver

StatusObject
(StatusObj)

QueriedProperties
PropertyIDs

PropertyID
PropertyID

DSAccessData
DSAccessData

Server
DSServerMap.Server

ClientRequest
ClientRequest

ContentData
ContentData

3–2 DocuShare Windows Client SDK

DSGateway Library Object model

Object model continue

ServerResponse
ServerResponse

ContentData
ContentData

ItemDescriptorArray
ItemDescriptorArray

ItemProperties
ItemProperties

ItemProperty
ItemProperty

ItemObject
ItemObj

Enumerator
EnumObj

Stream
IStream

XMLDOM
XMLDOMDocument

SearchRequest

QueriedProperties
PropertyIDs

SearchTermsCollection
SearchTermsCollection

Terms
SearchTerms

Term
SearchTerm

DocuShare Windows Client SDK 3–3

Objects DSGateway Library

3.2 Objects
3.2.1 GatewayHandler
List of GateHandler methods and properties

Methods Properties

AwaitCompletion DSCollHandle

Cancel DSContainerHandle

ClearCollectionCache DSContent

DoLoginDialog DSCreatedTimeFrom

Download DSCreatedTimeTo

GetAuthToken DSDisplayName

GetItemProplds DSFileHandle

GetLastError DSFileName

GetMode DSFileType

GetProps DSHandle

GetStatus DSHandleList

GetTransferInfo DSItemListFile

GoOffline DSItemProp

GoOnline DSKeywords

InitiateBulkDownload DSMaxItems

InitiateBulkReplicate DSModifiedTimeFrom

InitiateBulkUpload DSModifiedTimeTo

InitiateCollectionCreate DSObjectHandle

InitiateCollectionOpen DSObjectTypeNum

InitiateContainerOpen DSKeywords

InitiateCopy DSOwner

InitiateCreateObject DSTime

InitiateDelete DSVersion

InitiateDisown LocalTime

InitiateDownload Proplds

InitiateGet PropAttrlds

3–4 DocuShare Windows Client SDK

DSGateway Library Objects

Methods Properties

InitiateHistory

InitiateLock

InitiateMove

InitiatePost

InitiateRename

InitiateSchema

InitiateUserAuth

OpenCollection

OpenContainer

RegisterClient

Search

SetItemProplds

SetMode

SetProps

SetShellNotification

Submit

Upload

Wait

DocuShare Windows Client SDK 3–5

Objects DSGateway Library

3.2.1.1 GatewayHandler methods

This section contains GatewayHandler method definitions.

AwaitCompletion

VB AwaitCompletion() as Long

C++ long AwaitCompletion();

The AwaitCompletion method waits until the on-going network call completes.

Return value

Value Description

DSAXES_SUCCESS The network call successfully completed.

DSAXES_E_HTTP An HTTP error was encountered. Use

GetLastError to retrieve the error code.

DSAXES_E_WINSOCK A Windows socket error was encountered. Use

GetLastError to retrieve the error code.

DSAXES_E_OPENFILE An upload file cannot be opened.

DSAXES_E_CREATEFILE A download file cannot be created.

Remarks
Should an error occur, DSGateway generates an exception report and displays it in a dialog window. This
takes place before control returns to the caller. The dialog window can be disabled programmatically using
the IDsAxes::SetMode method with the DSAXES_MODE_NOERRORDLG mode flag. By default,
AwaitCompletion causes a progress dialog to run while the ongoing network call completes. To suppress
the progress dialog, use the DSAXES_MODE_SILENT mode flag.

3–6 DocuShare Windows Client SDK

DSGateway Library Objects

Cancel

VB Cancel() as Long

C++ long Cancel();

The Cancel method attempts to cancel a network call in progress.

Parameters
None

Return value
0 always.

Remarks
Depending on the phase of the network call, cancellation may not take effect immediately. For a single task
command such as InitiateDelete, once the request is sent, the server can proceed. Even if the task is
canceled, the task is completed when the request transmission phase is done.

The Cancel method can be used after an SDK application has successfully subscribed to the IDsAxes
event notification service. Some of the events used by IDsAxes, pass a Cancel flag parameter so that the
sink interface can signal cancellation of an ongoing network call without explicitly calling the Cancel
method.

Refer to Event handling on page 2–77 for more information on utilizing IDsAxes events.

DocuShare Windows Client SDK 3–7

Objects DSGateway Library

ClearCollectionCache

VB ClearCollectionCache(nCollHandle as Long, pszServerUrl as String) as Long

C++ long ClearCollectionCache(long nCollHandle, LPCTSTR pszServerUrl);

The ClearCollectionCache method clears the item listing cache of one collection or all collections.

Parameters

Parameter Description

nCollHandle Handle number for a collection whose item listing

cache is to be cleared or -1. If nCollHandle is -1,
all listing cache belonging to the server specified
by pszServerUrl, is cleared.

pszServerUrl Optional address of a DocuShare server URL

string.

Return value

Value Description

DSAXES_SUCCESS The cache was successfully cleared.

DSAXES_E_FAIL The cache directory was not found.

DSAXES_E_SYSRES A listings enumerator could not be allocated.

Remarks
DSGateway caches a generated item listing per collection and per user account. A cached listing expires
in a prescribed time; the default is 5 minutes. The cache can be disabled by clearing the
DSAXES_MODE_ENABLECACHE flag. The cache expiration time is loaded from the system registry. See
SetMode on page 3–71 for details.

This method deletes all listings associated with the specified collection. There can be more than one listing
per collection, because more than one user may be connected to a collection. A different user generates a
different item listing.

If the home URL of the server is http://docushare.xyz.com/, the pszServerUrl parameter points to the URL.
If this parameter is empty, the value from the previous command is used.

3–8 DocuShare Windows Client SDK

DSGateway Library Objects

DoLoginDialog

VB DoLoginDialog() as Long

C++ long DoLoginDialog();

The DoLoginDialog method runs a login dialog and contacts DocuShare for user authentication. A user
can enter an account name, password, server address, and proxy server (optional). Control does not
return until authentication completes.

Parameters
None

Return value

Value Description

DSAXES_SUCCESS The user has successfully logged in.

DSAXES_E_CANCEL The operation was canceled by the user.

DSAXES_E_BADPARAM An unsupported protocol scheme was detected.

DSAXES_E_BUSY A network access is in progress.

Remarks
Following a successful login, you can call GetAuthToken to retrieve authentication credentials for the user.
This method internally calls InitiateUserAuth for dispatching the login command. Use the SetMode method
with DSAXES_MODE_ENABLEXML to elect the XML Login command.

Use the DSAXES_MODE_USEPROXY mode flag to enable editing the proxy address. The following script
uses the flag to permit editing a proxy server address in the login dialog.

curMode = gateway.SetMode(DSAXES_MODE_USEPROXY, DSAXES_MODE_USEPROXY)

status = gateway.DoLoginDialog()

DocuShare Windows Client SDK 3–9

Objects DSGateway Library

Download

VB Download(flags As Long, pItemDisp As Object, pFileName As String) As Long

C++ long Download(long flags, LPDISPATCH pItemDisp, LPCTSTR pFileName);

The Download method downloads a file or collection to the specified path.

Parameters

Parameters Description

DSAXES_FLAG_DOWNLOADLOCKED Locks the file to be downloaded.

pItemDisp Dispatch interface pointer for an ItemObj that

represents the file or collection to be downloaded.

pFileName An optional pathname for the file or collection to

be downloaded.

Return value

Value Description

DSAXES_SUCCESS A request for downloading an object was

successful.

DSAXES_E_BUSY A network call is in progress.

DSAXES_E_BADPARAM A parameter is not complete or the correct type.

Remarks
The Download method downloads the file or collection represented by the ItemObj interface for pItemDisp.
Download requires setting the following ItemObj properties to valid values.

ItemObjProperty Value

Handle DocuShare handle.

Name Filename stored in DocuShare.

Title Display name stored in DocuShare.

Instead of setting the Handle property, an application can separately set HandleNum and TypeNum with
numeric identifiers. If parameter pFileName is empty, the method regards the ItemObj.Name value as the
fully qualified pathname for a file or folder to be downloaded to the target file or collection. If pFileName
and ItemObj.Name are both empty, error DSAXES_E_BADPARAM is raised.

For a collection download, the DSHandleList property holds a list of files and folders downloaded to the
client machine.

3–10 DocuShare Windows Client SDK

DSGateway Library Objects

The Download method by default does not return until the network call completes. Use the
DSAXES_MODE_ASYNCHRONOUS mode flag to cause the method call to return immediately. Refer to
Event handling on page 2–77 for how to receive event notification from the IDsAxes interface.

DocuShare Windows Client SDK 3–11

Objects DSGateway Library

GetAuthToken

VB GetAuthToken(pAuthToken as String, pUserId as Long) as Long

C++ long GetAuthToken(BSTR* pAuthToken, long* pUserId);

The GetAuthToken retrieves user credentials generated by a DocuShare server in response to a call to
InitiateUserAuth or DoLoginDialog.

Parameters

Parameter Description

pAuthToken Address of a BSTR buffer receiving an

authentication token. If pAuthToken contains a null
pointer, the method allocates memory and copies
the authentication token. If pAuthToken contains
the address of a pre-allocated buffer, the buffer
must be at least DSAXES_MAX_AUTH_LEN
characters long.

pUserId Address of a variable receiving a user handle for a

valid authentication token.

Return value

Value Description

DSAXES_SUCCESS A user was successfully authenticated, and the

authentication token and user handle were copied
to the buffers.

DSAXES_E_LOGIN The operation failed due to a general login failure.

Remarks
The caller needs to free the allocated buffer in pAuthToken using the Win32 SysFreeString function. In the
following sample, the code:

• calls GetAuthToken
• displays the obtained authentication and user handle
• frees the authentication buffer using SysFreeString
IDsAxes gateway;
...
BSTR bsAuthToken = NULL;
long lUserId = 0;
long status = gateway.GetAuthToken( &bsAuthToken, &lUserId );
if ( status == 0 )

3–12 DocuShare Windows Client SDK

DSGateway Library Objects

{
CString strAuthToken( bsAuthToken );
printf( "AuthToken: %s\n", (LPCTSTR)strAuthToken );
printf( "User ID: %u\n", lUserId );
SysFreeString( bsAuthToken );
}

DocuShare Windows Client SDK 3–13

Objects DSGateway Library

GetItemProplds

VB GetItemPropIds(nItemType As Long) As Long

C++ long GetItemPropIds(long nItemType);

The GetItemPropIds method returns the current property ID flags for property query and modification of a
DocuShare object type.

Parameters
nItemType—to get the property IDs for the object type. The following flags are used to designate the item
type.

Flag Description

DSXITEMTYPE_COLLECTION Get the property IDs for a collection.

DSXITEMTYPE_DOCUMENT Get the property IDs for a document.

DSXITEMTYPE_VERSION Get the property IDs for a particular version of a

document.

DSXITEMTYPE_CALENDAR Get the property IDs for a calendar object on a

DocuShare server.

DSXITEMTYPE_BBOARD Get the property IDs for a bulletin board object on

a DocuShare server.

DSXITEMTYPE_URL Get the property IDs for a designated URL object

on a DocuShare server.

DSXITEMTYPE_SAVEDQUERY Get the property IDs for a saved query on a

DocuShare server.

DSXITEMTYPE_USER Get the property IDs for a user.

DSXITEMTYPE_GROUP Get the property IDs for a user group on a

DocuShare server.

Return value
The GetItemPropIds method returns a combination of property ID flags. The exact number of flags depend
on the item type passed. See SetItemProplds on page 3–68 for a list of property ID flags.

3–14 DocuShare Windows Client SDK

DSGateway Library Objects

GetLastError

VB GetLastError() as Long

C++ long GetLastError();

The GetLastError method retrieves the error code for the last encountered error.

Parameters
None

Return value
The last error code.

Remarks
The status code returned by GetStatus and other IDsAxes methods identifies the error category, such as
HTTP error and Winsock error. The error code returned by this method identifies a specific error type within
the category.

Common HTTP result codes:

200 HTTP_OK

201 HTTP_CREATED

202 HTTP_ACCEPTED

203 HTTP_NON_AUTHORITATIVE_INFO

204 HTTP_NO_CONTENT

207 HTTP_MULTI_STATUS

300 HTTP_MULTIPLE_CHOICE

301 HTTP_MOVED_PERMANENTLY

302 HTTP_MOVED_TEMPORARILY

303 HTTP_SEE_OTHER

304 HTTP_NOT_MODIFIED

400 HTTP_BAD_REQUEST

401 HTTP_NOT_AUTHORIZED

402 HTTP_PAYMENT_REQUIRED

403 HTTP_FORBIDDEN

404 HTTP_NOT_AVAILABLE

405 HTTP_NOT_SUPPORTED

406 HTTP_NONE_ACCEPTABLE

DocuShare Windows Client SDK 3–15

Objects DSGateway Library

407 HTTP_PROXYAUTHREQUIRED

408 HTTP_REQUEST_TIMEOUT

409 HTTP_CONFLICT

410 HTTP_GONE

411 HTTP_AUTHORIZATION_REFUSED

500 HTTP_INTERNALSERVERERROR

501 HTTP_NOT_IMPLEMENTED

502 HTTP_BADGATEWAY

503 HTTP_MAXCONNECTS

504 HTTP_GATEWAYTIMEOUT

Windows socket error codes*:

WSAEINTR

WSAEBADF

WSAEACCES

WSAEFAULT

WSAEINVAL

WSAEMFILE

WSAEWOULDBLOCK

WSAEINPROGRESS

WSAEALREADY

WSAENOTSOCK

WSAEDESTADDRREQ

WSAEMSGSIZE

WSAEPROTOTYPE

WSAENOPROTOOPT

WSAEPROTONOSUPPORT

WSAESOCKTNOSUPPORT

WSAEOPNOTSUPP

WSAEPFNOSUPPORT

WSAEAFNOSUPPORT

3–16 DocuShare Windows Client SDK

DSGateway Library Objects

WSAEADDRINUSE

WSAEADDRNOTAVAIL

WSAENETDOWN

WSAENETUNREACH

WSAENETRESET

WSAECONNABORTED

WSAECONNRESET

WSAENOBUFS

WSAEISCONN

WSAENOTCONN

WSAESHUTDOWN

WSAETOOMANYREFS

WSAETIMEDOUT

WSAECONNREFUSED

WSAELOOP

WSAENAMETOOLONG

WSAEHOSTDOWN

WSAEHOSTUNREACH

WSAENOTEMPTY

WSAEPROCLIM

WSAEUSERS

WSAEDQUOT

WSAESTALE

WSAEREMOTE

WSAEDISCON

WSANOTINITIALISED

WSASYSNOTREADY

WSAVERNOTSUPPORTED

WSAHOST_NOT_FOUND

WSATRY_AGAIN

DocuShare Windows Client SDK 3–17

Objects DSGateway Library

WSANO_RECOVERY

WSANO_DATA

Operating system error codes*:

ERROR_FILE_NOT_FOUND

ERROR_PATH_NOT_FOUND

ERROR_TOO_MANY_OPEN_FILES

ERROR_ACCESS_DENIED

ERROR_NOT_ENOUGH_MEMORY

ERROR_OUTOFMEMORY

ERROR_WRITE_PROTECT

ERROR_SECTOR_NOT_FOUND

ERROR_READ_FAULT

ERROR_GEN_FAILURE

ERROR_SHARING_VIOLATION

ERROR_LOCK_VIOLATION

ERROR_NETWORK_BUSY

ERROR_NETWORK_ACCESS_DENIED

ERROR_FILE_EXISTS

ERROR_INVALID_PARAMETER

ERROR_FILENAME_EXCED_RANGE

ERROR_DISK_OPERATION_FAILED

ERROR_INVALID_DRIVE

ERROR_MEDIA_CHANGED

ERROR_DRIVE_LOCKED

ERROR_NOT_DOS_DISK

ERROR_NOT_READY

ERROR_DISK_FULL

* Refer to Windows documentation for the numeric values.

3–18 DocuShare Windows Client SDK

DSGateway Library Objects

GetMode

VB GetMode() as Long

C++ long GetMode();

The GetMode method retrieves the current state of all the mode flags.

Parameters
None

Return value
The current state of the following mode flags:

DSAXES_MODE_SILENT

DSAXES_MODE_USEPROXY

DSAXES_MODE_USEMIMETYPE

DSAXES_MODE_ADDDSCGI

DSAXES_MODE_MEMORIZEUSER

DSAXES_MODE_VIRTUALROOT

DSAXES_MODE_ENABLECACHE

DSAXES_MODE_ENABLEXML

DSAXES_MODE_DNLDNAMECLASHPROMPT

DSAXES_MODE_UPLDNAMECLASHPROMPT

DSAXES_MODE_UPLDALWAYSASNEWDOC

DSAXES_MODE_SAVESETTINGS

DSAXES_MODE_AUTOUPLOAD

DSAXES_MODE_READONLY

Remarks
To learn the state of a particular flag, use a bitwise AND.

The DSAXES_MODE_READONLY flag is set when the DocuShare server is in read-only mode, such as
server maintenance. This information is collected whenever the top-level collections are enumerated, as
when OpenCollection(0) is called. IDsAxes does not use this status information internally. Therefore, if you
attempt to upload a file with this flag set, IDsAxes forwards your request but will fail if the server is still in a
read-only state. You can turn off the read-only query by specifying the
DSAXES_MODE_NOSERVERSTATUSQUERY mode flag prior to calling OpenCollection or
IntiateCollectionOpen.

See the flag description for SetMode on page 3–71 for the other flags.

DocuShare Windows Client SDK 3–19

Objects DSGateway Library

GetProps

VB GetProps(fPropIds as Long pItemDisp as Object, pszPropNames as String) as

Long

C++ long GetProps(long fPropIdsCore, long fPropIds, LPDISPATCH pItemDisp);

The GetProps method retrieves property values for a given DocuShare object and places them into the
given IItemObj object. The caller specifies the standard and custom properties to retrieve.

Parameters

Parameter Description

fPropIds OR propId flags (DSAXES_PROPID_*) indicate

which properties to retrieve. To request a custom
property, the caller must set
DSAXES_PROPID_CUSTOM and pass the name
of the custom property in the pszPropNames
parameter.

pItemDisp An IItemObj object identifying the source

DocuShare object. Set the TypeNum and
HandleNum properties for the item to the source
DocuShare object. Upon return, the IItemObj is
populated with the retrieved properties.

pszPropNames A list of custom property names separated by

single blank characters. If
DSAXES_PROPID_CUSTOM is not set in
fPropIds, this parameter is ignored.

Return value

Value Description

DSAXES_SUCCESS The item properties were successfully obtained.

DSAXES_E_FAIL The network call failed. Call GetStatus to obtain

the status code. Call GetLastError to find the error
code.

DSAXES_E_BUSY A network call is in progress.

Remarks
Existing properties is preserved in the source, IItemObj, unless they are replaced by the retrieved
properties.

This method is synchronous.

3–20 DocuShare Windows Client SDK

DSGateway Library Objects

GetStatus

VB GetStatus() as Long

C++ long GetStatus();

The GetStatus method retrieves the gateway status. The status is returned as a success or failure code.

Parameters
None

Return value

Value Description

DSAXES_SUCCESS A task successfully completed.

DSAXES_INPROG A network call is in progress.

DSAXES_E_WINSOCK A Windows socket error was encountered.

DSAXES_E_HTTP An HTTP error was encountered.

Remarks
GetStatus returns the success or failure code as a general status. For a detailed error code call refer to
GetLastError on page 3–15.

DocuShare Windows Client SDK 3–21

Objects DSGateway Library

GetTransferInfo

VB GetTransferInfo(pBytes as Long, pPercent as Long) as Long

C++ long GetTransferInfo(long* pBytes, long* pPercent);

The GetTransferInfo method retrieves data transfer statistics.

Parameters

Parameter Description

pBytes Address of a variable receiving the byte count of

the transfered data.

pPercent Address of a variable receiving the percent

completed.

Return value
The return value is the transaction handle generated by DocuShare. Upon completion of a request
process, DocuShare sends as part of its response, a header entitled DocuShare-handle. DSAXESS keeps
the value given in this header. For example, successful downloading of a file sets this field to the file handle
of the file. Also, successful uploading sets this field to a generated file handle for the uploaded file.

Remarks
Refer to DSHandle on page 3–87 for a description of the DocuShare transaction handle.

Rather than using GetTransferInfo, it is recommended that an SDK application subscribes to the event
notification service of IDsAxes. As network events occur, progressive data transfer information is
forwarded to the application as parameters of events.

3–22 DocuShare Windows Client SDK

DSGateway Library Objects

GoOffline

VB GoOffline( Flags as optional Variant, PromptMessage as optional Variant,

PromptTitle as optional Variant) as Long

C++ long GoOffline(VARIANT* Flags, VARIANT* PromptMessage, VARIANT*

PromptTitle);

GoOffline disconnects a remote connection established by GoOnline.

Parameters

Parameter Description

Flags Optional; contains DSXDIALUP flag settings. If

this is not specified, flag settings loaded from the
system registry are used.

PromptMessage Optional; displays a message in a box for

disconnect confirmation if
DSXDIALUP_DISCONNECT_ASK is enabled. A
default message is displayed if PromptMessage is
empty

PromptTitle Optional; contains a title string for a confirmation

prompt. A default title is used if PromptTitle is
empty.

Return value

Value Description

DSAXES_SUCCESS The remote connection was successfully

disconnected.

DSAXES_E_BADPARAM One or more invalid arguments.

DSAXES_E_CANCEL The user canceled the operation, or an

unrecoverable error occurred.

Remarks
Valid offline control flags are:

• DSXDIALUP_DISCONNECT_NEVER
• DSXDIALUP_DISCONNECT_ASK

DocuShare Windows Client SDK 3–23

Objects DSGateway Library

GoOnline

VB GoOnline(Flags as optional Variant, PromptMessage as optional Variant,

PromptTitle as optional Variant) as Long

C++ long GoOnline(VARIANT* Flags, VARIANT* PromptMessage, VARIANT*

PromptTitle);

Establishes a connection to a network using Windows Remote Access Service (RAS).

Parameters

Parameter Description

Flags Optional; contains DSXDIALUP flag settings. If

this is not specified, flag settings loaded from the
system registry are used. DSXDIALUP flags are
defined in C header file DSClient.h. See
Remarks.

PromptMessage Optional; displays a message in a box for dialup

confirmation if DSXDIALUP_CONNECT_ASK is
enabled. A default message is displayed if
PromptMessage is empty.

PromptTitle Optional; contains a title string for a confirmation

prompt. A default title is used if PromptTitle is
empty.

Return value

Value Description

DSAXES_SUCCESS A remote connection was successfully

established.

DSAXES_E_BADPARAM One or more invalid arguments.

DSAXES_E_CANCEL The user canceled the connection, or an

unrecoverable error occurred.

Remarks
The Flags parameter may contain the following control flags:

• DSXDIALUP_FORCE_DIAL
• DSXDIALUP_CHECK_NETWORK_FIRST
• DSXDIALUP_SKIP_RETEST
• DSXDIALUP_CONNECT_BYURL
• DSXDIALUP_CONNECT_UNATTENDED
• DSXDIALUP_CONNECT_ASK

3–24 DocuShare Windows Client SDK

DSGateway Library Objects

• DSXDIALUP_CHECK_NETWORK_LATER
• DSXDIALUP_IGNORE_LAN
• DSXDIALUP_DISCONNECT_NEVER
• DSXDIALUP_DISCONNECT_ASK
DSXDIALUP_DISCONNECT_NEVER and DSXDIALUP_DISCONNECT_ASK are used by GoOffline.

A gateway instance loads default DSXDIALUP flags from the registry entry.

[HKCU\Software\Xerox\DocuShare Client\DsAxess\Settings]
DialUpFlags=dword:xxxxxxxx
If the entry does not exist, the following DSXDIALUP flags are enabled:

• DSXDIALUP_CONNECT_ASK
• DSXDIALUP_SKIP_RETEST
• DSXDIALUP_CHECK_NETWORK_FIRST
• DSXDIALUP_FORCE_DIAL
• DSXDIALUP_DISCONNECT_NEVER

DocuShare Windows Client SDK 3–25

Objects DSGateway Library

InitiateBulkDownload

VB InitiateBulkDownload( nCollHandle as Long, nItemCount as Short, pItemList as

Variant, pszDownloadPath as String, pszServerUrl as String, pszAuthToken as
String, pszProxyServer as String) as Long

C++ long InitiateBulkDownload(long nCollHandle, short nItemCount, VARIANT*

pItemList, LPCTSTR pszDownloadPath, LPCTSTR pszServerUrl, LPCTSTR
pszAuthToken, LPCTSTR pszProxyServer);

The InitiateBulkDownload method downloads multiple files from a DocuShare collection. If a collection is in
the list, a directory is created in the client machine before the member files are downloaded.

Parameters

Parameter Description

nItemCount Number of items in the pItemList list. Set this

parameter to zero to have the method count the
items specified in pItemList; or set pItemList to -1
to designate that pItemList contains a file pattern.
See Remarks for information.

pItemList Address of a variant containing an array of item

descriptors, each describing a file or collection to
download. This variant parameter can contain a
list of item handles and names in textual
representation instead of a descriptor array. See
Remarks for details.

pszDownloadPath Base path where downloaded items are placed.

pszServerUrl, pszAuthToken, pszProxyServer Server access information. These parameters

may be empty. If empty, the method uses the
access information from a previous call to
InitiateUserAuth, DoLoginDialog, InitiateSetProps
(with object type DSXOBJTYPE_GATEWAY), or
any network access methods which accept server
access parameters.

Return value

Value Description

DSAXES_SUCCESS The download sequence successfully started.

DSAXES_E_BADDIR A temporary work directory could not be created.

DSAXES_E_BADPARAM pItemList does not have an acceptable data type

(VT_BSTR or VT_ARRAY).

3–26 DocuShare Windows Client SDK

DSGateway Library Objects

Remarks
Parameter pItemList can contain either a binary array of DocuShare item descriptors (VT_ARRAY) or a
string list of file/collection handles and display names (VT_BSTR).

To generate a descriptor array, an application can use the ItemObj.GetPropStruct method and obtain a
descriptor structure for each item to be downloaded. The array is constructed by simply stacking the
descriptor structures one after another and terminate with a NULL (32-bit) integer. The first integer entry of
an item descriptor contains the byte length of the descriptor structure. The method computes the offset to
the next structure in the array by looking at the integer entry of the current structure. When the NULL
integer entry is reached, the method knows that it has reached the end of the array. The array must be
allocated as a contiguous block of memory of type SAFEARRAY. The p-array member of pItemList is set to
the address of the array. The vt member is set to VT_ARRAY. The caller is responsible for freeing the
array.

This method uses the item length (ItemObj.Length) and modified time (ItemObj.TimeModified) to
determine the need for downloading the latest version of the item from the server. Therefore, if the caller
knows that the download folder already contains the same file that the method call downloads, the caller
should pass the latest file size and modified time. If the version in the server has the same size and time
values, IDsAxes foregoes the download. If no synchronization is required, length and time information is
not needed.

Instead of supplying a descriptor array, an application can supply a textual list of handles and names in
pItemList. The method downloads the files (and collections) whose handles appear in the list. Valid
example lists are:

""File-123,Test document.txt" "Collection-456,My collection""

""File-123 Test document.txt" "Collection-456 My collection""
""[24578 {1/23/1998 8:12:38 PM}]File-123, Test document.txt" "[4 {4/20/1999
10:15:50 AM}]Collection-456, My collection""
A file or collection entry must be enclosed with double quotation marks. Entries are separated by a single
white space character. The optional file size or the collection item count and file time (or the collection's last
modified time) are enclosed in brackets and must precede the file or collection handle.

The array technique is more suitable for a C++ application, while the string list is more suited for a VB
application.

To have the method count the items specified in the pItemList list, the item count parameter, nItemCount, is
set to zero.

To download all files from a collection whose names match a pattern, set nItemCount to -1 and pItemList to
a filename pattern. Valid file patterns are "*.[ext]", where [ext] designates any complete file extension
name. If there are no files whose names match the supplied pattern, the method returns
DSAXES_NOCHANGE.

InitiateBulkDownload is an asynchronous method. Control returns immediately after a socket is opened.

An SDK application can subscribe to the event notification service to be notified when the download
completes. Alternatively, the application can call AwaitCompletion to wait until the download completes.

The following VB script example demonstrates using a file pattern and InitiateBulkDownload to download
all MS Excel files in Collection-10 to the download destination, c:\temp\excel.

DocuShare Windows Client SDK 3–27

Objects DSGateway Library

Dim gateway
Set gateway = CreateObject("DSGateway.GatewayHandler")
Status = gateway.DoLoginDialog
If Status = 0 Then
Status = gateway.InitiateBulkDownload( 10, -1, "*.xls", "c:\temp\excel", "",
"", "" )
If Status = 0 Then
Status = gateway.AwaitCompletion
If Status = 0 Then
MsgBox ("Downloaded file count and handles:" + chr(10) +
gateway.DSHandleList)
End if
End If
End If

3–28 DocuShare Windows Client SDK

DSGateway Library Objects

InitiateBulkReplicate

VB InitiateBulkReplicate( nItemCount as Short, pItemList as Variant, nSrcHandle

as Long, pszSrcServerUrl as String, pszSrcAuthToken as String,
pszSrcProxyAddr as String, nDestHandle as Long, pszDestServerUrl as String,
pszDestAuthToken as String, pszDestProxyAddr as String) as Long

C++ long InitiateBulkReplicate(short nItemCount, VARIANT* pItemList, long

nSrcHandle, LPCTSTR pszSrcServerUrl, LPCTSTR pszSrcAuthToken,
LPCTSTR pszSrcProxyAddr, long nDestHandle, LPCTSTR pszDestServerUrl,
LPCTSTR pszDestAuthToken, LPCTSTR pszDestProxyAddr);

The InitiateBulkReplicate method replicates multiple files between two DocuShare collections. The source
and destination collections may or may not exist in the same server. Collections, if specified in the list, are
replicated as well. A replicated item inherits the standard properties except the owner property, which is set
in the source item.

Parameters

Parameter Description

nItemCount Number of items in the pItemList list. Set this

parameter to zero to have the method count the
items specified in pItemList; or set pItemList to -1
to designate that pItemList contains a file pattern.
Refer to InitiateBulkDownload on page 3–26 for
more information on file pattern usage.

pItemList Address of a variant containing an array of item

descriptors describing each file or collection to
download. This variant parameter may contain a
list of item handles and names in textual
representation instead of a descriptor array. See
InitiateBulkDownload on page 3–26 for details.

nSrcHandle Handle of a DocuShare base collection from which

the replicated files/collection originates. This
parameter is used only for status display
purposes. Set nSrcHandle to zero to designate the
source server home site.

pszSrcServerUrl, pszSrcAuthToken, Source server information.

pszSrcProxyAddr

nDestHandle Handle of a DocuShare base collection in which

the replicated items are placed. nDestHandle
must contain a non-zero value and refers to an
existing collection in the destination server.

pszDestServerUrl, pszDestAuthToken, Destination server information

pszDestProxyAddr

DocuShare Windows Client SDK 3–29

Objects DSGateway Library

Return value

Value Description

DSAXES_SUCCESS The user has successfully logged in.

DSAXES_E_BADDIR A temporary work directory could not be created.

DSAXES_E_BADPARAM Possible errors:

• pItemList->vt is not VT_ARRAY or VT_BSTR
• nSrcHandle, nDestHandle, or nItemCount are invalid
• Space allocation failed in list preprocessor

Remarks
DSAXES_MODE_AUTOUPLOAD can be set by a prior call to SetMode to cause auto termination of the
IDsAxes instance upon completion of the replication sequence. When this mode is specified, the method
increments its reference count so that control returns to the caller and the caller releases the IDsAxes
instance. The IDsAxes instance can continue to exist and complete the replication task in the background
without being attached to the application which called this method. Upon completion of the replication task,
the IDsAxes instance decreases the reference count, thereby terminating itself.

If server access parameters are empty, the method uses the access information from a previous call to
InitiateUserAuth, DoLoginDialog, InitiateSetProps (with object type DSXOBJTYPE_GATEWAY), or any of
the network access methods which accept server access parameters.

InitiateBulkReplicate is an asynchronous method. Control returns after the top-level collection listing is
obtained from the source server. An SDK application can subscribe to the event notification service to be
notified when the task completes. Alternately, the application can call AwaitCompletion to wait until the task
completes.

Upon successful conclusion of the replication, the DSHandleList property contains the count for source
(downloaded) and destination (uploaded) items and a list of their handles. The item count and item
handles are separated with commas and appear in the list in the following pattern:

• item count
• handle of the first downloaded item
• handle of the first uploaded item
• handle of the second downloaded item
• handle of the second uploaded item

3–30 DocuShare Windows Client SDK

DSGateway Library Objects

InitiateBulkUpload

VB InitiateBulkUpload( nCollHandle as Long, nItemCount as Short, pPathList as

Variant, pszServerUrl as String, pszAuthToken as String, pszProxyServer as
String) as Long

C++ long InitiateBulkUpload(long nCollHandle, short nItemCount, VARIANT*

pPathList, LPCTSTR pszServerUrl, LPCTSTR pszAuthToken, LPCTSTR
pszProxyServer);

The InitiateBulkUpload method upload multiple files to a DocuShare collection. If a directory is specified in
the item list, a collection is created in DocuShare before the member files are uploaded.

Parameters

Parameter Description

nCollHandle Handle number of the destination collection to

which files are uploaded.

nItemCount Number of pathnames contained in the pPathList

list.

pPathList Address of a variant containing an array of item

descriptors each describing a file or collection to
upload. This variant parameter can contain a list of
pathnames in textual representation instead of a
descriptor array.

pszServerUrl, pszAuthToken, pszProxyServer Server access information.

Return value

Value Description

DSAXES_SUCCESS The upload sequence successfully started.

DSAXES_E_BUSY A network call is in progress.

DSAXES_E_BADPARAM nItemCount is inconsistent with the list.

DSAXES_NOCHANGE No file items were found in the source directory.

Remarks
nItemCount is set to -1, indicating that the path list contains a single pathname with a file filter ('*' or '?' wild
card). Pre-processing attempts to build a list of top-level filenames by querying files using this file filter. If
the pathname does not contain a wild card and is a straight directory name, the pre-processing builds a list
consisting of all the files and subdirectories found under that directory.

If pPathList contains a BSTR list (pPathList->vt = VT_BSTR) and if nItemCount is set to 0, pre-processing
enumerates the supplied list for doube quotation marks and computes the number of pathnames that are
in the list.

DocuShare Windows Client SDK 3–31

Objects DSGateway Library

If it is a positive number, nItemCount must indicate the exact number of pathnames that are being passed.
The list may contain file and/or directory pathnames. If a directory is specified, a collection with the same
directory name is created in the server and all files and nested subdirectories under the specified directory
are uploaded into the created collection.

If pszServerUrl, pszAuthToken, and pszProxyServer are empty, the values from the previous command are
used. If DoLoginDialog was previously called, the pre-processing method assigns the base URL,
AuthToken, and proxy parameters that the user set during the login dialog.

DSAXES_MODE_AUTOUPLOAD can be set by a prior call to SetMode, causing auto termination of the
gateway at completion of the upload sequence. When this mode is specified, the method increments its
reference count so that control returns to the caller, and the caller releases the IDsAxes instance. The
IDsAxes instance continues to exist and complete the upload task in the background without being
attached to the application which called this method. Upon completion of the task, the IDsAxes instance
decreases the reference count, thereby terminating itself.

InitiateBulkUpload is an asynchronous method. Control returns after a socket is opened. An SDK

application can subscribe to the event notification service to be notified when the task completes.
Alternatively, the application can call AwaitCompletion to wait until the task completes.

Upon successful conclusion of the upload, property DSHandleList contains the uploaded items count and
a list of their handles. The item count and item handles are separated with commas. The handles appear in
the order as the uploaded items.

3–32 DocuShare Windows Client SDK

DSGateway Library Objects

InitiateCollectionCreate

VB InitiateCollectionCreate( nParentHandle as Long, pszTitle as String,

pszSummary as String, pszDescription as String, pszKeywords as String,
pszServerUrl as String, pszAuthToken as String, pszProxyAddr as String) as
Long

C++ long InitiateCollectionCreate(long nParentHandle, LPCTSTR pszTitle,

LPCTSTR pszSummary, LPCTSTR pszDescription, LPCTSTR pszKeywords,
LPCTSTR pszServerUrl, LPCTSTR pszAuthToken, LPCTSTR pszProxyAddr);

The InitiateCollectionCreate method creates a collection in a DocuShare server.

Parameters

Parameter Description

nParentHandle Handle number of a newly created collection.

pszTitle A string that contains the new collection title.

pszSummary A string that contains the new collection summary

text.

pszDescription A string that contains the new collection

description.

pszKeywords A string that contains search keywords for the new

collection.

pszServerUrl, pszAuthToken, pszProxyServer Strings that contain server access information

Return value

Value Description

DSAXES_SUCCESS Request for creating a new collection was

successful.

DSAXES_E_BUSY A network call is in progress.

DSAXES_E_HTTP An HTTP error was encounterd.

DSAXES_E_WINSOCK A Winsock error was encounterd.

Remarks
If pszServerUrl, pszAuthToken, and pszProxyServer are empty, the values from the previous command are
used.

DocuShare Windows Client SDK 3–33

Objects DSGateway Library

InitiateCollectionOpen

VB InitiateCollectionOpen( pszListFile as String, collHandle as Long, pszServerUrl

as String, pszAuthToken as String, pszProxy as String) as Long

C++ long InitiateCollectionOpen(LPCTSTR pszListFile, long collHandle, LPCTSTR

pszServerUrl, LPCTSTR pszAuthToken, LPCTSTR pszProxy);

The InitiateCollectionOpen method opens a collection in a DocuShare server and queries its contents.

Parameters

Parameter Description

pszListFile A string containing a fully qualified pathname.

DSAXESS will generate an item listing and store it
in this file. A file with the same name is
overwritten.

collHandle Handle number of a collection to open or 0 for

opening the server root collection for enumerating
the top-level collections.

pszServerUrl, pszAuthToken, pszProxy Contains server access information.

Return value

Value Description

DSAXES_SUCCESS Request for opening the collection was

successful.

DSAXES_E_BUSY A network call is in progress.

DSAXES_E_HTTP An HTTP error was encounterd.

DSAXES_E_WINSOCK A Winsock error was encounterd.

Remarks
InitiateCollectionOpen is an asynchronous method. Control returns after a socket is opened. Use the
OpenCollection method for synchronous opening of a collection.

pszListFile cannot be empty. Although OpenCollection uses DSItemListFile, InitiateCollectionOpen does

not use DSItemListFile.

If pszServerUrl, pszAuthToken, and pszProxyServer are empty, the values from the previous command are
used.

If collHandle is 0, DSAXES_MODE_ENABLEXML flag is set and the

DSAXES_MODE_NOSERVERSTATUSQUERY flag not set, DSGateway makes a query for the server
properties prior to making the root open request. This is done to update the general server status such as
server read-only mode. A calling program can use GetMode to query the state of the server.

3–34 DocuShare Windows Client SDK

DSGateway Library Objects

Upon successful conclusion of the collection open request, an item list is generated at the location
specified by parameter pszListFile. The list contains a chained stack of item descriptor structures, each
describing an item which appears in the opened collection. Use the IEnumObj interface to load and
enumerate the queried items. The call, InitiateCollectionOpen, is responsible for deleting the list file after it
is no longer needed.

InitiateCollectionOpen (and OpenCollection) are used to obtain a collection lineage.

A collection lineage refers to a series of collections connected by parent-child relationships. A complete

lineage starts with a top-level collection and ends with the identify collection which InitiateCollectionOpen
opens. A partial lineage starts with an intermediate collection located somewhere in the middle between a
top-level collection and the identify collection. DSGateway uses the concept of elevation to designate the
starting collection of a lineage. DSGateway defines elevation levels one through seven with level one
referring to the parent collection and level seven referring to a top-level collection.

Elevation Elevation Flags Queried Collections

1 DSAXES_PROPATTR_QUERYELEV_PARENT Parent collection

2 DSAXES_PROPATTR_QUERYELEV_2 Grandparent and parent

3 DSAXES_PROPATTR_QUERYELEV_3 Great grandparent

4 DSAXES_PROPATTR_QUERYELEV_4 4 ancestor collections

5 DSAXES_PROPATTR_QUERYELEV_5 5 ancestor collections

6 DSAXES_PROPATTR_QUERYELEV_6 6 ancestor collections

7 DSAXES_PROPATTR_QUERYELEV_INFINITE Top-level collection

To set an elevation level, use property PropAttrIds. For example, to request a lineage list spanning an end
collection all the way up to a top-level collection, set PropAttrIds to
DSAXES_PROPATTR_QUERYELEV_INFINITE. Here is an example that obtains the complete lineage for
Collection-123.

IDsAxes gateway;
...
gateway.SetPropAttrIds( DSAXES_PROPATTR_QUERYELEV_INFINITE );
long status = gateway.InitiateCollectionOpen( pszListFile, 123, "", "", "" );
For a lineage query, the method builds an item descriptor list consisting of collection descriptors describing
each child collection. Thus, the first descriptor refers to the identify collection; the second descriptor refers
to the parent collection. The last descriptor refers to the top-level collection or the collection of the highest
elevation that starts the lineage. The following code loads the lineage list generated by the above code and
prints the names of the lineage collections starting with the top-level collection.

IEnumObj enumObj;
enumObj.Load( DSCONTF_IDENTITY | DSCONTF_ASCENDANTS, pszListFile );
IItemObj identityColl( enumObj.GetNextItem() );
IItemObj parentColl( enumObj.GetNextItem() );
...
IItemObj topColl( enumObj.GetNextItem() );

DocuShare Windows Client SDK 3–35

Objects DSGateway Library

printf( "Top-level collection: %s\n", (LPCTSTR)topColl.GetTitle() );

...
printf( "Parent collection: %s\n", (LPCTSTR)parentColl.GetTitle() );
printf( "Identity collection: %s\n", (LPCTSTR)identityColl.GetTitle() );

NOTE: A lineage query does not perform a query for child items of the identify collection. To obtain
child information, another call must be made to InitaiteCollectionOpen without an elevation
setting.

InitiateCollectionOpen (and OpenCollection) may be used to obtain a hierarchy of collections as well.

A hierarchy of collections refers to an identify collection and any nested collections that appear in the
identify collection. A collection hierarchy is characterized by an identify collection that starts the hierarchy
and a query depth which determines the number of descendent levels that the query should reach.

Descendent
Query Depth Flag Queried Items
Level

1 DSAXES_PROPATTR_QUERYDEPTH_CHILDREN Child items

2 DSAXES_PROPATTR_QUERYDEPTH_2 Children and their children

3 DSAXES_PROPATTR_QUERYDEPTH_3 3 descendent items

4 DSAXES_PROPATTR_QUERYDEPTH_4 4 descendent items

5 DSAXES_PROPATTR_QUERYDEPTH_5 5 descendent items

6 DSAXES_PROPATTR_QUERYDEPTH_6 6 descendent items

7 DSAXES_PROPATTR_QUERYDEPTH_7 7 descendent items

To set a query depth, use property PropAttrIds. For example, to request a hierarchy list of an identify
collection and all items whose lineages trace to the identify collection, set PropAttrIds to
DSAXES_PROPATTR_QUERYDEPTH_INFINITE. Here is an example that obtains a two-level
descendent hierarchy for Collection-123 and prints the names of the queried items.

gateway.SetPropAttrIds( DSAXES_PROPATTR_QUERYDEPTH_2 );
if ( 0 != gateway.InitiateCollectionOpen( pszListFile, 123, "", "", "" ) )
return;
if ( 0 != gatewayAwaitCompletion() )
return;
IEnumObj enumObj;
enumObj.Load(
DSCONTF_IDENTITY | DSCONTF_CHILDREN | DSCONTF_DESCENDANTS,
pszListFile ) )
IItemObj topColl( enumObj.GetNode( 123 ) );
IEnumObj childEnum( topColl.EnumObjects( ITEMOBJ_EOFLAG_SHAREENUM ) );

3–36 DocuShare Windows Client SDK

DSGateway Library Objects

while( childEnum.GetNextPos() )
{
IItemObj childObj( childEnum.GetNextItem() );
puts( childObj.Title );
if ( childObj.TypeNum == DSXITEMTYPE_COLLECTION )
{
puts( "Descendents:" );
IEnumObj grandchildEnum( childObj.EnumObjects(ITEMOBJ_EOFLAG_SHAREENUM ) );
while( grandchildEnum.GetNextPos() )
{
IItemObj grandchildObj( grandchildEnum.GetNextItem() );
puts( grandchildObj.Title );
}
}
}

DocuShare Windows Client SDK 3–37

Objects DSGateway Library

InitiateContainerOpen

VB InitiateContainerOpen ( ListFile as String, BaseType as long, ContType as long,

ContHandle as long, ServerUrl as String, AuthToken as String, ProxyServer as
String) as long

C++ long InitiateContainerOpen ( LPCTSTR ListFile, long BaseType, long

ContType, long ContHandle, LPCTSTR ServerUrl, LPCTSTR AuthToken,
LPCTSTR ProxyServer);

InitiateContainerOpen initiates retrieval of a directory for a DocuShare container object from a DocuShare
server. The retrieval completes in the background. An application may check the retrieval status by calling
GatewayHandler.GetStatus. The status value is DSAXES_SUCCESS (0) when the retrieval is complete.
Alternatively, an application can call the AwaitCompletion or Wait methods.

Parameters

Parameter Description

AuthToken If the target container is restricted to authenticated

users, the DocuShare authentication token for a
DocuShare user. For Guest access, AuthToken
may be set to an empty string. Also, if the
GatewayHandler was instantiated from a call to
Server.Open, AuthToken can be set to an empty
string. GatewayHandler will use the authentication
token maintained by the Server object.

BaseType The DSXITEMTYPE type identifier of the base

DocuShare object class from which the target
container object was derived. If the target
container belongs to a standard DocuShare object
class (such as Collection, Calendar, BulletinBoard,
and SavedQuery), BaseType can be set to zero. If
the target container is a subclass of a standard
object class, BaseType must specify the type
identifier of the latter object class.

ContHandle The handle number of the target container object.

If the target is Calendar-10, ContHandle is set to
10.

ContType The DSXITEMTYPE type identifier of the target

container object for which a directory is retrieved.
If the target is Calendar-10, ContType is set to
DSXITEMTYPE_CALENDAR.

ListFile The pathname of a file to use by the method to

store the retrieved directory information. ListFile
can be empty if storing the directory in a file is not
important.

3–38 DocuShare Windows Client SDK

DSGateway Library Objects

Parameter Description

ProxyServer The http (or https) URL of a proxy server to access

the DocuShare server from the client machine if a
server is in use. If the GatewayHandler was
instantiated from a call to Server.Open,
ProxyServer can be set to an empty string.
GatewayHandler will use the proxy setting used by
the Server object.

ServerUrl The URL of a DocuShare home site. If

GatewaySettings.AddDSCGI is false, the URL
needs to end with a 'dscgi/ds.py' directory
specifier. If the GatewayHandler was instantiated
from a call to Server.Open, SeverUrl can be set to
an empty string. GatewayHandler will use the
server address maintained by the Server object.

Return value

Value Description

DSAXES_SUCCESS (0) The method successfully initiated the retrieval.

DSAXES_E An error occured and the retrieval could not be

started.

Remarks
The method is a generalized version of InitiateCollectionOpen. The latter method works for a Collection
object or for a Collection subclass by specifying a special handle value and cannot be used to find items in
a non-Collection container such as a Calendar or Bulletin Board.

Use the OpenContainer method to synchronously retrieve a directory.

The example below uses InitiateContainerOpen to asynchronously retrieve a Calendar's directory from a
DocuShare server.

set gateway = CreateObject("DSGateway.GatewayHandler")

status = gateway.InitiateContainerOpen( _
"", _
0, _
DSXITEMTYPE_CALENDAR, _
10, _
"http://www.xyz.com/docushare/dscgi/ds.py/", _
"", _
"")
while gateway.Wait(100) = DSAXES_INPROG
' do something else

DocuShare Windows Client SDK 3–39

Objects DSGateway Library

wend
if gateway.GetStatus = 0 then
set cd = gateway.ServerResponse
set enumObj = cd.ItemDescriptorArray.Enumerator
enumObj.Reset
while enumObj.NextPos <> 0
set itemObj = enumObj.NextItem
Print itemObj.Handle, itemObj.Title
wend
end if

3–40 DocuShare Windows Client SDK

DSGateway Library Objects

InitiateCopy

VB InitiateCopy( nObjType as Long, nDsHandle as Long, nNewParentHandle as

Long, pszServerUrl as String, pszAuthToken as String, pszProxyServer as
String) as Long

C++ long InitiateCopy(long nObjType, long nDsHandle, long nNewParentHandle,

LPCTSTR pszServerUrl, LPCTSTR pszAuthToken, LPCTSTR
pszProxyServer);

The InitiateCopy method adds the given DocuShare object to the given DocuShare collection. This method
simply adds the given DocuShare collection to the parent list of the source object. Despite the term Copy in
the method name, the source object is not replicated.

Parameters

Parameter Description

nObjType Object type to copy. It can be one of these values:

• DSXOBJTYPE_DOCUMENT—file object
• DSXOBJTYPE_COLLECTION —collection object
• DSXOBJTYPE_CALENDAR—calendar object
• DSXOBJTYPE_BBOARD—bulletin board object
• DSXOBJTYPE_URL—URL object
• DSXOBJTYPE_SAVEDQUERY—saved query object

nDsHandle Handle number of the object to copy.

nNewParentHandle Handle number of a collection to which the object

is copied.

pszServerUrl Address of a DocuShare server URL string.

pszAuthToken Address of a user authentication token.

pszProxyAddr Address of a proxy server, or if a proxy server is

not used, the address of an empty string.

Return value

Value Description

DSAXES_SUCCESS Request for copying the object was successful.

DSAXES_E_BUSY A network call is in progress.

DSAXES_E_HTTP An HTTP error was encounterd.

DSAXES_E_WINSOCK A Winsock error was encountered.

DocuShare Windows Client SDK 3–41

Objects DSGateway Library

Remarks
Conceptually, InitiateCopy adds a link (parent) to the source object rather than duplicating an object.

If pszServerUrl, pszAuthToken, and pszProxyServer are empty, the values from the previous command are
used.

InitiateCreateObject

VB InitiateCreateObject(fPropIdsCore as Long, fPropIds as Long, pItemDisp as

Object) as Long

C++ long InitiateCreateObject(long fPropIdsCore, long fPropIds, LPDISPATCH

pItemDisp);

InitiateCreateObject creates an object on a DocuShare server using the DocuShare HTTP/XML MKRES
command.

Parameters

Parameter Description

fPropIdsCore Property IDs of core properties that should be

included in the MKRES form data.

fPropIds Property IDs of the new object's type-specific

properties that should be included in the MKRES
form data.

pItemDisp An ItemObj instance that represents the new

object to be created.

Return value
DSAXES_SUCCESS—The creation request was submitted and is being processed by DocuShare.

Remarks
This method is used to create a non-document, non-collection object such as bulletin board and calendar.

Properties of pItemDisp that pertain to the properties specified by fPropIdsCore and fPropIds must contain
non-empty values.

This method starts a background query and returns immediately. Use AwaitCompletion to wait until the
query completes.

3–42 DocuShare Windows Client SDK

DSGateway Library Objects

InitiateDelete

VB InitiateDelete(nObjType as DSX_OBJTYPE, nDsHandle as Long, pszServerUrl

as String, pszAuthToken as String, pszProxyServer as String) as Long

C++ long InitiateDelete(long nObjType, long nDsHandle, LPCTSTR pszServerUrl,

LPCTSTR pszAuthToken, LPCTSTR pszProxyServer);

The InitiateDelete method deletes a DocuShare object.

Parameters

Parameter Description

nObjType Object type to delete. It can be one of these

values:
• DSXOBJTYPE_DOCUMENT—file object
• DSXOBJTYPE_COLLECTION—collection object
• DSXOBJTYPE_CALENDAR—calendar object
• DSXOBJTYPE_BBOARD—bulletin board object
• DSXOBJTYPE_URL—URL object
• DSXOBJTYPE_SAVEDQUERY—saved query object

nDsHandle Handle number of the object to delete.

pszServerUrl Address of a DocuShare server URL string.

pszAuthToken Address of a user authentication token.

pszProxyAddr Address of a proxy server, or if a proxy server is

not used, the address of an empty string.

Return value

Value Description

DSAXES_SUCCESS A request for deleting the object was successful.

DSAXES_E_BUSY A network call is in progress.

DSAXES_E_HTTP An HTTP error was encounterd.

DSAXES_E_WINSOCK A Winsock error was encountered.

Remarks
If pszServerUrl, pszAuthToken, and pszProxyServer are empty, the values from the previous command are
used.

DocuShare Windows Client SDK 3–43

Objects DSGateway Library

InitiateDisown

VB InitiateDisown(pItemDisp as Object, nDisowningParentHandle as Long,

pszServerUrl as String, pszAuthToken as String, pszProxyServer as String) as
Long

C++ long InitiateDisown(LPDISPATCH pItemDisp, long nDisowningParentHandle,

LPCTSTR pszServerUrl, LPCTSTR pszAuthToken, LPCTSTR
pszProxyServer);

The InitiateDisown method removes the given DocuShare object from the given DocuShare collection.
This method simply removes the given DocuShare collection from the parent list of the source object. If the
source object has only one parent, this method fails so that an orphan (parentless) object is not created.
An object can be deleted using InitiateDelete.

Parameters

Parameter Description

pItemDisp An IItemObj object identifying the source

DocuShare object. Set the TypeNum and
HandleNum Item properties to the source
DocuShare object.

nDisowningParentHandle Handle number of the collection from which the

source object is to be removed.

pszServerUrl Address of a DocuShare server URL string.

pszAuthToken Address of a user authentication token.

pszProxyAddr Address of a proxy server, or if a proxy server is

not used, the address of an empty string.

Return value

Value Description

DSAXES_SUCCESS Request for disowning the item was successful.

DSAXES_E_BUSY A network call is in progress.

DSAXES_E_HTTP An HTTP error was encounterd.

DSAXES_E_WINSOCK A Winsock error was encountered.

Remarks
Conceptually, InitiateDisown removes a link (parent) from the source object rather than deleting an object.

If pszServerUrl, pszAuthToken, and pszProxyServer are empty, the values from the previous command are
used.

3–44 DocuShare Windows Client SDK

DSGateway Library Objects

InitiateDownload

VB InitiateDownload( nFlags as Long, nFileHandle as Long, nDownloadData as

Long, pLocalName as String, pDocTitle as String, pServerUrl as String,
pAuthToken as String, pProxyAddr as String) as Long

C++ long InitiateDownload(long nFlags, long nFileHandle, long nDownloadData,

LPCTSTR pLocalName, LPCTSTR pDocTitle, LPCTSTR pServerUrl,
LPCTSTR pAuthToken, LPCTSTR pProxyAddr);

The InitiateDownload method downloads a file from a DocuShare server.

Parameters

Parameter Description

nFlags 0 for normal downloading or

DSAXES_FLAG_DOWNLOADLOCKED for
downloading and locking the file (check-out).
Parameter nFlags can be set to
DSAXES_FLAG_DOWNLOADREPR to instruct
the method to download the representation data
for a file. Parameter nDownloadData must be set
to a representation format identifier.

nFileHandle Handle number of a file to download.

nDownloadData The value of this parameter depends on the value

of nFlags. Set nFlags to zero, nDownloadData
downloads the version number for a specific file
version.

NOTE: Set nFlags and nDownloadData to zero,

the latest version is downloaded.

With nFlags set to

DSAXES_FLAG_DOWNLOADLOCKED,
nDownloadData is ignored.
With nFlags set to
DSAXES_FLAG_DOWNLOADREPR,
nDownloadData is set to one of the following
representation format identifiers:
• DSAXES_REPR_HTML—HTML representation
• DSAXES_REPR_PDF—Adobe PDF representation
• DSAXES_REPR_THUMBNAIL—Thumbnail image
representation

pLocalName A string containing a fully qualified pathname for

the file to be downloaded. If a file with the same
name exists, it is overwritten.

DocuShare Windows Client SDK 3–45

Objects DSGateway Library

Parameter Description

pDocTitle A string that contains the display title of the file.

DSAXESS displays the title in a progress dialog.
The string does not need to be the actual title that
DocuShare holds for the file.

pszServerUrl Address of a DocuShare server URL string.

pszAuthToken Address of a user authentication token.

pszProxyAddr Address of a proxy server, or if a proxy server is

not used, the address of an empty string.

Return value

Value Description

DSAXES_SUCCESS Request for downloading the file was successful.

DSAXES_E_BUSY A network call is in progress.

DSAXES_E_HTTP An HTTP error was encounterd.

DSAXES_E_WINSOCK A Winsock error was encountered.

DSAXES_E_BADPARAM nFileHandle is zero, or pLocalName is invalid.

Remarks
If automatic name clash resolution is desired, use InitiateBulkDownload.

If pServerUrl, pAuthToken, and pProxyAddr are empty, the values from the previous command are used.

3–46 DocuShare Windows Client SDK

DSGateway Library Objects

InitiateGet

VB InitiateGet( pszURL as String, pszAuthToken as String, pszProxyAddr as

String, pszOutFile as String) as Long

C++ long InitiateGet(LPCTSTR pszURL, LPCTSTR pszAuthToken, LPCTSTR

pszProxyAddr, LPCTSTR pszOutFile);

The InitiateGet method submits an HTTP GET request.

Parameters

Parameter Description

pszUrl Address of a DocuShare URL string. pszURL

cannot be empty.

pszAuthToken Address of a user authentication token.

pszProxyAddr Address of a proxy server, or if a proxy server is

not used, the address of an empty string.

pszOutFile An optional string containing a fully qualified

pathname. DSAXESS will redirect the response
entity data, if any, from the server to this file. A file
with the same name is overwritten.

Return value

Value Description

DSAXES_SUCCESS A GET request was successful.

DSAXES_E_BUSY A network call is in progress.

DSAXES_E_HTTP An HTTP error was encounterd.

DSAXES_E_WINSOCK A Winsock error was encountered.

Remarks
If the pszURL URL does not contain a protocol scheme specifier such as http, the address of the
DocuShare server, currently set in DSGateway, is appended. Thus, if the caller passes View/Collection-
123, with the current server address set to http://docushare.xyz.com/, the URL that the method opens
becomes http://docushare.xyz.com/dscgi/ds.py/View/Collection-123.

If it is empty, pszAuthToken or pszProxyAddr is set to the authentication token or proxy server address
currently cached by DSGateway.

If the URL to be opened is a DocuShare URL, any DocuShare handle that is generated as a result of the
URL opening, is saved in DSObjectHandle.

DocuShare Windows Client SDK 3–47

Objects DSGateway Library

InitiateHistory

VB InitiateHistory( pszListFile as String, docHandle as Long, pszServerUrl as

String, pszAuthToken as String, pszProxy as String) as Long

C++ long InitiateHistory(LPCTSTR pszListFile, long docHandle, LPCTSTR

pszServerUrl, LPCTSTR pszAuthToken, LPCTSTR pszProxy);

The InitiateHistory method queries the version history of a DocuShare file.

Parameters

Parameter Description

pszListFile A string containing a fully qualified pathname.

DSAXESS outputs the obtained version history of
this file. A file with the same name is overwritten.

docHandle Handle number of the file for which history query is

made.

pszServerUrl Address of a DocuShare server URL string.

pszAuthToken Address of a user authentication token.

pszServerProxy Address of a proxy server, or if a proxy server is

not used, the address of an empty string.

Return value

Value Description

DSAXES_SUCCESS Request for querying the object was successful.

DSAXES_E_BUSY A network call is in progress.

DSAXES_E_HTTP An HTTP error was encounterd.

DSAXES_E_WINSOCK A Winsock error was encounterd.

Remarks
A version history has the same data structure as a collection item list. It is a chained list of descriptor
structures. Each descriptor structure describes a document version. Use the IEnumObj interface to load
the generated list and enumerate the found version objects.

MFC code to query for the version history of File-456 in a DocuShare server and to print the version
number and filename of each version object found.

IDsAxes gateway;
...
LPCTSTR pszListFile = "c:\temp\history.dat";
if( 0 != gateway.InitiateHistory( pszListFile, 456, "", "", "" ) )

3–48 DocuShare Windows Client SDK

DSGateway Library Objects

return;
if( 0 != gateway.AwaitCompletion() )
return;
IEnumObj enumObj;
enumObj.CreateDispatch( "DSITEMENUMLib.EnumObj" );
if( 0 != enumObj.Load( DSCONTF_VERSIONS, pszListFile ) )
return;
while( enumObj.GetNextPos() )
{
IItemObj verObj( enumObj.GetNextItem() );
printf( "Version %d: %s\n", verObj.VersionNum, verObj.Name );
}

DocuShare Windows Client SDK 3–49

Objects DSGateway Library

InitiateLock

VB InitiateLock( bLock as Boolean, nFileHandle as Long, pServerUrl as String,

pAuthToken as String, pProxyAddr as String) as Long

C++ long InitiateLock(BOOL bLock, long nFileHandle, LPCTSTR pServerUrl,

LPCTSTR pAuthToken, LPCTSTR pProxyAddr);

The InitiateLock method locks or unlocks a DocuShare file.

Parameters

Parameter Description

bLock TRUE to lock or FALSE to unlock.

nFileHandle Handle number of a file to be locked or unlocked.

pServerUrl Address of a DocuShare server URL string.

pAuthToken Address of a user authentication token.

pProxyAddr Address of a proxy server, or if a proxy server is

not used, the address of an empty string.

Return value

Value Description

DSAXES_SUCCESS Request for locking the object was successful.

DSAXES_E_BUSY A network call is in progress.

DSAXES_E_HTTP An HTTP error was encounterd.

DSAXES_E_WINSOCK A Winsock error was encounterd.

Remarks
DSAXESS ignores an error condition reported by DocuShare for an attempt to unlock a file that is
unlocked. When this happens, DSGateway does not display an error dialog and does not set the following:

• DSHandle parameter to -1
• GetStatus status code to 0
• GetLastError error code to 409
If pszServerUrl, pszAuthToken, and pszProxyServer are empty, the values from the previous command are
used.

3–50 DocuShare Windows Client SDK

DSGateway Library Objects

InitiateMove

VB InitiateMove( nObjType as Long, nDsHandle as Long, nNewParentHandle as

Long, nOldParentHandle as Long, pszServerUrl as String, pszAuthToken as
String, pszProxyServer as String) as Long

C++ long InitiateMove(long nObjType, long nDsHandle, long nNewParentHandle,

long nOldParentHandle, LPCTSTR pszServerUrl, LPCTSTR pszAuthToken,
LPCTSTR pszProxyServer);

The InitiateMove method moves an item in a DocuShare server.

Parameters

Parameter Description

nObjType Object type to move. It can be one of these

values:
• DSXOBJTYPE_DOCUMENT—file object
• DSXOBJTYPE_COLLECTION —collection object
• DSXOBJTYPE_CALENDAR—calendar object
• DSXOBJTYPE_BBOARD—bulletin board object
• DSXOBJTYPE_URL—URL object
• DSXOBJTYPE_SAVEDQUERY—saved query object

nDsHandle Handle number of the object to set properties.

nNewParentHandle Handle number of the destination collection.

nOldParentHandle Handle number of the collection currently

containing the object.

pszServerUrl Address of a DocuShare server URL string.

pszAuthToken Address of a user authentication token.

pszProxyAddr Address of a proxy server, or if a proxy server is

not used, the address of an empty string.

Return value

Value Description

DSAXES_SUCCESS Request for moving the object was successful.

DSAXES_E_BUSY A network call is in progress.

DSAXES_E_HTTP An HTTP error was encounterd.

DSAXES_E_WINSOCK A Winsock error was encounterd.

Remarks

DocuShare Windows Client SDK 3–51

Objects DSGateway Library

If pszServerUrl, pszAuthToken, and pszProxyServer are empty, the values from the previous command are
used.

InitiatePost

VB InitiatePost( cProps as Long, pvPropNames as Variant, pvPropValues as

Variant, pszURL as String, pszAuthToken as String, pszProxyAddr as String,
pszOutFile as String) as Long

C++ long InitiatePost(long cProps, VARIANT* pvPropNames, VARIANT*

pvPropValues, LPCTSTR pszURL, LPCTSTR pszAuthToken, LPCTSTR
pszProxyAddr, LPCTSTR pszOutFile);

The InitiatePost methods submits an urlencoded form or an XML message using HTTP POST.

Parameters

Parameter Description

cProps Number of properties to include in the form data. If

this parameter is set to one, pvPropNames will
have text data and pzPropValues an integer value.
This method regards the text data in
pvPropNames as a complete XML data set and
the integer value in pvPropValues as a query
depth specifier.

pvPropNames A variant containing property names. If the vt

member is VT_BSTR, the pbstrVal member
contains the address of a Unicode string list of
double-quoted property names.
If the vt member is VT_ARRAY, the parray
member contains the address of a SAFEARRAY
structure that contains a list of zero-terminated
ANSI strings of property names.
To post XML data, set the data in pvPropNames.
The vt member must be VT_BSTR, and the
pbstrVal must be the address of the null-
terminated string of XML data.

3–52 DocuShare Windows Client SDK

DSGateway Library Objects

Parameter Description

pvPropValues A variant containing property values. If the vt

member is VT_BSTR, the pbstrVal member
contains the address of a Unicode string list of
double-quoted property values. The order of the
property values must be the same as that in
pvPropNames.
If the vt member is VT_ARRAY, the parray
member contains the address of a list of zero-
terminated ANSI strings of property values.
When pvPropNames contains XML data,
pvPropValues contains a query depth specifier.
The vt member must be VT_I2 or VT_I4. The iVal
or lVal must contain a query depth specifier. If a
query depth header is not required, set it to zero.

pszURL, pszAuthToken, pszProxyAddr Strings containing server access information.

pszURL cannot be empty.

pszOutFile An optional string containing a fully qualified

pathname. DSGateway redirects the response
entity data, if any, from the server to this file. A file
with the same name is overwritten.

Return value

Value Description

DSAXES_SUCCESS A POST request was successful.

DSAXES_E_BUSY A network call is in progress.

DSAXES_E_HTTP An HTTP error was encounterd.

DSAXES_E_WINSOCK A Winsock error was encounterd.

DSAXES_E_BADPARAM pvPropNames and pvPropValues are inconsistent.

DSAXES_E_SYSRES BSTR conversion ran out of allocation space.

Remarks
For posting non-XML form data, the method encodes the property values by escaping characters that are
illegal for HTTP transport. The method generates a transmittal form by combining the property names of
pvPropNames and the property values of pvPropValues. The number of properties defined by the two
variant structures must equal the count in cProps.

If the pszURL URL does not contain a transport protocol specifier (http), the address of the DocuShare
server currently set in DSGateway is appended. If the caller passes PROPFIND/Collection-123 with the
current server address set to http://docushare.xyz.com/, the URL that the method opens becomes http://
docushare.xyz.com/dscgi/ds.py/PROPFIND/Collection-123.

DocuShare Windows Client SDK 3–53

Objects DSGateway Library

If it is empty, pszAuthToken or pszProxyAddr is set to the authentication token or proxy server address
currently cached by DSGateway.

If the URL to be opened is a DocuShare URL, any DocuShare handle that is generated as a result of the
URL opening, is saved in DSObjectHandle.

It is the responsiblity of the calling application to delete the pszOutFile output file.

The following is a VB script that uses InitiatePost to post a form for creating a sub-collection in Collection-
10 in a DocuShare server.

dim gateway
set gateway = CreateObject("DSGateway.GatewayHandler")
status = gateway.DoLoginDialog
if status = 0 then
dim propNames
dim propValues
cProps = 3
propNames = chr(&H22)+"parent"+chr(&H22)+" "+_
chr(&H22)+"obj_type"+chr(&H22)+" "+_
chr(&H22)+"title"+chr(&H22)
propValues = chr(&H22)+"Collection-10"+chr(&H22)+" "+_
chr(&H22)+"Collection"+chr(&H22)+" "+_
chr(&H22)+"Another New Collection"+chr(&H22)
URL = "ApplyUpload/Collection-10"
outputFile = "c:\temp\posttest.htm"
status = gateway.InitiatePost(cProps, propNames, propValues, URL, "", "",
outputFile)
if status = 0 then
status = gateway.AwaitCompletion
if status = 0 then
MsgBox("Successfully created Collection-" & CStr(gateway.DSHandle))
end if
else
MsgBox("InitiatePost returned status code=" & CStr(status))
end if
end If
The above script causes InitiatePost to generate the following canonical form data of content type
application/x-www-form-urlencoded.

parent=Collection%2D10&obj_type=Collection&title=New%20Collection
The handle of the created collection is saved in DSHandle upon successful completion.

To post an XML command message:

3–54 DocuShare Windows Client SDK

DSGateway Library Objects

1. Define the XML message body and set it in pvPropNames.

2. Set pvPropValues to the value of a query depth required by the XML command. For a command
other than the DocuShare HTTP/XML PROPFIND command, this parameter may be set to zero.
For a PROPFIND command, or any other command that requires a query depth, specify the
desired depth using this parameter.
3. Set cProps to one.
4. Call InitiatePost with pszURL set to the XML command.
Here is a script that posts an XML MKRES command for creating a URL object in Collection-10.

dim gateway
set gateway = CreateObject("DSGateway.GatewayHandler")
status = gateway.DoLoginDialog
If status = 0 then
dim xmlData
dim queryDepth
xmlData = "<?xml version="+chr(&H22)+"1.0"+chr(&H22)+" ?>" & _
"<propertyupdate>" & _
"<set><prop>" & _
"<url><![CDATA[http://www.xerox.com/]]></url>" & _
"<displayname><![CDATA[Xerox Home Page]]></displayname>" & _
"</prop></set>" & _
"</propertyupdate>"
queryDepth = 0
URL = "MKRES/Collection-10/URL"
outputFile = "c:\temp\posttest.htm"
status = gateway.InitiatePost(1, xmlData, queryDepth, URL, "", "",
outputFile)
if status = 0 then
status = gateway.AwaitCompletion
if status = 0 then
MsgBox("Successfully created URL-" & CStr(gateway.DSHandle))
end if
else
MsgBox("InitiatePost returned status code=" & CStr(status))
end if
end If

DocuShare Windows Client SDK 3–55

Objects DSGateway Library

InitiateRename

VB InitiateRename(nObjType as DSX_OBJTYPE, nDsHandle as Long,

pszNewTitle as String, pszServerUrl as String, pszAuthToken as String,
pszProxyServer as String) as Long

C++ long InitiateRename(long nObjType, long nDsHandle, LPCTSTR pszNewTitle,

LPCTSTR pszServerUrl, LPCTSTR pszAuthToken, LPCTSTR
pszProxyServer);

The InitiateRename method renames an item in DocuShare.

Parameters

Parameter Description

nObjType Object type to rename. It can be one of these

values:
• DSXOBJTYPE_DOCUMENT—file object
• DSXOBJTYPE_COLLECTION—collection
object
• DSXOBJTYPE_CALENDAR—calendar object
• DSXOBJTYPE_BBOARD—bulletin board object
• DSXOBJTYPE_URL—URL object
• DSXOBJTYPE_SAVEDQUERY—saved query
object
• DSXOBJTYPE_USER—User object
• DSXOBJTYPE_GROUP—Group object

nDsHandle Handle number of the object to rename.

pszNewTitle A string containing the new name of the object.

pszServerUrl Address of a DocuShare server URL string.

pszAuthToken Address of a user authentication token.

pszProxyAddr Address of a proxy server, or if a proxy server is

not used, the address of an empty string.

3–56 DocuShare Windows Client SDK

DSGateway Library Objects

Return value

Value Description

DSAXES_SUCCESS Request for renaming was successful.

DSAXES_E_BUSY A network call is in progress.

DSAXES_E_HTTP An HTTP error was encounterd.

DSAXES_E_WINSOCK A Winsock error was encounterd.

DSAXES_E_FAIL The XML mode is not in use. This method only

works for DocuShare version 2.0 or higher.

Remarks
If pszServerUrl, pszAuthToken, and pszProxyServer are empty , the values from the previous command
are used.

DocuShare Windows Client SDK 3–57

Objects DSGateway Library

InitiateSchema

VB InitiateSchema( pszListFile as String, pszServerUrl as String, pszAuthToken as

String, pszProxy as String) as Long

C++ long InitiateSchema(LPCTSTR pszListFile, LPCTSTR pszServerUrl, LPCTSTR

pszAuthToken, LPCTSTR pszProxy);

InitiateSchema retrieves schema data from a DocuShare server.

Parameters

Parameter Description

pszListFile Pathname to the file that stores the retrieved data.

If this contains a NULL or an empty string, the
method uses a temporary storage.

pszServerUrl URL of a DocuShare server. If

GatewaySettings.AddDSCGI is false, the URL
must end with a "dscgi/ds.py/" directory specifier.

pszAuthToken A DocuShare authentication token that identifies a

DocuShare user and authorizes access.

pszProxy URL of a proxy server. If a proxy server is not

used, it is set to NULL or an empty string.

Return values
DSAXES_SUCCESS—The schemata query was submitted and is being processed by DocuShare.

Remarks
The method starts a background query and returns immediately. Use AwaitCompletion to wait until the
query completes.

This script retrieves schemata from a DocuShare server and prints server-defined property names and
associated help text.

set gateway = CreateObject("DSGateway.GatewayHandler")

gateway.InitiateSchema("", "http://ds.xyz.com/dscgi/ds.py/", "", "")
if 0 = gateway.AwaitCompletion then
set enumSchema = CreateObject( "DSITEMENUMLib.EnumSchema" )
enumSchema.Load gateway.ServerResponse
enumSchema.Reset
while enumSchema.NextPos <> 0

3–58 DocuShare Windows Client SDK

DSGateway Library Objects

set itemSchema = enumSchema.NextItem

Print itemSchema.Name, itemSchema.HelpText
wend
end if
The ContentData.ParseSchema was internally called by the built-in Close event handler. This is okay for
the above script to access ContentData.ItemDescriptorArray directly.

DocuShare Windows Client SDK 3–59

Objects DSGateway Library

InitiateUserAuth

VB InitiateUserAuth( pszUsername as String, pszPassword as String,

pszServerUrl as String, pszProxyServer as String) as Long

C++ long InitiateUserAuth(LPCTSTR pszUsername, LPCTSTR pszPassword,

LPCTSTR pszServerUrl, LPCTSTR pszProxyServer);

The InitiateUserAuth method submits a user authentication request to a DocuShare server. Control returns
immmediately.

Parameters

Parameter Description

pszUsername Username of a DocuShare account.

pszPassword Password for the DocuShare account.

pszServerUrl Address of a DocuShare server URL string.

pszAuthToken Address of a user authentication token.

pszProxyAddr Address of a proxy server, or if a proxy server is

not used, the address of an empty string.

Return value

Value Description

DSAXES_SUCCESS Request for authentication was successful.

DSAXES_E_SYSRES Command object instantiation failure.

Remarks
Use AwaitCompletion to synchronize with the network call. To retrieve the authentication token and user
handle, call GetAuthToken.

If the DSAXES_MODE_ENABLEXML flag is set, the method uses the XML Login command for
DocuShare version 2.0 and forms an XML entity body to pass the credential information to the server. The
format for XML entity body.

<?xml version=""1.0"" ?>

<authorization>
<username><![CDATA[%2]]></username>
<password><![CDATA[%3]]></password>
</authorization>"
%2 is the account name, and %3 is the password string.

3–60 DocuShare Windows Client SDK

DSGateway Library Objects

If the flag is cleared, the method uses the DocuShare version 1.5 ApplyLogin command and forms.

Content-type: application/x-www-form-urlencoded
username=%2&password=%3
%2 is a urlencoded account name, and %3 is a urlencoded password string.

DocuShare Windows Client SDK 3–61

Objects DSGateway Library

OpenContainer

VB OpenContainer( ContHandle as String ) as long

C++ long OpenContainer( LPCTSTR ContHandle );

OpenContainer retrieves a directory of a DocuShare container object.

Parameters
ContHandle—the DocuShare handle of a container object for which directory information is retrieved.

Return value

Value Description

DSAXES_SUCCESS (0) The method successfully initiated the retrieval.

DSAXES_E An error occured and the retrieval could not be

started.

Remarks
The method does not return until either the retrieval completes or an error terminates the retrieval.

The method is a generalized version of OpenCollection which restricted directory query to a Collection
object. OpenContainer can be used to retrieve a directory for a non-Collection object as well.

The example below retrieves the directory of a bulletin board.

set gateway = server.Open

status = gateway.OpenContainer( "BulletinBoard-11" )
if status = 0 then
set cd = gateway.ServerResponse
set enumObj = cd.ItemDescriptorArray.Enumerator
enumObj.Reset
while enumObj.NextPos <> 0
set itemObj = enumObj.NextItem
Print itemObj.Handle, itemObj.Title
wend
end if
The above example does not specify a file through GatewayHandler.DSItemListFile for storing the
retrieved directory information. But, if the information is important, an application can set DSItemListFile to
a file pathname. OpenContainer will save the directory data in the file upon successful completion.

3–62 DocuShare Windows Client SDK

DSGateway Library Objects

OpenCollection

VB OpenCollection( nCollHandle as Long ) as Long

C++ long OpenCollection(long nCollHandle);

The OpenCollection method opens a collection in the current server synchronously. Control does not
return until the network call completes.

Parameters
nCollHandle—handle number of a collection to open.

Return value

Value Description

DSAXES_SUCCESS The collection opened successfully.

DSAXES_E_BUSY A network call is in progress.

DSAXES_E_BADPARAM The collection handle is not a valid parameter.

DSAXES_E_SYSRES The call failed due to insufficient system

resources.

Remarks
This method outputs the item list to a file specified by DSItemListFile. If DSItemListFile is empty, a file with
name SZ_DSAXES_DEFOUTPUTFILE is created in the cache sub-directory of the base directory where
the SDK was installed. The listing data will output to this file. When it terminates, IDsAxes deletes the file.

To open a collection asynchronously, use InitiateCollectionOpen.

Here is MFC code which opens Collection-10 in DocuShare and prints the item names that appear in the
collection.

IDsAxes gateway;
gateway.CreateDispatch( "DSGateway.GatewayHandler" );
if ( 0 != gateway.DoLoginDialog() )
return;
if ( 0 != gateway.OpenCollection( 10 ) )
return;
IEnumObj enumObj;
enumObj.CreateDispatch( "DSITEMENUMLib.EnumObj" );
enumObj.Load( DSCONTF_CHILDREN, gateway.GetDSItemListFile() );
enumObj.Reset();
while( enumObj.GetNextPos() )
{

DocuShare Windows Client SDK 3–63

Objects DSGateway Library

IItemObj itemObj( enumObj.GetNextItem() );

puts( itemObj.Title );
}
OpenCollection can be used to obtain collection lineage and hierarchy information. Refer to
InitiateCollectionOpen on page 3–34 for details.

3–64 DocuShare Windows Client SDK

DSGateway Library Objects

RegisterClient

VB RegisterClient( bRegister as Boolean, nClientID as Long, pszClientName as

String, pdwCookie as Long) as Long

C++ long RegisterClient(BOOL bRegister, long nClientID, LPCTSTR

pszClientName, long* pdwCookie);

The RegisterClient method registers the client application.

Parameters

Parameter Description

bRegister If set to True, the client application is registered.

Otherwise, the client application is not registered.

nClientID Process ID of the registering client application.

Use Win32 function GetCurrentProcessId to
obtain the process ID.

pszClientName Contains a display name for the registering client

application.

pdwCookie This parameter is filled with a valid cookie which is

needed to unregister the client application. This
parameter should be set to a valid memory
location when registering the client.

Return value

Value Description

DSAXES_SUCCESS The registration or unregistration request was

successful.

DSAXES_E_BADPARAM An invalid parameter was passed.

Remarks
Although it is not required for an SDK application to register with IDsAxes by calling RegisterClient, doing
so ensures that in the event of an abnormal client application termination, the IDsAxes instance can shut
down automatically.

The following code registers the application with an IDsAxes instance, performs some tasks, and
unregisters before the IDsAxes instance goes out of scope.

DWORD dwGatewayCookie = 0;
IDsAxes gateway;
gateway.CreateDispatch( "DSGateway.GatewayHandler" );

DocuShare Windows Client SDK 3–65

Objects DSGateway Library

if( 0 == gateway.RegisterClient( TRUE, GetCurrentProcessId(), "MyApp",

&dwGatewayCookie ) )
{
// Perform client gateway tasks.
...
gateway.RegisterClient( FALSE, 0, "", &dwGatewayCookie );
}

3–66 DocuShare Windows Client SDK

DSGateway Library Objects

Search

VB Search( dwFlags as Long, pszQueryData as String ) as Long

C++ long Search(long dwFlags, LPCTSTR pszQueryData);

The Search method performs a synchronous search against the current DocuShare server. This method
prepares an XML request body which specifies the search scope and criteria and does a HTTP post with a
DocuShare Search command. Control does not return until the command completes or an error is
encountered.

Parameters

Parameter Description

dwFlags Controls how Search prepares an XML request

body for search scope and criteria.

pszQueryData Address of either an XML request body or the

value of a search property whose type is given by
one of the property type flags.

Return value

Value Description

DSAXES_SUCCESS The search request successfully completed.

DSAXES_E_HTTP An HTTP error was encounterd.

DSAXES_E_WINSOCK A Winsock error was encounterd.

DSAXES_E_BADPARAM A server URL was not set.

Remarks
Refer to Performing basic searches on page 2–64 on how to utilize the Search method.

On successful return, DSHandle contains the number of search hits.

Search fails if used against DocuShare version 1.x. server

DocuShare Windows Client SDK 3–67

Objects DSGateway Library

SetItemProplds

VB SetItemPropIds(nItemType As Long, fPropIds As Long) As Long

C++ long SetItemPropIds(long nItemType, long fPropIds);

The SetItemPropIds method specifies which properties should be queried or updated for a specific item
type when the methods GetProps, SetProps, or Upload are called.

Parameters
nItemType—the type of item to be set. Valid types are:

Parameter Description

DSXITEMTYPE_COLLECTION Obtains the collection property IDs.

DSXITEMTYPE_DOCUMENT The property IDs for a document.

DSXITEMTYPE_VERSION Obtains the property IDs for a particular version of

a document.

DSXITEMTYPE_CALENDAR Gets the property IDs for a calendar object on a

DocuShare server.

DSXITEMTYPE_BBOARD Gets the property IDs for a bulletin board object on

a DocuShare server.

DSXITEMTYPE_URL Gets the property IDs for a designated URL object

on a DocuShare server.

DSXITEMTYPE_SAVEDQUERY Gets the property IDs for a saved query on a

DocuShare server.

DSXITEMTYPE_USER Gets the property IDs for a user.

DSXITEMTYPE_GROUP Gets the property IDs for a user group on a

DocuShare server.

fPropIds—the property types to set are OR together. See Valid Propld in SetProps on page 3–77 for a list
of PropIDs.

Return value
SetItemPropIds always returns DSAXES_SUCCESS

Remarks
SetItemPropIds is used to update the item specific property IDs. Use the IDsAxes property PropIds to
update the core property IDs.

The SetItemPropIds method works in conjunction with methods InitiateCollectionOpen, OpenCollection,

and Search. These methods query only those specific item type properties specified by the property IDs
set by SetItemPropIds and those core properties specified by the property IDs of IDsAxes.PropIds.

3–68 DocuShare Windows Client SDK

DSGateway Library Objects

The item type specific properties that are queried by default.

Item Type Item Dependent Property ItemObj Properties

File DSAXES_PROPID_FILE_FILENAME Name*

DSAXES_PROPID_FILE_MIMETYPE MimeType

DSAXES_PROPID_FILE_MAXVERSION MaxVersions *

DSAXES_PROPID_FILE_LOCKEDBY IsLocked, User *

DSAXES_PRODID_FILE_SIZE Length *

Collection DSAXES_PROPID_COLL_SIZE Length *

URL DSAXES_PROPID_URL_URL URL

Calendar –

BulletinBoard –

User –

Group –

NOTE: * Refer to Proplds on page 3–99 for a list of default core properties.

The property ID flags applicable to the SetItemPropsIds method are also applicable to the item specify
property ID parameters of methods GetProps, SetProps, and Upload. These methods take in an IItemObj
interface as an input argument. GetProps query those properties identified by the current set of core and
item specific property IDs and stores the found property values in the IItemObj interface. Using the
property values stored in the IItemObj interface, SetProps and Upload update properties of an item that are
stored in a DocuShare server. The methods update only those properties specified by the property IDs of
fPropIdsCore and fPropIds parameters. The item type specific properties applicable to these methods are
shown below.

Item Type Item Dependent Property ItemObj Properties

File DSAXES_PROPID_FILE_FILENAME Name*

DSAXES_PROPID_FILE_MIMETYPE MimeType

DSAXES_PROPID_FILE_AUTHOR Author

DSAXES_PROPID_FILE_MAXVERSION MaxVersions *

DSAXES_PROPID_FILE_LOCKEDBY IsLocked, User *

DSAXES_PRODID_FILE_SIZE Length *

DSAXES_PROPID_FILE_ABSTRACT Abstract *

DocuShare Windows Client SDK 3–69

Objects DSGateway Library

Item Type Item Dependent Property ItemObj Properties

Collection DSAXES_PROPID_COLL_LOGO Logo

DSAXES_PROPID_COLL_BGIMAGE Background Image

DSAXES_PROPID_COLL_SORTORDER Sort Order

DSAXES_PROPID_COLL_SIZE Length *

URL DSAXES_PROPID_URL_URL URL

Calendar DSAXES_PROPID_CLND_DEFAULTVIEW CustomProp ("default_scale",

DSAXES_PROPTYPE_BOOL)

BulletinBoard DSAXES_PROPID_BBRD_EXPIRES CustomProp ("expire",

DSAXES_PROPTYPE_MENU

User DSAXES_PROPID_USER_USERNAME Name

DSAXES_PROPID_USER_FIRSTNA
ME

DSAXES_PROPID_USER_FIRSTNAME CustomProp ("first_name",

DSAXES_PROPTYPE_STRING

DSAXES_PROPID_USER_LASTNAME CustomProp ("last_name",

DSAXES_PROPTYPE_STRING)

DSAXES_PROPID_USER_EMAIL CustomProp ("email",

DSAXES_PROPTYPE_STRING)

DSAXES_PROPID_USER_MAILSTOP CustomProp ("mailstop",

DSAXES_PROPTYPE_STRING)

DSAXES_PROPID_USER_PHONE CustomProp ("phone",

DSAXES_PROPTYPE_STRING)

DSAXES_PROPID_USER_USEUPLDHLPR CustomProp ("use_upload_helper",

DSAXES_PROPTYPE_MENU)

DSAXES_PROPID_USER_PASSWORD CustomProp ("password",

DSAXES_PROPTYPE_STRING)

DSAXES_PROPID_USER_LASTLOGIN CustomProp ("last_login",

DSAXES_PROPTYPE_DATE)

DSAXES_PROPID_USER_HOMEPAGE CustomProp ("homepage",

DSAXES_PROPTYPE_STRING)

Group DSAXES_PROPID_GRP_CHANGEACCESS CustomProp ("change_access",

DSAXES_PROPTYPE_BOOL)

NOTE: Properties marked with asterisks are read-only properties; therefore, applicable to GetProps
only.

3–70 DocuShare Windows Client SDK

DSGateway Library Objects

SetMode

VB SetMode( flags as Long, mask as Long ) as Long

C++ long SetMode(long flags, long mask);

The SetMode method sets the gateway mode.

Parameters

Parameter Description

DSAXES_MODE_SILENT Disables the data transfer progress display. The

flag is cleared by default but is set by default in the
console mode.

DSAXES_MODE_USEPROXY Enables using a proxy server in DoLoginDialog.

The flag is cleared by default.

DSAXES_MODE_USEMIMETYPE Enables use of a MIME type specifier in an

ApplyUpload header. The flag is initialized to the
negated boolean value of the registry setting,
HKCU\Software\Xerox\DocuShare
Client\DSAXESS\Settings\IgnoreMimeType. The
registry setting defaults to FALSE, therefore this
flag is set by default.
If enabled, DSAXES_MODE_USEMIMETYPE
directs DSAXESS to output this as part of the multi-
part request header:
• Content-Disposition: form-data; name="file1";
filename="%1"
• Content-Type: %2
• Content-Transfer-Encoding: binary
%1 is the placeholder for a filename from the caller,
and %2 is the placeholder for a MIME type specifier
from the caller. If an empty MIME type is passed,
%2 is replaced with the default content type,
application/octet-stream, and the entire third line for
the binary transfer encoding type is not output.
If the USEMIMETYPE flag is off, %2 is always the
default content type, and the binary transfer
encoding line is always output.

DSAXES_MODE_ADDDSCGI Adds the dscgi/ds.py redirection path to the server

home URL when building a DocuShare command
URL. If the server URL does not contain the path,
before calling InitiateUserAuth, set this flag to have
DSGateway add the path to the server URL. The
flag is cleared by default, but is set by default in the
console mode.

DocuShare Windows Client SDK 3–71

Objects DSGateway Library

Parameter Description

DSAXES_MODE_MEMORIZEUSER Enables reading a registry username and writing it

to the registry entry at
HKCU\Software\Xerox\DocuShare
Client\DSAXESS\User\UserName. The registry
writing of user information is controlled by
DSAXES_MODE_SAVESETTINGS. The reading of
user information is controlled by
DSAXES_MODE_LOADSETTINGS.

DSAXES_MODE_VIRTUALROOT Enables appending a redirection path to the server

home URL. The flag does not affect a command
URL. You can use this to address the home URL for
DocuShare version 1.5. For example, a web server
address—http://webserver.xyz.com/ and whose
DocuShare home address is http://
webserver.xyz.com/docushare/. If this flag is set at
the time of an InitiateUserAuth call, DSGateway
extracts the DocuShare redirection part from the
DocuShare home URL which you enter as the
server URL parameter. To form a command URL,
DSAXESS uses the web server address and
ignores the DocuShare redirection path. The default
is off.

DSAXES_MODE_ENABLECACHE Enables caching opened collections. By default,

this flag is set. The default (global) setting can be
changed by editing the registry setting at
HKCU\Software\Xerox\DocuShare
Client\DSAXESS\Settings\EnableCache. The
cache expiration time is 5 minutes and can be
modified by editing
HKCU\Software\Xerox\DocuShare
Client\DSAXESS\Settings\CacheExpireMinutes.

DSAXES_MODE_ENABLEXML Enables using DocuShare XML commands. The

flag is cleared by default. DSGateway updates the
state of this flag everytime it executes a DocuShare
command. DSGateway looks at the DocuShare
version header sent by the server. If the header
value is 2.0 or higher, the XML flag is set
automatically. In order to execute a session's first
command, such as InitiateUserAuth in its XML
format (Login), you need to set this flag before
making the call. Otherwise, the HTML command,
ApplyLogin, is generated.

3–72 DocuShare Windows Client SDK

DSGateway Library Objects

Parameter Description

DSAXES_MODE_DNLDNAMECLASHPROMPT Enables a prompt for resolution when the name of a

file to be downloaded clashes with a filename in the
destination folder on the client machine. The flag
only affects InitiateBulkDownload. It does not affect
InitiateDownload.
If the flag is set and a name clash is encountered
during the pre-processing phase of
InitiateBulkDownload, DSAXESS runs a dialog and
asks the user to choose one of the actions:
• Yes to replace
• Yes to All to replace all
• No to skip
• Cancel
The default state of the flag is cleared (for always
replace) and loaded from the registry entry
HKCU\Software\Xerox\DocuShare
Client\DSAXESS\Settings\NameClashPromptOnDo
wnload at startup.

DSAXES_MODE_UPLDNAMECLASHPROMPT Enables a prompt for resolution when the name of a

file to be uploaded clashes with a filename in the
destination DocuShare collection. The flag only
affects InitiateBulkUpload and InitiateBulkReplicate.
It does not affect InitiateUpload.
If the flag is set and a name clash is encountered
during the pre-processing phase of
InitiateBulkUpload, DSGateway runs a dialog and
asks the user to choose one of the actions:
• Yes to replace
• Yes to All to replace all
• No to skip
• Cancel
The default state of the flag is set (for always
prompt) and loaded from the registry entry
HKCU\Software\Xerox\DocuShare
Client\DSAXESS\Settings\NameClashPromptOnUp
load at startup.

DocuShare Windows Client SDK 3–73

Objects DSGateway Library

Parameter Description

DSAXES_MODE_UPLDALWAYSASNEWDOC Instructs DSAXESS to always upload a file as a

new document. The flag only affects
InitiateBulkUpload and InitiateBulkReplicate. It does
not affect InitiateUpload.
When this flag is set, DSGateway skips the name
clash resolution routine. This flag overrides the flag
setting of
DSAXES_MODE_UPLDNAMECLASHPROMPT.
The flag's default state is loaded from the registry
entry HKCU\Software\Xerox\DocuShare
Client\DSAXESS\Settings\UploadAlwaysAsNewDo
c at startup.

DSAXES_MODE_AUTOUPLOAD Instructs DSAXESS to run as standalone and

terminate automatically as soon as
InitiateBulkUpload, InitiateBulkDownload, or
InitiateBulkReplicate completes. This flag is useful
in detaching the gateway from a call process to
allow the gateway to complete its upload task in the
background while allowing the call process to
resume its own task in the foreground.

DSAXES_MODE_SAVESETTINGS Enables writing user information to the system

registry key HKCU\Software\Xerox\DocuShare
Client\DSAXESS\User. The following entries are
updated:
• MemorizeUser contains the state of
DSAXES_MODE_MEMORIZEUSER.
• UserName contains the user name string (if
DSAXES_MODE_MEMORIZEUSER is set) or is
empty (if DSAXES_MODE_MEMORIZEUSER is
cleared).
• URL contains the DocuShare server URL from
the last session.
• DsCgi contains the state of
DSAXES_MODE_ADDDSCGI.
• VirtualRoot contains the state of
DSAXES_MODE_VIRTUALROOT.
Root contains the redirection root path.
This flag is cleared by default, but is set in console
mode.

DSAXES_MODE_LOADSETTINGS Instructs DSGateway to load the user information

saved by DSAXES_MODE_SAVESETTINGS. The
loading happens during the SetMode call. Both
flags and mask must include this flag.

3–74 DocuShare Windows Client SDK

DSGateway Library Objects

Parameter Description

DSAXES_MODE_SHOWWINDOW Instructs DSGateway to display its log window. This

flag can be used for debugging purposes. Once the
window is displayed, use the View menu to toggle
the even log feature. Both flags and mask must
include this flag.

DSAXES_MODE_STDMASK Mask—a combination of the above mode flags for

setting or clearing the selected mode flags.
DSAXES_MODE_STDMASK defines a standard
mask which OR with the following flags:
DSAXES_MODE_SILENT
DSAXES_MODE_USEPROXY
DSAXES_MODE_USEMIMETYPE
DSAXES_MODE_ADDDSCGI
DSAXES_MODE_MEMORIZEUSER
DSAXES_MODE_VIRTUALROOT
DSAXES_MODE_ENABLECACHE
DSAXES_MODE_ENABLEXML

DSAXES_MODE_NOERRORDLG Controls the display of an error dialog box. By

default, DSGateway runs an error dialog when a
network call fails. By setting this flag, you instruct
DSGateway not to run the error dialog and to return
immediately to the caller. The caller may call
GetLastError to retrieve the network error code.

DSAXES_MODE_RENAME1STREPLICATE Instructs DSAXESS to rename the first file to be

replicated in a call to InitiateBulkReplicate to a
name prefixed with Copy of. A call to
InitiateBulkReplicate can set this mode flag prior to
calling InitiateBulkReplicate if it knows that the
target collection already contains a file with the
same name as the first or source file to be
replicated. DSAXESS will rename the first
replicated file to distinguish between the replicated
file and the existing file of the same name. The
replicated filename is renamed as Copy of plus the
original name. For example, for filename business
proposal.doc, the renamed file is Copy of
business proposal.doc.

DocuShare Windows Client SDK 3–75

Objects DSGateway Library

Parameter Description

DSAXES_MODE_WWWAUTH Instructs DSGateway to use the NTLM challenge/

response protocol for user authentication with a
web server. An IDsAxes instance obtained through
IServer.Open sets the state of this flag
automatically to the state obtained from an
IServer.Logon call.
If this flag not set, the contacted web server is
configured to use the NTLM protocol, and the
network call fails because of a challenge response
failure. DSGateway automatically retries with the
NTLM capability; however, retrying can cause
unnecessary delays. If an application knows that
the web server uses the NTLM protocol, it should
set this flag before it invokes a method resulting in a
network call.

DSAXES_MODE_AUTOSETWWWAUTH Controls updating of the

DSAXES_MODE_WWWAUTH mode flag upon
completion of a network call. With the flag set to
TRUE, DSGateway updates the
DSAXES_MODE_WWWAUTH flag to the state
obtained from the last network call. If the flag is
cleared, the DSAXES_MODE_WWWAUTH flag is
not updated.

DSAXES_MODE_NOSERVERSTATUSQUERY Instructs DSGateway to skip the server status query

which is part of a query for top-level collections in a
DocuShare server. With this flag not set and the
collection handle parameter set to 0, DSGateway
performs the server status query and updates the
DSAXES_MODE_READONLY flag whenever
InitiateCollectionOpen or OpenCollection is called.

DSAXES_MODE_ASYNCHRONOUS Instructs IDsAxes methods to return immediately

after a socket is opened. Methods will not wait for
completion of the network call.
To use this mode flag, an application must
subscribe to the IDsAxes event notification. Refer to
Event handling on page 2–77.
The methods which support this mode flag are:
Download, Upload, and SetProps.

Return value
The previous states of all of the mode flags.

3–76 DocuShare Windows Client SDK

DSGateway Library Objects

SetProps

VB SetProps( fPropIdsCore as Long, fPropIds as Long, pItemDisp as Object ) as

Long

C++ long SetProps(long fPropIdsCore, long fPropIds, LPDISPATCH pItemDisp);

The SetProps method set properties for a DocuShare file or collection. This method is also used to set
server access parameters.

Parameters

Parameter Description

fPropIdsCore OR core propId flags

(DSAXES_PROPID_CORE_*) indicates which
core properties to set.

fPropIds OR propId flags (DSAXES_PROPID_*) indicates

which properties to set.

pItemDisp An IItemObj object representing the object

properties to set. Set TypeNum and HandleNum
properties for the DocuShare object item. Set the
item properties as desired.

Return value

Value Description

DSAXES_SUCCESS Request for setting object properties was

successful.

DSAXES_E_BUSY A network call is in progress.

DSAXES_E_HTTP An HTTP error was encounterd.

DSAXES_E_WINSOCK A Winsock error was encountered.

DSAXES_E_FAIL A requested property was not found in IItemObj.

Remarks
If a propId flag is set and a corresponding value is absent from the IItemObj, the method fails.

This method can be operated in asynchronous or synchronous mode.

DocuShare Windows Client SDK 3–77

Objects DSGateway Library

SetShellNotification

VB SetShellNotification( nEventId as Long, pvAbsIDL1 as Variant, pvAbsIDL2 as

Variant ) as Long

C++ long SetShellNotification(long nEventId, VARIANT* pvAbsIDL1, VARIANT*

pvAbsIDL2);

The SetShellNotification method instructs DSAXESS to notify the system shell (DocuShare in Explorer) of
an event whenever the gateway process terminates.

Parameters

Parameter Description

nEventId The value equals a shell change notify event or

zero. If zero, the event ID defaults to
SHCNE_UPDATEDIR.

pvAbsIDL1 A variant whose pbstrVal member is the address

of an absolute shell item ID list that is dependent
on the event ID.

pvAbsIDL2 A variant whose pbstrVal member is the address

of an absolute shell item ID list that is dependent
on the event ID.

Return values

Value Description

DSAXES_SUCCESS DSAXESS has cached the event information and

is ready for notification upon termination.

DSAXES_E_BADPARAM pvAbsIDL1->vt is not VT_BYREF|VT_BSTR.

Remarks
The ID lists should be allocated using SysAllocString. The method determines the list length by calling
SysStringLen.

Upon termination, DSGateway calls SHChangeNotify to pass the parameters given by this method.

If the event is SHCNE_UPDATEDIR, the first item ID list specifies the folder for the updated collection. The
second list is not used and should be set to NULL.

This method is typically called after SetMode DSAXES_MODE_AUTOUPLOAD calls and prior to an
InitiateBulkUpload call or one of the other InitiateBulk... methods.

3–78 DocuShare Windows Client SDK

DSGateway Library Objects

Submit

VB Submit(Request as ClientRequest) as Long

C++ long Submit(IDispatch *Request);

The method Submits an HTTP request encapsulated in a ClientRequest object to a DocuShare server for
processing.

Parameters
Request—A ClientRequest that describes an HTTP request. Alternately, it may contain a SearchRequest
that describes a search request.

Return value

Value Description

DSAXES_SUCCESS The request was submitted successfully.

DSAXES_E_PARSEDATA A request message could not be parsed.

DSAXES_E_SYSRES A command object instantiation failure.

Remarks
Submit is a general-purpose method to send a request to DocuShare. Applications use it in conjunction
with a ClientRequest or SearchRequest to submit a request to a DocuShare server for processing. The
method supersedes InitiateGet and InitiatePost. InitiateGet is a special case of Submit with the
ClientRequest.Method property set to Get, while for InitiatePost.Method is set to Post. A Get request has
no content data, while a Post request is usually accompanied by non-empty content data.

The Submit method returns immediately and the job runs in the background if
GatewaySettings.Asynchronous is set to True. GatewaySettings.Asynchronous is by default set to False.
Therefore, the method runs synchronously and does not return control until the server finishes processing
the request.

When switching on GatewaySettings.Asynchronous, an application may want to subscribe to the

GatewayHandlerEvents notification service so that it is notified when the job is completed. Alternatively, an
application can periodically call GatewayHandler.GetStatus and check the return value. If it is
DSAXES_INPROG, the job is still running. If it is DSAXES_SUCCESS, the job has successfully
completed.

The return value of DSAXES_SUCCESS indicates that the request was successfully processed by the
server, and the response message is stored in ServerResponse. For a Post request,
ServerResponse.ContentData contains the content data the server has sent. Methods and properties of
ContentData can be used to help perform postprocessing such as XML data parsing.

DocuShare Windows Client SDK 3–79

Objects DSGateway Library

Upload

VB Upload( fPropIdsCore as Long, fPropIds as Long, pItemDisp as Object,

pFileName as String ) as Long

C++ long Upload(long fPropIdsCore, long fPropIds, LPDISPATCH pItemDisp,

LPCTSTR pFileName);

The Upload method uploads a file with custom properties or a folder without custom properties to a
DocuShare server.

Parameters

Parameter Description

fPropIdsCore OR core propId flags

(DSAXES_PROPID_CORE_*) indicates which
core properties to set.

fPropIds OR propId flags (DSAXES_PROPID_*) indicates

which item type specific properties to set.

pItemDisp An IItemObj object representing the new

DocuShare object. Set the itemTypeNum property
to:
• DSXITEMTYPE_DOCUMENT if uploading a
new file
• DSXITEMTYPE_VERSION if uploading a new
version
• DSXITEMTYPE_COLLECTION if uploading a
folder
Set the properties appropriate for the new object.
If uploading a new file or folder, set the Parent
property for the item to the handle number of the
parent collection. If uploading a new version, set
the Handle property for the item to the file
DocuShare handle.

pFileName A string containing the fully qualified pathname of

a file to upload.

Return value

Value Description

DSAXES_SUCCESS The network call completed successfully.

DSAXES_E_BUSY A network call is in progress.

DSAXES_E_HTTP An HTTP error was encounterd.

3–80 DocuShare Windows Client SDK

DSGateway Library Objects

Value Description

DSAXES_E_WINSOCK A Winsock error was encountered.

DSAXES_E_FAIL A requested property was not found in IItemObj.

Remarks
When uploading a folder, this method creates a collection and names it after the folder. The method will
upload all files and sub-folders which appear in the folder to the created collection. The method ignores the
fPropIdsCore and fPropIds settings. Property DSHandleList holds a list of the created folders and
uploaded files.

When uploading a new file, you can designate only one parent collection. If an IItemObj contain handles for
multiple parents, only the handle specified in the Parent property is used. InitiateCopy can be used to
propagate the object to other collections.

If a core propId flag or item-specific propId flag is set and a corresponding value is absent from the
IItemObj, the method fails.

This method can be operated in asynchronous or synchronous mode.

DocuShare Windows Client SDK 3–81

Objects DSGateway Library

Wait

VB Wait (Timeout as long, HasResponse as optional Variant ) as long

C++ long Wait( long Timeout, VARIANT* HasResponse );

Wait incrementally waits for completion of an asynchronous gateway operation.

Parameters

Parameter Description

Timeout [in] A timeout value in milliseconds. The method

returns if the wait time exceeds this parameter.

HasResponse [out, optional] True, if the GatewayHandler has a

partial or complete response from a server,
otherwise, it is False.

Return value
The method returns a DSAXES_SUCCESS status code or a DSAXES_E fail status code.

Remarks
If Timeout is set to 0, Wait does not return until an active operation completes. It is equivalent to calling
AwaitCompletion.

3–82 DocuShare Windows Client SDK

DSGateway Library Objects

3.2.1.2 GatewayHandler Properties

This section contains GatewayHandler property definitions.

DSCollHandle

VB DSCollHandle As Long

C++ long GetDSCollHandle();

void SetDSCollHandle(long);

Access Read/Write

The DSCollHandle property designates the collection to be opened or its contents searched.

DocuShare Windows Client SDK 3–83

Objects DSGateway Library

DSContainerHandle

VB DSContainerHandle as String

C++ CString GetDSContainerHandle();

void SetDSContainerHandle( LPCTSTR );

Access Read/Write

DSContainerHandle specifies a DocuShare object handle for the DocuShare container object where a
search is performed. This property works with the Search flag DSSRCH_SCOPE_COLL. See Search on
page 3–67 on use of the flag.

Remarks
The GatewayHandler.Search method uses the handle value in the DSContainerHandle property to restrict
the search to a container and its objects in response to the Search flag DSSRCH_SCOPE_COLL.

If an application writes a Collection handle number to the DSCollHandle integer property, the search scope
is set to the Collection object. DSContainerHandle is then updated to a value, Collection-n, where n is the
handle number specified by DSCollHandle.

An application wanting to search a non-Collection container or a Collection subclass object should use
DSContainerHandle and to specify the handle of the object.

The example below uses DSContainerHandle to limit a search to a Calendar and the search for Event
objects whose titles contain the word, meeting.

set gateway = server.Open

gateway.DSContainerHandle = "Calendar-10"
gateway.DSDisplayName = "meeting"
status = gateway.Search( DSSRCH_SCOPE_COLL or DSSRCH_BY_TITLE, "" )
if status = 0 then
set cd = gateway.ServerResponse.ContentData
set enumObj = ItemDescriptorArray.Enumerator
enumObj.Reset
while enumObj.NextPos <> 0
set itemObj = enumObj.NextItem
Print itemObj.Handle, itemObj.Title
wend
end if

3–84 DocuShare Windows Client SDK

DSGateway Library Objects

DSContent

VB DSContent As String

C++ CString GetDSContent();

void SetDSContent(LPCTSTR);

Access Read/Write

The DSContent property searches the contents of documents. The content value is the string specified
within DSContent.

DSCreatedTimeFrom

VB DSCreatedTimeFrom As Date

C++ DATE GetDSCreatedTimeFrom();

void SetDSCreatedTimeFrom(DATE);

Access Read/Write

The DSCreatedTimeFrom property sets the begin creation time for performing a search.

DSCreatedTimeTo

VB DSCreatedTimeTo As Date

C++ DATE GetDSCreatedTimeTo();

void SetDSCreatedTimeTo(DATE);

Access Read/Write

The DSCreatedTimeTo property sets the end creation time for performing a search.

DocuShare Windows Client SDK 3–85

Objects DSGateway Library

DSDisplayName

VB DSDisplayName As String

C++ CString GetDSDisplayName();

void SetDSDisplayName(LPCTSTR);

Access Read/Write

The DSDisplayName property sets the display name value for performing a search.

DSFileHandle

VB DSFileHandle As Long

C++ long GetDSFileHandle();

void SetDSFileHandle(long);

Access Read/Write

This property is not currently used.

DSFileName

VB DSFileName As String

C++ CString GetDSFileName();

void SetDSFileName(LPCTSTR);

Access Read/Write

The DSFileName property sets the filename value for performing a search.

DSFileType

VB DSFileType As String

C++ CString GetDSFileType();

void SetDSFileType(LPCTSTR);

Access Read/Write

The DSFileType property sets the MIME type when performing a search.

3–86 DocuShare Windows Client SDK

DSGateway Library Objects

DSHandle

VB DSHandle As Long

C++ long GetDSHandle();

void SetDSHandle(long);

Access Read/Write

The DSHandle property sets the handle property for a number of method calls.

Remarks
After a network call completes, DSHandle can be used to obtain a DocuShare handle that the server has
generated in response to the call. The description of the generated handle differs depending on the
method invoked. The following table lists the methods and descriptions.

Method DSHandle Description

DoLoginDialog Handle number of an authenticated user.

Download Handle number of a downloaded filea.

GetProps Handle number of parent (collection) of a queried

object.

InitiateBulkDownload n/ab

InitiateBulkReplicate n/ab

InitiateBulkUpload n/ab

InitiateCollectionCreate Handle number of a created collection.

InitiateCollectionOpen Handle number of an opened collection.

InitiateCopy Handle number of a destination collection.

InitiateDelete Handle number of a deleted item.

InitiateDisown Handle number of one of the remaining parents

(collections).

InitiateDownload Handle number of a downloaded filec.

InitiateGet Handle number of a DocuShare object.

InitiateHistory Handle number of a queried file.

InitiateLock Handle number of a locked/unlocked file.

InitiateMove Handle number of a destination collection.

InitiatePost Handle number of a DocuShare object.

InitiateRename Handle number of a renamed object.

InitiateSearch Number of objects.

DocuShare Windows Client SDK 3–87

Objects DSGateway Library

Method DSHandle Description

InitiateUpload Handle number of an uploaded file.

InitiateUploadEx Handle number of an uploaded file.

InitiateUserAuth Handle number of an authenticated user.

Search Number of a found object.

Upload Handle number of an uploaded filed.

a. Not used for a collection download. Use DSHandleList to obtain a handle list for a collection download.
b. Use DSHandleList to obtain a list of result handles.
c. DSHandle should not be referenced for a representation download.
d. Not used for a collection upload. Use DSHandleList to obtain a handle list for a collection upload.

3–88 DocuShare Windows Client SDK

DSGateway Library Objects

DSHandleList

VB DSHandleList As String

C++ CString GetDSHandleList();

void SetDSHandleList(LPCTSTR);

Access Read/Write

The DSHandle property contains a string list of an item count and item handles.

Remarks
DSHandleList is updated by the methods of InitiateBulkDownload, InitiateBulkUpload, and
InitiateBulkReplicate. The first member of the list is always the item count which is downloaded or
uploaded by one of these methods. The item count is followed by the DocuShare handles of the items. An
item handle is added in the order the item gets downloaded or uploaded.

For InitiateBulkDownload, the handle list contains only downloaded items. For InitiateBulkUpload, the list
contains only uploaded items and includes created collections. For InitiateBulkReplicate, the list contains
both downloaded (source) items and uploaded (destination) items. Downloaded and uploaded items
alternate in the list. Refer to InitiateBulkReplicate on page 3–29 for more information on the handle order.

DocuShare Windows Client SDK 3–89

Objects DSGateway Library

DSItemListFile

VB DSItemListFile As String

C++ CString GetDSItemListFile();

void SetDSItemListFile(LPCTSTR);

Access Read/Write

The DSItemListFile is the local file that is created when successfully returning from a search or after
opening a collection.

Remarks
DSItemListFile contains an informational list about the queried items. A DSItemListFile listing file is
generated following the successful conclusion of one of the following commands.

Command Method Invoked

Open collection InitiateCollectionOpen, OpenCollection

Search items InitiateSearch, Search

Version history InitiateHistory

Use the IEnumObj interface to load a listing file and enumerate the queried items. The following code
opens Collection-123 in a DocuShare server represented by IServer (server), and prints the names of the
items that appear in the collection.

IDsAxes gateway( server.Open() );

if( 0 == gateway.OpenCollection( 123 ) )
{
IEnumObj enumObj;
enumObj.CreateDispatch( "DSITEMENUMLib.EnumObj" );
if( 0 == enumObj.Load( DSCONTF_CHILDREN, gateway.GetDSItemListFile() )
{
enumObj.Reset();
while( enumObj.NextPos )
{
IItemObj itemObj( enumObj.NextItem() );
puts( itemObj.GetTitle() );
}
}
}

3–90 DocuShare Windows Client SDK

DSGateway Library Objects

If DSItemListFile is empty, a temporary filename is assigned to DSItemListFile at the time one of the
command methods is called (see the table above). A temporary listing file is automatically deleted when
the current instance of IDsAxes is expunged.

If an SDK application assigns an arbitrary filename, the SDK application should use a fully qualified
pathname. If a file already exists at the specified path, it is overwritten with the new listing file. Also, the
application should delete the listing file after it is no longer needed.

DocuShare Windows Client SDK 3–91

Objects DSGateway Library

DSItemProp

VB DSItemProp As String

C++ CString GetDSItemProp();

void SetDSItemProp(LPCTSTR);

Access Read/Write

The DSItemProp property enters the name and values for custom properties in a search.

DSKeywords

VB DSKeywords As String

C++ CString GetDSKeywords();

void SetDSKeywords(LPCTSTR);

Access Read/Write

The DSKeywords property enters the keyword values when performing a search.

DSMaxItems

VB DSMaxItems As Long

C++ long GetDSMaxItems();

void SetDSMaxItems(long);

Access Read/Write

The DSMaxItems property limits the number of items to be returned from a search request.

3–92 DocuShare Windows Client SDK

DSGateway Library Objects

DSModifiedTimeFrom

VB DSModifiedTimeFrom As Date

C++ DATE GetDSModifiedTimeFrom();

void SetDSModifiedTimeFrom(DATE);

Access Read/Write

The DSModifiedTimeFrom property sets the beginning of the modified time for performing a search.

DSModifiedTimeTo

VB DSModifiedTimeTo As Date

C++ DATE GetDSModifiedTimeTo();

void SetDSModifiedTimeTo(DATE);

Access Read/Write

The DSModifiedTimeTo method sets the end of the modified time for performing a search.

DocuShare Windows Client SDK 3–93

Objects DSGateway Library

DSObjectHandle

VB DSObjectHandle as String

C++ CString GetDSObjectHandle();

void SetDSObjectHandle( LPCTSTR );

Access Read/Write

DS ObjectHandle contains the handle of a DocuShare object that one of the listed methods uses.

DoLoginDialog InitiateCreateObject InitiateSchema

Download InitiateDelete InitiateSearch

GetProps InitiateDisown InitiateUpload

GetSchema InitiateDownload InitiateUploadEx

InitiateBulkDownload InitiateGet InitiateUserAuth

InitiateBulkReplicate InitiateHistory OpenCollection

InitiateBulkUpload InitiateLock Search

InitiateCollectionCreate InitiateMove SetProps

InitiateCollectionOpen InitiatePost Submit

InitiateCopy InitiateRename Upload

An object handle consists of two parts connected by a hyphen:

• an object type identifier

• a handle number
For example, DSObjectHandle may be set to a collection handle such as File-123 after
GatewayHandler.Upload is called to upload a file.

DSObjectHandle is also used to pass the handle of a custom DocuShare object to GatewayHandler
methods that take an object handle as one of the input parameters. The methods listed in the following
table assume that the target objects are of the predetermined types. A caller can only specify an integer
handle number. The object type cannot be changed. This creates a problem when the target object is a
custom object.

To resolve this problem, the special handle constant DSXHANDLENUM_DSOBJECTHANDLE is used. To

specify a custom object type in a method call, a caller does the following:

1. Sets DSObjectHandle to the custom object's handle.

2. Passes a handle number of DSXHANDLENUM_DSOBJECTHANDLE to the method.

3–94 DocuShare Windows Client SDK

DSGateway Library Objects

Method Handle Parameter Assumed Type

InitiateDownload nFileHandle File

InitiateLock nFileHandle File

InitiateHistory nFileHandle File

InitiateUpload nParentHandle Collection or Filea

InitiateBulkDownload nCollHandle Collection

InitiateBulkUpload nCollHandle Collection

InitiateBulkReplicate nSrcHandle Collection

InitiateCollectionCreate nParentHandle Collection

InitiateCollectionOpen nCollHandle Collection

OpenCollection nCollHandle Collection

ClearCollectionCache nCollHandle Collection

a. If the nFlags parameter contains the DSAXES_FLAG_UPLOADVERSION flag, the object type defaults to File. If not, it
defaults to Collection.

DocuShare Windows Client SDK 3–95

Objects DSGateway Library

DSObjectTypeNum

VB DSObjectTypeNum as Long

C++ long GetDSObjectTypeNum();

void SetDSObjectTypeNum( long );

Access Read/Write

DSObjectTypeNum contains the integer type number of a DocuShare object that a call to one of the
methods mentioned in DSObjectHandle has affected. The handle number, which is the other part of an
object handle, is contained in property DSHandle. To convert a type number to a character string type
identifier, set ItemObj.TypeNum to the type number. The string identifier can be read from ItemObj.Handle.

NOTE: A type number assigned to a custom object type is specific to the client machine and is not
transferable to another machine.

DSOwner

VB DSOwner As String

C++ CString GetDSOwner();

void SetDSOwner(LPCTSTR);

Access Read/Write

The DSOwner property limits the search scope to a specific owner.

3–96 DocuShare Windows Client SDK

DSGateway Library Objects

DSTime

VB DSTime As Date

C++ DATE GetDSTime();

void SetDSTime(DATE);

Access ReadWrite

The DSTime property returns the DocuShare processing time for the last command issued by this IDsAxes
object. The time is adjusted for the local time zone.

Remarks
IDsAxes updates the LocalTime property value whenever DSTime is updated as a result of processing a
DocuShare command. If the server and client machines are in synchronization, DSTime equals LocalTime.
The difference between the two shows how much one lags behind the other.

DSVersion

VB DSVersion As String

C++ CString GetDSVersion();

void SetDSVersion(LPCTSTR);

Access Read/Write

The DSVersion property specifies the version number of a DocuShare server last contacted by this
IDsAxes object.

Remarks
The high 16-bit word is the major version number. The low 16-bit word is the minor version number.

IDsAxes gateway;
...
DWORD dwVer = gateway.GetDSVersion();
printf( "Major version=%X, Minor version=%X\n", HIWORD(dwVer), LOWORD(dwVer)
);
Although an application can set an arbitrary value in DSVersion, this does not affect the DocuShare server.

DocuShare Windows Client SDK 3–97

Objects DSGateway Library

LocalTime

VB LocalTime As Date

C++ DATE GetLocalTime();

void SetLocalTime(DATE);

Access Read/Write

The LocalTime property returns:

• The time for the local PC/Server that is running the DSAxess gateway.
• The time (in the local time zone) whenever DSTime is updated as a result of processing a
DocuShare command.

Remarks
If the server and client machines are in synchronization, DSTime equals LocalTime. The difference
between the two shows how much one lags behind the other.

PropAttrlds

VB Property PropAttrIds As Long

C++ long IDsAxes::GetPropAttrIds()

void IDsAxes::SetPropAttrIds(long)

Access Read/Write

The PropAttrIds method sets the query depth level for opening a collection.

Remarks
Refer to InitiateCollectionOpen on page 3–34 for information on utilizing this property.

3–98 DocuShare Windows Client SDK

DSGateway Library Objects

Proplds

VB PropIds As Long

C++ long GetPropIds();

void SetPropIds(long);

Access Read/Write

PropIds sets the properties to be searched or to open a collection.

Remarks
The PropIds property works in conjunction with methods InitiateCollectionOpen, OpenCollection and
Search. These methods query only those item type specific properties as specified by the property IDs set
by SetItemPropIds, and core properties as specified by the property IDs for IDsAxes.PropIds.

The following core properties are queried by default.

Core Property Property of ItemObj

DSAXES_PROPID_CORE_TITLE Title

DSAXES_PROPID_CORE_SUMMARY Summary

DSAXES_PROPID_CORE_OWNER Owner

DSAXES_PROPID_CORE_CREATEDATE TimeCreated

DSAXES_PROPID_CORE_MODIFIEDDATE TimeModified

DSAXES_PROPID_CORE_MODIFIEDBY User

DSAXES_PROPID_CORE_PARENTHANDLES Parent, ParentCount

Constant DSAXES_PROPID_CORE_DEFAULT_QUERY includes all of the above core property IDs. If an

SDK application needs to query a different set of properties when using OpenCollection or Search, it
should modify the core property set by specifying necessary property IDs in the PropIds property. The
other available core properties are listed below.

Core Property Property of ItemObj

DSAXES_PROPID_CORE_DESCRIPTION Description

DSAXES_PROPID_CORE_KEYWORDS Keywords

Refer to SetItemProplds on page 3–68 for the list of default item type specific properties that the above
methods use.

DocuShare Windows Client SDK 3–99

Objects DSGateway Library

GatewayClient

VB GatewayClient as Object GatewayClient

C++ IDispatch* GetGatewayClient();

void SetGatewayClient( IDispatch* );

Access Read/Write

A GatewayClient object associated with the current instance of GatewayHandler. An SDK application uses
GatewayClient to identify itself to the client gateway. The object is also used to obtain network settings for
the client machine and the internal gateway parameters for posting a canceled event to stop a network
operation.

set gateway = server.OpenGateway

gateway.GatewayClient.ID = 1
gateway.GatewayClient.Name = "My DocuShare Test Script"

NOTE: The method GatewayHandler.RegisterClient updates the ID and Name properties of

GatewayClient.

set gateway = server.OpenGateway

gateway.RegisterClient True, 1, "My DocuShare Test Script", cookie
Passing a False to RegisterClient clears GatewayClient.ID and GatewayClient.Name, and unregisters the
client from the gateway.

gateway.RegisterClient False, 0, "", cookie

3–100 DocuShare Windows Client SDK

DSGateway Library Objects

GatewaySettings

VB GatewaySettings as Object GatewaySettings

C++ IDispatch* GetGatewaySettings();

Access Read only

A GatewaySettings object associated with the current instance of GatewayHandler. GatewaySettings is

used to manage gateway control settings to include how long the gateway should wait for the server to
respond and if a DocuShare operation should run asynchronously.

The following example shows use of GatewaySettings to upload data silently and quit the operation if the
server does not respond within 30 seconds.

set gateway = CreateObject( "DSGateway.GatewayHandler" )

gateway.DSAccessData.DocuShareAddress = "http://ds.xyz.com/"
gateway.DSAccessData.AuthToken = "**********"
gateway.GatewaySettings.AddDSCGI = true
gateway.GatewaySettings.Silent = true
gateway.GatewaySettings.HttpRequestTimeout = 30000
set request = CreateObject( "DSGateway.ClientRequest" )
request.Method = "POST"
request.RequestURI = "ApplyUpload/Collection-10"
request.ContentType = "multipart/form-data; boundary=xyz123"
request.ContentData.Text = "..[form data ommitted].."
status = gateway.Submit( request )

DocuShare Windows Client SDK 3–101

Objects DSGateway Library

DSAccessData

VB DSAccessData as Object DSAccessData

C++ IDispatch* GetIDSAccessData();

Access Read only

A DSAccessData object associated with the current instance of GatewayHandler. DSAccessData is used
to manage the web server, DocuShare server, and other network access control parameters for
establishing connections to a DocuShare server.

The following VB script uses DSAccessData to specify a DocuShare server and to submit a collection
query.

set gateway = CreateObject( "DSGateway.GatewayHandler" )

gateway.DSAccessData.DocuShareAddress = "http://ds.xyz.com/"
gateway.GatewaySettings.AddDSCGI = true
set request = CreateObject( "DSGateway.ClientRequest" )
request.Method = "POST"
request.Header( "Depth" ) = 1
request.RequestURI = "PROPFIND/Collection-10"
status = gateway.Submit( request )
MsgBox gateway.ServerResponse.MessageHeader,_
vbOK,_
gateway.DSAccessData.DocuShareAddress

3–102 DocuShare Windows Client SDK

DSGateway Library Objects

ClientRequest

VB ClientRequest as Object ClientRequest

C++ IDispatch* GetClientRequest();

Access Read only

A ClientRequest object associated with the current instance of GatewayHandler. ClientRequest is used to
generate an HTTP request message. It is also used to read, modify, or both, parts of a request message.

An HTTP request message consists of three basic parts:

• Request line consisting of method, URI, and HTTP version strings—corresponds to the
ClientRequest properties of Method, RequestURI, and to HTTPVersionMajor and HTTPVersionMinor.
• Message header—corresponds to the MessageHeader property. An individual field of a message
header is accessible through the property Header.
• Content data—corresponds to the ContentData object property. ContentData exposes the content data
through four storage accessor properties: a traditional file, an OLE stream, text data, and an XMLDOM
document. ClientRequest looks at the ContentData.StorageMedium property to determine whether the
content data resides in a file or on a stream. If StorageMedium is set to STGMEDIUM_FILE,
ContentData.File is used to locate and load the data source.
For a DocuShare operation, the request method is typically POST. The URI is a DocuShare HTTP/XML
verb such as PROPFIND, followed by an operand, such as Collection handle. The HTTP version that the
gateway supports is HTTP/1.1.

NOTE: For details on the HTTP request message format, refer to RFC 2616, Hypertext Transfer
Protocol -- HTTP/1.1.

ClientRequest can be created independently of the GatewayHandler interface and also used to pass a
custom HTTP request message to the GatewayHandler.Submit method for submission to a DocuShare
server for processing.

The following is an example script that uses an independent ClientRequest to generate a PROPFIND
request message and calls GatewayHandler.Submit to send the request to a DocuShare server.

set gateway = CreateObject("DSGateway.GatewayHandler")

gateway.DSAccessData.DocuShareAddress = "http://ds.xyz.com/"
gateway.GatewaySettings.AddDSCGI = true
set request = CreateObject("DSGateway.ClientRequest")
request.Method = "POST"
request.Header("Depth") = 1
request.RequestURI = "PROPFIND/Collection-10"
request.ContentData.Text = _
"<?xml version="+chr(&H22)+"1.0"+chr(&H22)+" ?>" & _
"<propfind>" & _

DocuShare Windows Client SDK 3–103

Objects DSGateway Library

"<prop>" & _
"<displayname/>" & _
"<summary/>" & _
"</prop>" & _
"</propfind>"
status = gateway.Submit(request)

3–104 DocuShare Windows Client SDK

DSGateway Library Objects

ServerResponse

VB ServerResponse as Object ServerResponse

C++ IDispatch* GetServerResponse();

Access Read only

A ServerResponse object associated with the current instance of GatewayHandler. ServerResponse

provides access to an HTTP response message from a DocuShare server.

An HTTP response message consists of three basic parts:

• Status line consisting of result code, result phrase, and HTTP version—the entire status line can be
read from ServerResponse.StatusLine. The result code is in ServerResponse.HTTPResultCode.
• Message header—the entire message header is in ServerResponse.MessageHeader. A message
header contain fields generated by DocuShare. They can include DocuShare-Handle and DocuShare-
Version which are stored in ServerResponse.DSHandle and ServerResponse.DSVersion, respectively.
• Content data—is used to read the content data sent from DocuShare.

NOTE: For details on the HTTP response message format, refer to RFC 2616, Hypertext Transfer
Protocol -- HTTP/1.1.

The following script uses ServerResponse to print the header and content data of a PROPFIND response
message.

set gateway = CreateObject("DSGateway.GatewayHandler")

gateway.DSAccessData.DocuShareAddress = "http://ds.xyz.com/"
gateway.GatewaySettings.AddDSCGI = true
set request = CreateObject("DSGateway.ClientRequest")
request.Method = "POST"
request.Header("Depth") = 0
request.RequestURI = "PROPFIND/File-1234"
if gateway.Submit(request) = 0 then
MsgBox gateway.ServerResponse.MessageHeader, , "MessageHeader"
MsgBox gateway.ServerResponse.ContentData.Text, , "ContentData"
end if

set gateway = CreateObject("DSGateway.GatewayHandler")

gateway.DSAccessData.DocuShareAddress = "http://ds.xyz.com/"
gateway.GatewaySettings.AddDSCGI = true
set request = CreateObject("DSGateway.ClientRequest")
request.Method = "POST"
request.Header("Depth") = 0

DocuShare Windows Client SDK 3–105

Objects DSGateway Library

request.RequestURI = "PROPFIND/File-1234"
if gateway.Submit(request) = 0 then
MsgBox gateway.ServerResponse.MessageHeader, , "MessageHeader"
MsgBox gateway.ServerResponse.ContentData.Text, , "ContentData"
end if

It is possible to use ServerResponse to progressively retrieve a response from DocuShare as it arrives at

the gateway. To do so, an application needs to subscribe to the GatewayHandlerEvents event notification
service. With the event hookup properly made, the gateway invokes the application's Receive event
handling code whenever a data packet of the server response arrives. The application then can
incrementally inspect the incoming packet and take an action without waiting for the entire response
message.

The VB code below illustrate how the event-driven inspection of a response message can be achieved
using GatewayHandlerEvents and ServerResponse.

dim WithEvents gatewayEvents as GatewayHandlerEvents

dim gateway as GatewayHandler
dim hasHeader as boolean
...
private sub gatewayEvents_Receive(...)
set resp = gateway.ServerResponse
if not hasHeader then
if InStr(resp.MessageHeader, vbCr+vbCr) > 0 then
hasHeader = true
end if
else
Print resp.ContentData.Delta
end if
end sub
An HTTP response message may require further processing than inspecting the resulting code and
retrieving the DocuShare handle value from the message header. An application may want to display
queried items in a row-column table. To do so, the application needs to parse XML data DocuShare sends.

To access the content data portion of a response message, an application uses the ContentData property
of ServerResponse. It then utilizes the dedicated data parsing methods of ContentData and loads the XML
data into a property enumeration object or an item enumeration object. Enumeration objects are used to
perform programmatic enumeration of DocuShare objects and object properties. ContentData also has
Text and XMLDOM properties. If raw data needs to be accessed, these properties can be used.

The following examples show how ServerResponse.ContentData is used to parse and generate
enumerators.

3–106 DocuShare Windows Client SDK

DSGateway Library Objects

Example 1
This example shows how to obtain an item enumerator for a collection and print the handle, title, and
summary of each item in the collection.

set gateway = CreateObject("DSGateway.GatewayHandler")

gateway.DSAccessData.DocuShareAddress = "http://ds.xyz.com/"
gateway.GatewaySettings.AddDSCGI = true
set request = CreateObject("DSGateway.ClientRequest")
request.Method = "POST"
request.Header("Depth") = 1
request.RequestURI = "PROPFIND/Collection-10"
status = gateway.Submit(request)
set response = gateway.ServerResponse
response.ContentData.ParseDirectory
set enumObj = response.ContentData.ItemDescriptorArray.Enumerator
enumObj.Reset
while enumObj.NextPos
set itemObj = enumObj.NextItem
PrintRow itemObj.Handle, itemObj.Title, itemObj.Summary
wend

Example 2
This example retrieves and lists DocuShare properties of a file.

set gateway = CreateObject("DSGateway.GatewayHandler")

gateway.DSAccessData.DocuShareAddress = "http://ds.xyz.com/"
gateway.GatewaySettings.AddDSCGI = true
set request = CreateObject("DSGateway.ClientRequest")
request.Method = "POST"
request.Header("Depth") = 0
request.RequestURI = "PROPFIND/File-1234"
status = gateway.Submit(request)
set response = gateway.ServerResponse
response.ContentData.ParseProperties
set props = response.ContentData.ItemProperties
for i = 1 to props.Count
set prop = props.ItemProperty(i)
PrintRow prop.DisplayName, prop.Value
wend

DocuShare Windows Client SDK 3–107

Objects DSGateway Library

NOTE: The examples above do not check the return values from Submit and Parsing functions.

3–108 DocuShare Windows Client SDK

DSGateway Library Objects

3.2.2 GatewayClient
List of GatewayClient methods and properties.

Methods and Properties

CancelCode

CancelWindow

ID

IPAddress

Name

Port

WindowHandle

3.2.2.1 GateClient Methods

There are no methods defined for this object.

3.2.2.2 GatewayClient Properties

This section contains GatewayClient property definitions.

CancelCode

VB CancelCode as Long

C++ long GetCancelCode();

Access Read only

CancelCode contains a window message code for canceling a gateway operation.

Remarks
The example below uses CancelCode and CancelWindow to post a cancel message from a UI thread to a
gateway running on a worker thread.

// Global variables
HWND g_hwndCancel;
LONG g_msgCancel;
...
// A worker thread opens a gateway and keeps the handler
// in variable pGatewayHandler. GatewayClient is obtained,
// and cancel parameters are retrieved and saved in global
// variables.
IGatewayClient* pClient;

DocuShare Windows Client SDK 3–109

Objects DSGateway Library

pGatewayHandler->get_GatewayClient( &pClient );
pClient->get_CancelWindow( (OLE_HANDLE)&g_hwndCancel );
pClient->get_CancelCode( &g_msgCancel );
pClient->Release();
...
// UI thread detects cancellation by a user.
// Set lParam to TRUE to cancel immediately.
::PostMessage( g_hwndCancel, g_msgCancel, 0, TRUE );

CancelWindow

VB CancelWindow as OLE_HANDLE

C++ HWND GetCancelWindow();

Access Read only

CancelWindow contains the handle of a window the gateway handler creates to which a cancel notification
can be posted using the Win32 API PostMessage.

ID

VB ID as String

C++ CString GetID();

void SetID( LPCTSTR );

Access Read/Write

ID contains a unique identifier of a client application.

Remarks
GatewayHandler.RegisterClient updates this property.

3–110 DocuShare Windows Client SDK

DSGateway Library Objects

IPAddress

VB IPAddress as String

C++ CString GetIPAddress();

Access Read only

IPAddress contains the IP address of the client machine.

Remarks
The IP address is available after a GatewayHandler object associated with the GatewayClient object
successfully initiates a socket connection to a web server.

Name

VB Name as String

C++ CString GetName();

void SetName( LPCTSTR );

Access Read/Write

Name contains the name of a client application.

Remarks
GatewayHandler.RegisterClient updates this property.

DocuShare Windows Client SDK 3–111

Objects DSGateway Library

Port

VB Port as Long

C++ long GetPort();

Access Read only

Port contains the port number the gateway uses to open a socket for connecting to a web server.

Remarks
The port number is available after a GatewayHandler object associated with the GatewayClient object
successfully initiates a socket connection to a web server.

WindowHandle

VB WindowHandle as OLE_HANDLE

C++ HWND GetWindowHandle();

void SetWindowHandle( HWND );

Access Read/Write

WindowHandle contains the handle of a client application window which owns the GatewayHandler
instance associated with the GatewayClient.

Remarks
A client application uses this property to inform a gateway which windows are active and should be used
for performing window operations. The gateway uses the window handle to associate a status UI it runs
with a proper client window. If WindowHandle is empty, the gateway uses a handle returned by the Win32
API function GetActiveWindow.

3–112 DocuShare Windows Client SDK

DSGateway Library Objects

3.2.3 GatewaySettings
List of GatewaySettings methods and properties.

GatewaySettings Methods and Properties

AddDSCGI LoadablePropIdsCore

Asynchronous LoadablePropsStore

AutoSetWWWAuth LoadDefaultProps

CacheExpireMinutes NameConflictResolver

CanKeepAlive NoErrorDialog

CompressRequestData NoServerStatusQuery

CompressResponseData PromptOnDownloadNameClash

CopyAllVersions PromptOnUploadNameClash

DefNewFileMaxVersions PropertyAttributeIDs

EnableCache QueriedProperties

ErrorDisplayStatus QueriedPropertyIDs

ErrorReportObject ReceptionTimeOut

File RenameFirstReplicate

FileFilter Silent

HttpRequestTimeout StatusObject

IgnoreFileTypeOnCompress StorageMedium

IgnoreMIMEType TransmissionBufferSize

ItemDescriptorArrayFile TransmissionPause

ItemDescriptorArrayStorage TransmissionTimeOut

LanguageTag UploadAlwaysAsNewDoc

LoadablePropIds

3.2.3.1 GatewaySettings methods

There are no methods defined for this object.

DocuShare Windows Client SDK 3–113

Objects DSGateway Library

3.2.3.2 GatewaySettings properties

This section contains GatewayClient property definitions.

AddDSCGI

VB AddDSCGI as boolean

C++ BOOL GetAddDSCGI();

void SetAddDSCGI( BOOL );

Access Read/Write

AddDSCGI determines if a dscgi/ds.py path specifier should be appended to a server base URL when
forming a DocuShare command URL, such as http://ds.xyz.com/dscgi/ds.py/View/File-123.

Remarks
This property corresponds to the GatewayHandler mode flag DSAXES_MODE_ADDDSCGI.

Asynchronous

VB Property Asynchronous as boolean

C++

Access Read/Write

Asynchronous determines if the gateway should send a request to a DocuShare server asynchronously by
sending a request and waiting for a response in the background.

Remarks
This property corresponds to the GatewayHandler mode flag DSAXES_MODE_ASYNCHRONOUS.

3–114 DocuShare Windows Client SDK

DSGateway Library Objects

AutoSetWWWAuth

VB AutoSetWWWAuth as boolean

C++ BOOL GetAutoSetWWWAuth();

void SetAutoSetWWWAuth( BOOL );

Access Read/Write

AutoSetWWWAuth determines if the gateway should automatically update the

DSAccessData.CapabilityFlags property, which is dependent on whether a web server enforces access
authentication or not.

Remarks
A web server may engage in access authentication using one of the following standard methods supported
by the DocuShare client gateway:

• NTLM
• Basic
• Digest
The gateway determines the authentication method by inspecting the value of a WWW-Authenticate field
in a response header from DocuShare.

The default value is True. The default value may be modified by specifying a different value for the registry
entry AutoSetWWWAuth, [HKCU\Software\Xerox\DocuShare Client\DsAxess\Settings]

AutoSetWWWAuth=dword:????????

This property corresponds to the GatewayHandler mode flag DSAXES_MODE_AUTOSETWWWAUTH.

CacheExpireMinutes

VB CacheExpireMinutes as long

C++ long GetCacheExpireMinutes();

void SetCacheExpireMinutes( long );

Access Read/Write

CacheExpireMinutes specifies how long a collection's item listing data should remain valid.

Remarks
The default expiration is 5 minutes. The default value may be modified by specifying a different value for
the registry entry CacheExpireMinutes, [HKCU\Software\Xerox\DocuShare Client\DsAxess\Settings]

CacheExpireMinutes=dword:????????

DocuShare Windows Client SDK 3–115

Objects DSGateway Library

CanKeepAlive

VB CanKeepAlive as boolean

C++ BOOL GetCanKeepAlive();

void SetCanKeepAlive( BOOL );

Access Read/Write

CanKeepAlive determines if the gateway should use a persistent connection with a DocuShare server. If
CanKeepAlive is True, the gateway requests the server to keep the connected socket open even after the
request is processed so that a subsequent client request can be sent immediately without the overhead of
opening a new socket.

Remarks
The default value is False. The gateway does not request the server to keep the connection.

When CanKeepAlive is True, the gateway adds a Connection header field to a request message to be sent
to the server, and sets the field value to Keep-Alive. If CanKeepAlive is False, the gateway does not add a
Connection header field. The web server may still respond with a Connection header field set to Keep-
Alive despite the client-side setting. In this case, the gateway will respect the server's persistence request
and keep the socket open.

CompressRequestData

VB CompressRequestData as boolean

C++ BOOL GetCompressRequestData();

void SetCompressRequestData( BOOL );

Access Read/Write

CompressRequestData determines if the gateway should compress the content data of a request
message based on the gzip compression method.

Remarks
Up to and including version 3.1, DocuShare does not support gzip compression.

3–116 DocuShare Windows Client SDK

DSGateway Library Objects

CompressResponseData

VB CompressResponseData as boolean

C++ BOOL GetCompressResponseData();

void SetCompressResponseData( BOOL );

Access Read/Write

CompressResponseData determines if the gateway should request DocuShare to use a gzip-based

compression when sending content data in a response.

Remarks
Up to and including version 3.1, DocuShare does not support gzip compression.

CopyAllVersions

VB CopyAllVersions as boolean

C++ BOOL GetCopyAllVersions();

void SetCopyAllVersions( BOOL );

Access Read/Write

CopyAllVersions determines if the gateway should download or replicate all versions of files instead of
downloading or replicating the latest versions.

Remarks
The property applies to the following GatewayHandler bulk methods:

• InitiateBulkDownload
• InitiateBulkReplicate
For a versions download operation started by InitiateBulkDownload, the gateway creates a subfolder using
the name of the file, and downloads the file versions into the subfolder. A downloaded file version (through
InitiateBulkDownload) receives a filename prefixed with a file handle and version number of form
[File-123_10 , where the file handle is File-123 and the version number is 10. The part of the filename that
follows the prefix is the filename of the version in DocuShare.

Versions download or replication is limited to the preferred rendition. No other content elements of the
document are downloaded or replicated.

This property corresponds to the GatewayHandler mode flag DSAXES_MODE_COPYVERSIONS.

DocuShare Windows Client SDK 3–117

Objects DSGateway Library

DefNewFileMaxVersions

VB Property DefNewFileMaxVersions as long

C++

Access Read/Write

Contains a default value for the DocuShare max_versions property. The max_versions property sets the
maximum number of versions a DocuShare server reserves for a newly uploaded file.

Remarks
The property affects the following GatewayHandler methods:

• Upload—DefNewFileMaxVersions is used if ItemObj.MaxVersions of pItemDisp is not defined.

• InitiateUpload—DefNewFileMaxVersions is always used.
The default value is 4. The default value may be modified by specifying a different value for the registry
entry DefNewFileMaxVersions, [HKCU\Software\Xerox\DocuShare Client\DsAxess\Settings]

DefNewFileMaxVersions=dword:

EnableCache

VB EnableCache as boolean

C++ BOOL GetEnableCache();

void SetEnableCache( BOOL );

Access Read/Write

EnableCache determines if the client gateway should cache directory information. The default value is
False.

Remarks
This property corresponds to the GatewayHandler mode flag DSAXES_MODE_ENABLECACHE.

3–118 DocuShare Windows Client SDK

DSGateway Library Objects

ErrorDisplayStatus

VB ErrorDisplayStatus as DSX_ERRDISP

C++ DSX_ERRDISP GetErrorDisplayStatus();

void SetErrorDisplayStatus( DSX_ERRDISP );

Access Read/Write

ErrorDisplayStatus contains one of the following DSX_ERRDISP flags.

Flag Description

ERRDISP_CUSTOM The gateway ran a custom error dialog.

ERRDISP_DETAIL The gateway ran a detailed error dialog.

ERRDISP_MSGBOX The gateway ran a message box dialog.

ERRDISP_NONE The gateway has not displayed any dialog box.

ERRDISP_SIMPLE The gateway ran a simple error dialog.

ErrorReportObject

VB ErrorReportObject as Object ErrorReportObj

C++ IDispatch* GetErrorReportObject();

void SetErrorReportObject( IDispatch* );

Access Read/Write

ErrorReportObject contains an error report object of interface IErrorReportObj. ErrorReportObject

manages error information generated by a DocuShare server or GatewayHandler.

File

VB File as String

C++ CString GetFile();

void SetFile( LPCTSTR );

Access Read/Write

File contains the pathname of a file that the gateway uses to store a response from a DocuShare server.

DocuShare Windows Client SDK 3–119

Objects DSGateway Library

FileFilter

VB FileFilter as string

C++ CString GetFileFilter();

void SetFileFilter( LPCTSTR );

Access Read/Write

FileFilter contains a file filter, such as *.doc, for restricting by type files, in a client machine to be uploaded.

Remarks
The property applies to GatewayHandler.InitiateBulkUpload. This script uses FileFilter to upload all .doc
files in the My Documents folder to DocuShare.

set gateway = server.OpenGateway

gateway.GatewaySettings.FileFilter = "*.doc"
gateway.InitiateBulkUpload( _
10, _
-1, _
"C:\My Documents", _
"http://ds.xyz.com/dscgi/ds.py/", _
"...", _
"" )

The above code is equivalent to gateway.InitiateBulkUpload( _

10, _
-1, _
"C:\My Documents\*.doc", _
"http://ds.xyz.com/dscgi/ds.py/", _
"...", _
"" )

3–120 DocuShare Windows Client SDK

DSGateway Library Objects

HttpRequestTimeout

VB HttpRequestTimeout as long

C++ long GetHttpRequestTimeout();

void SetHttpRequestTimeout( long );

Access Read/Write

HttpRequestTimeout contains a timeout setting for initiation of data reception from a connected socket. If a
data packet does not start arriving within the amount of time in HttpRequestTimeout after a request
message is sent, the gateway aborts the data reception and raises a socket error WSAETIMEDOUT.

Remarks
The default value is 240,000 milliseconds (4 minutes). The default value can be modified by specifying a
different value for the registry entry HttpRequestTimeout,
[HKCU\Software\Xerox\DocuShare Client\DsAxess\Settings]

HttpRequestTimeout=dword:

DocuShare Windows Client SDK 3–121

Objects DSGateway Library

IgnoreFileTypeOnCompress

VB IgnoreFileTypeOnCompress as boolean

C++ BOOL GetIgnoreFileTypeOnCompress();

void SetIgnoreFileTypeOnCompress( BOOL );

Access Read/Write

IgnoreFileTypeOnCompress determines if the gateway should compress a file to be uploaded regardless

of file type. CompressRequestData must be True for IgnoreFileTypeOnCompress to be effective.

Remarks
DocuShare 3.1 or lower does not support compressed file upload.

The property affects the following gateway methods:

• Upload
• InitiateUpload
• InitiateUploadEx
• InitiateBulkUpload
• InitiateBulkReplicate
If IgnoreFileTypeOnCompress is False, the gateway checks the MIME type of the file for a compressed
format. If it is not compressed, the file is compressed in gzip. The following compressed content types are
automatically excluded from compression if IgnoreFileTypeOnCompress is False:

• application/x-zip-compressed
• application/x-gzip
• application/x-compress
• application/x-tar
• image/jpeg
• video/mpeg
If the MIME type is not available, the file extension name is inspected. Files of the following extension
names are also excluded:

• .zip
• .gz
• .z
• .tar
• .cab
• .jpg
• .jpeg
• .mpg
• .mpeg

3–122 DocuShare Windows Client SDK

DSGateway Library Objects

IgnoreMIMEType

VB IgnoreMIMEType as boolean

C++ BOOL GetIgnoreMIMEType();

void SetIgnoreMIMEType( BOOL );

Access Read/Write

IgnoreMIMEType determins if the gateway should set the content type of a file to be uploaded as binary
type application/octet-stream regardless of the presence of a caller-supplied content type when a upload
method is called. If IgnoreMIMEType is True, the binary type is used.

Remarks
The default value is False. The default value can be modified by specifying a different value for the registry
entry IgnoreMimeType, [HKCU\Software\Xerox\DocuShare Client\DsAxess\Settings]

IgnoreMimeType=dword:

This property affects the following GatewayHandler methods.

Method Affected Parameter

Upload ItemObj.MimeType of parameter pItemDisp

InitiateUpload pszMimeType

InitiateBulkUpload DSAXES_PROPID_FILE_MIMETYPE settings in

the DSXCOLLECTIONITEMINFO structures
contained in pPathList

This property inversely corresponds to the GatewayHandler mode flag DSAXES_MODE_USEMIMETYPE.

If IgnoreMIMEType is True, DSAXES_MODE_USEMIMETYPE is False, and vice versa.

ItemDescriptorArrayFile

VB ItemDescriptorArrayFile as String

C++ CString GetItemDescriptorArrayFile();

void SetItemDescriptorArrayFile( LPCTSTR );

Access Read/Write

ItemDescriptorArrayFile contains the file pathname that the gateway uses to store an item descriptor array
generated from XLM data in a response from a DocuShare server.

DocuShare Windows Client SDK 3–123

Objects DSGateway Library

ItemDescriptorArrayStorage

VB ItemDescriptorArrayStorage as DSX_STGMEDIUM

C++ DSX_STGMEDIUM GetItemDescriptorArrayStorage();

void SetItemDescriptorArrayStorage( DSX_STGMEDIUM );

Access Read/Write

ItemDescriptorArrayStorage determines the type of storage medium that the gateway uses to store a
response from a DocuShare server.

LanguageTag

VB LanguageTag as string

C++ CString GetLanguageTag();

void SetLanguageTag( LPCTSTR );

Access Read/Write

LanguageTag contains a Lang-Tag setting for specifying a language for a DocuShare server in rendering a
response.

Remarks
Lang-Tag is a header field in an HTTP message a gateway generates to execute a DocuShare command.

The US English Lang-Tag value is en-US. The default value of LanguageTag is "*" which tells a server to
use the default language.

3–124 DocuShare Windows Client SDK

DSGateway Library Objects

LoadablePropIds

VB LoadablePropIds as long

C++ long GetLoadablePropIds();

void SetLoadablePropIds( long );

Access Read/Write

LoadablePropIds contains DSAXES_PROPID property identifiers specific to the type of an object to be

uploaded or created in DocuShare that specify DocuShare properties whose default values are loaded
from a properties store.

Remarks
See LoadDefaultProps on how LoadablePropIds is used to perform the loading of property values.

LoadablePropIdsCore

VB LoadablePropIdsCore as long

C++ long GetLoadablePropIdsCore();

void SetLoadablePropIdsCore( long );

Access Read/Write

LoadablePropIdsCore contains core DSAXES_PROPID property identifiers that specify DocuShare

properties whose default values are to be loaded from a properties store.

Remarks
See LoadDefaultProps on how LoadablePropIdsCore is used to perform the loading of property values.

LoadablePropsStore

VB Property LoadablePropsStore as string

C++

Access Read/Write

LoadablePropsStore contains the name of a property value storage that exists in the DSClient section of
the system registry. If LoadablePropsStore is not set, the default store of SDKProps is used.

Remarks
See LoadDefaultProps on how LoadablePropsStore is used to perform the loading of property values.

DocuShare Windows Client SDK 3–125

Objects DSGateway Library

LoadDefaultProps

VB LoadDefaultProps as boolean

C++ BOOL GetLoadDefaultProps();

void SetLoadDefaultProps( BOOL );

Access Read/Write

LoadDefaultProps determines if an upload method should set DocuShare object properties to default
values loaded from a local properties store.

Remarks
The gateway uses the ItemObj.LoadDefaultProps method, for the ItemObj object in the pItemDisp
parameter of the GatewayHandler.Upload method, to load default property values. It calls the method to
pass the values in LoadablePropIdsCore, LoadablePropIds and LoadablePropStore.

ItemObj.LoadDefaultProps( LoadablePropIdsCore, LoadablePropIds, LoadablePropStore )

Refer to the Objects on page 5–4 for more details on the LoadDefaultProps method.

The loaded property values as well as the content data of the file to be uploaded are used to generate an
HTTP multi-part request message for the DocuShare HTTP/XML ApplyUpload command or an HTTP XML
request message for the MKCOL or MKRES command for creating a container object.

The property applies to the following GatewayHandler methods.

Method HTTP/XML

Upload ApplyUpload

InitiateBulkUpload ApplyUpload

InitiateBulkReplicate ApplyUpload

InitiateCreateObject MKCOL or MKRES

This property corresponds to the GatewayHandler mode flag DSAXES_MODE_LOADDEFPROPS.

3–126 DocuShare Windows Client SDK

DSGateway Library Objects

NameConflictResolver

VB NameConflictResolver as NameConflictResolver

C++ IDispatch* GetNameConflictResolver();

void SetNameConflictResolver( IDispatch* );

Access Read/Write

A name conflict resolution object of interface INameConflictResolver. NameConflictResolver runs a UI to

resolve a name conflict between a file or folder in a client machine and an item on a DocuShare server.

NoErrorDialog

VB NoErrorDialog as boolean

C++ BOOL GetNoErrorDialog();

void SetNoErrorDialog( BOOL );

Access Read/Write

NoErrorDialog determines if the client gateway should not run an error report dialog after a connection to a
DocuShare server or the processing by the server fails. The default value of NoErrorDialog is False.

Remarks
This property corresponds to the GatewayHandler mode flag DSAXES_MODE_NOERRORDLG.

NoServerStatusQuery

VB NoServerStatusQuery as boolean

C++ BOOL GetNoServerStatusQuery();

void SetNoServerStatusQuery( BOOL );

Access Read/Write

NoServerStatusQuery determines if a call to InitiateCollectionOpen or OpenCollection for a server's root

collection should or not invoke a server status query prior to the collection query. If NoServerStatusQuery
is True, a server status query is skipped.

Remarks
This property corresponds to the GatewayHandler mode flag
DSAXES_MODE_NOSERVERSTATUSQUERY

DocuShare Windows Client SDK 3–127

Objects DSGateway Library

PromptOnDownloadNameClash

VB PromptOnDownloadNameClash as boolean

C++ BOOL GetPromptOnDownloadNameClash();

void SetPromptOnDownloadNameClash( BOOL );

Access Read/Write

PromptOnDownloadNameClash determines if the gateway should perform a name clash test when
downloading a file from a DocuShare server to the client machine. If the DocuShare file to be downloaded
has the same filename as in the destination folder on the client machine, PromptOnDownloadNameClash
causes the gateway to run a dialog and allow the user to overwrite the local file or cancel the download.

Remarks
The GatewayHandler.InitiateBulkDownload method uses this property.

This property corresponds to the GatewayHandler mode flag

DSAXES_MODE_DNLDNAMECLASHPROMPT.

PromptOnUploadNameClash

VB PromptOnUploadNameClash as boolean

C++ BOOL GetPromptOnUploadNameClash();

void SetPromptOnUploadNameClash( BOOL );

Access Read/Write

PromptOnUploadNameClash determines if the gateway should perform a name clash test when uploading
a file to a DocuShare server. If the local file to be uploaded has the same filename as in the destination
collection on a DocuShare server, PromptOnUploadNameClash causes the gateway to run a dialog and
allow the user to overwrite the remote file or cancel the upload.

Remarks
The GatewayHandler.InitiateBulkUpload method uses this property.

This property corresponds to the GatewayHandler mode flag

DSAXES_MODE_UPLDNAMECLASHPROMPT.

3–128 DocuShare Windows Client SDK

DSGateway Library Objects

PropertyAttributeIDs

VB PropertyAttributeIDs as long

C++ long GetPropertyAttributeIDs();

void SetPropertyAttributeIDs( long );

Access Read/Write

PropertyAttributeIDs contains DSAXES_PROPATTR attribute identifiers that determine the ancestoral and
descendent query depths for a collection query.

Remarks
PropertyAttributeIDs is initialized to the combined value of DSAXES_PROPATTRID_PROPVALUES and
DSAXES_PROPATTR_QUERYDEPTH_CHILDREN.

It is possible to replace the DSAXES_PROPATTR_QUERYDEPTH_CHILDREN flag with one of these.

Flag Description

DSAXES_PROPATTR_QUERYDEPTH_SELF Limit to target collection.

DSAXES_PROPATTR_QUERYDEPTH_CHILDREN Include children collections.

DSAXES_PROPATTR_QUERYDEPTH_INFINITE Include all descendent collections.

DSAXES_PROPATTR_QUERYELEV_PARENT Include parent collection.

DSAXES_PROPATTR_QUERYELEV_INFINITE Include all ancester collections.

DocuShare Windows Client SDK 3–129

Objects DSGateway Library

QueriedProperties

VB QueriedProperties as Object PropertyIDs

C++ IDispatch* GetQueriedProperties();

Access Read only

QueriedProperties contains an enumerator for property identifiers that determine server-side properties
that are retrieved for a call to OpenCollection, InitiateCollectionOpen, Search, or Submit.
QueriedProperties supports enumeration of custom DocuShare properties.

Remarks
To retrieve a custom DocuShare property, an application can use QueriedProperties to add a custom
property to the collection of retrieved properties before calling OpenCollection to obtain an item list for a
collection or calling Search to find an item. The GatewaySettings.QueriedPropertyIDs property cannot be
used to specify a custom DocuShare property.

The script below uses QueriedProperties to retrieve custom property my_custom_prop as well as regular
properties—for example, title and summary in Collection-10. The script prints the retrieved custom
property of each item in a message box.

set gateway = server.OpenGateway

set propIds = gateway.GatewaySettings.QueriedProperties
set propId = propIds.Add(DSAXES_PROPID_CORE_CUSTOM)
propId.Text = "my_custom_prop"
if 0 = gateway.OpenCollection(10) then
set contData = gateway.ServerResponse.ContentData
if 0 = contData.ParseDirectory then
set enumObj = contData.ItemDescriptorArray.Enumerator
enumObj.Reset
while enumObj.NextPos <> 0
set itemObj = enumObj.NextItem
MsgBox itemObj.Prop("my_custom_prop"), , itemObj.Title
wend
end if
end if

3–130 DocuShare Windows Client SDK

DSGateway Library Objects

QueriedPropertyIDs

VB QueriedPropertyIDs(ItemType as Variant) as long

C++ long GetQueriedPropertyIDs( VARIANT* ItemType );

void SetQueriedPropertyIDs( VARIANT* ItemType, long );

Access Read/Write

QueriedPropertyIDs contains DSAXES_PROPID property identifiers that determine which server-side

properties are retrieved for a call to OpenCollection, InitiateCollectionOpen, Search, or Submit.

Parameters
ItemType contains the base type identifier of a DocuShare item. Valid base type identifiers are listed in the
table.

Properties Type Identifier Default Property

Bulletin DSXITEMTYPE_BULLETIN 0

BulletinBoard DSXITEMTYPE_BBOARD DSAXES_PROPID_BBRD_DEFAULT_QUERY

Calendar DSXITEMTYPE_CALENDAR DSAXES_PROPID_CLND_DEFAULT_QUERY

Collection DSXITEMTYPE_COLLECTION DSAXES_PROPID_COLL_DEFAULT_QUERY

Core 0 DSAXES_PROPID_CORE_DEFAULT_QUERY

Event DSXITEMTYPE_EVENT 0

File DSXITEMTYPE_DOCUMENT DSAXES_PROPID_FILE_DEFAULT_QUERY or

DSXITEMTYPE_VERSION

Group DSXITEMTYPE_GROUP 0

SavedQuery DSXITEMTYPE_SAVEDQUERY DSAXES_PROPID_QRY_DEFAULT_QUERY

URL DSXITEMTYPE_URL DSAXES_PROPID_URL_DEFAULT_QUERY

User DSXITEMTYPE_USER 0

Remarks
If an application uses a custom DocuShare property, use GatewayHandler.QueriedProperties to obtain a
PropertyIDs object and add a PropertyID of ID DSAXES_PROPID_CUSTOM with its Text property set to
the name of the custom property.

DocuShare Windows Client SDK 3–131

Objects DSGateway Library

ReceptionTimeOut

VB ReceptionTimeOut as long

C++ long GetReceptionTimeOut();

void SetReceptionTimeOut( long );

Access Read/Write

ReceptionTimeOut contains a timeout setting for data reception from a closing socket. If data packets
remain even after the web server signals a closure and some of the packets do not arrive within the
amount of time in ReceptionTimeOut, the gateway aborts the data reception and raises a socket error
WSAETIMEDOUT.

Remarks
The default value is 60,000 milliseconds (1 minute). The default value can be modified by specifying a
different value for the registry entry "ReceiveTimeOut",

[HKCU\Software\Xerox\DocuShare Client\DsAxess\Settings]

ReceiveTimeOut=dword:

RenameFirstReplicate

VB RenameFirstReplicate as boolean

C++ BOOL GetRenameFirstReplicate();

void SetRenameFirstReplicate( BOOL );

Access Read/Write

RenameFirstReplicate determines if the first file to be replicated should be renamed. If

RenameFirstReplicate is True, the first top-level file or folder is renamed with a prefix Copy of and the
original name.

Remarks
The property applies to a bulk replication started by a call to GatewayHandler.InitiateBulkReplicate.

This property corresponds to the GatewayHandler mode flag

DSAXES_MODE_RENAME1STREPLICATE.

3–132 DocuShare Windows Client SDK

DSGateway Library Objects

Silent

VB Silent as boolean

C++ BOOL GetSilent();

void SetSilent( BOOL );

Access Read/Write

Silent determines if the client gateway should not run a status dialog while connecting to a DocuShare
server. The default value of Silent is False.

Remarks
This property corresponds to the GatewayHandler mode flag DSAXES_MODE_SILENT.

StatusObject

VB StatusObject as Object StatusObj

C++ IDispatch* GetStatusObject();

void SetStatusObject( IDispatch* );

Access Read/Write

StatusObject contains a status UI object of interface IStatusObj. StatusObject controls display of a

DocuShare call status.

StorageMedium

VB StorageMedium as DSX_STGMEDIUM

C++ DSX_STGMEDIUM GetStorageMedium();

void SetStorageMedium( DSX_STGMEDIUM );

Access Read/Write

StorageMedium determines the type of a storage medium that the gateway uses to store a response from
a DocuShare server.

DocuShare Windows Client SDK 3–133

Objects DSGateway Library

TransmissionBufferSize

VB TransmissionBufferSize as long

C++ long GetTransmissionBufferSize();

void SetTransmissionBufferSize( long );

Access Read/Write

TransmissionBufferSize specifies the byte size of the send buffer.

Remarks
The default buffer size is 4096 bytes. The default setting can be modified by specifying a different value for
the registry entry SocketTxBuffer, [HKCU\Software\Xerox\DocuShare Client\DsAxess\Settings].

SocketTxBuffer=dword:

TransmissionPause

VB Property TransmissionPause as long

C++

Access Read/Write

TransmissionPause contains a time setting in milliseconds for pausing data transmission.

Remarks
In the event a message transmission blocks a connected socket due to slow throughput, the gateway can
suspend the transmission by the amount specified in TransmissionPause. If the blocking persists for more
than the amount specified in TransmissionTimeout, the gateway aborts the transmission and raises a
socket error WSAECONNABORTED. See TransmissionTimeOut on page 3–135.

The default value is 0. The default value may be modified by specifying a different value for the registry
entry SocketSendPause, [HKCU\Software\Xerox\DocuShare Client\DsAxess\Settings]

SocketSendPause=dword:

3–134 DocuShare Windows Client SDK

DSGateway Library Objects

TransmissionTimeOut

VB Property TransmissionTimeOut as long

C++

Access

TransmissionTimeOut specifies a timeout setting for a socket transmission retry.

Remarks
The default timeout setting is 10 seconds. The default setting can be modified by specifying a different
value in milliseconds for the registry entry SocketSendTimeOut , [HKCU\Software\Xerox\DocuShare
Client\DsAxess\Settings]

SocketSendTimeOut=dword:

UploadAlwaysAsNewDoc

VB UploadAlwaysAsNewDoc as boolean

C++ BOOL GetUploadAlwaysAsNewDoc();

void SetUploadAlwaysAsNewDoc( BOOL );

Access Read/Write

UploadAlwaysAsNewDoc determines if the gateway should upload a file as a new document to DocuShare
regardless of an existing file with the same name in the destination DocuShare collection.

Remarks
UploadAlwaysAsNewDoc has precedence over PromptOnUploadNameClash if both are set to True.

This property corresponds to the GatewayHandler mode flag

DSAXES_MODE_UPLDALWAYSASNEWDOC.

DocuShare Windows Client SDK 3–135

Objects DSGateway Library

3.2.4 DSAccessData
List of DSAccessData methods and properties

DSAccessData Methods and Properties

AuthToken Password

BrokerMap Port

CapabilityFlags Protocol

DocuShareAddress ProxyAddress

Domain ServerMap

DSVersionNumber SupportDS1x

GatewaySettings UseProxy

HostName UserHandle

IPAddress UserName

IsUserLoggedIn VirtualRoot

3.2.4.1 DSAccessData methods

There are no methods defined for this object.

3.2.4.2 DSAccessData properties

This section contains DSAccessData property definitions.

AuthToken

VB AuthToken as string

C++ CString GetAuthToken();

void SetAuthToken( LPCTSTR );

Access Read/Write

AuthToken contains a DocuShare user authentication token.

3–136 DocuShare Windows Client SDK

DSGateway Library Objects

BrokerMap

VB BrokerMap as Variant

C++ VARIANT* GetBrokerMap();

void SetBrokerMap( VARIANT );

Access Read/Write

BrokerMap contains a server map for a peer workstation associated with the DSAccessData instance.

CapabilityFlags

VB CapabilityFlags as long

C++ long GetCapabilityFlags();

void SetCapabilityFlags( long );

Access Read/Write

CapabilityFlags contain DSCAPFLAG flags that determine the DocuShare HTTP/XML Interface capability
of a DocuShare server.

Flag or Mask Value Capability

DSCAPFLAG_NEWVERCOMMENT 0x00000001 Supports version comment

DSCAPFLAG_DIRUPLOAD 0x00000002 Supports folder upload

DSCAPFLAG_AUTHCONVERSION 0x00000004 Supports authtoken conversion

DSCAPFLAG_SECUREHTTP 0x00000008 Uses secure transport

DSCAPFLAG_ISLORAX 0x00000010 Supports DS 2.2 features

DSCAPFLAG_READONLY 0x00000020 In Read-only maintenance mode

DSCAPFLAG_WWWAUTH 0x00000040 Uses a WWW-Authenticate method

DSCAPFLAG_ACCEPTCOMPRESSION 0x00000080 Supports gzip compression

DSCAPFLAG_WWWAUTHMETHOD 0x00000F00 Auth method ordinal

DSCAPFLAG_PROXYAUTH 0x00001000 Proxy uses authentication

DSCAPFLAG_PROXYAUTHMETHOD 0x0001E000 Proxy's auth method ordinal

DSCAPFLAG_ISGRIFFIN 0x00020000 Supports DS 3.0 features

Remarks
CapabilityFlags is set upon successful completion of a DocuShare call, such as DoLoginDialog and
OpenCollection.

DocuShare Windows Client SDK 3–137

Objects DSGateway Library

DocuShareAddress

VB DocuShareAddress as string

C++ CString GetDocuShareAddress();

void SetDocuShareAddress( LPCTSTR );

Access Read/Write

DocuShareAddress contains the http or https address for a DocuShare server.

Domain

VB Domain as string

C++ CString GetDomain();

void SetDomain( LPCTSTR );

Access Read/Write

Domain contains the domain of a DocuShare server in which a user login has been performed.

DSVersionNumber

VB DSVersionNumber as long

C++ long GetDSVersionNumber();

void SetDSVersionNumber( long );

Access Read/Write

DSVersionNumber contains the version number for a DocuShare server.

Remarks
The high word indicates the major version number. The low word indicates the minor version number.

GatewaySettings

VB GatewaySettings as Object GatewaySettings

C++ IDispatch* GetGatewaySettings();

Access Read only

GatewaySettings contains a reference to the GatewaySettings object associated with the DSAccessData
instance.

3–138 DocuShare Windows Client SDK

DSGateway Library Objects

HostName

VB HostName as string

C++ CString GetHostName();

void SetHostName( LPCTSTR );

Access Read/Write

HostName contains the hostname for a DocuShare server.

IPAddress

VB IPAddress as string

C++ CString GetIPAddress();

void SetIPAddress( LPCTSTR );

Access Read/Write

IPAddress contains the IP address for a DocuShare server.

IsUserLoggedIn

VB IsUserLoggedIn as boolean

C++ BOOL GetIsUserLoggedIn();

Access Read only

IsUserLoggedIn determines if a user has successfully logged in.

Remarks
The determination is made by testing the following items:

• A valid User handle exists in UserHandle.

• A valid AmberUser auth token exists in AuthToken.

DocuShare Windows Client SDK 3–139

Objects DSGateway Library

Password

VB Password as string

C++ CString GetPassword();

void SetPassword( LPCTSTR );

Access Read/Write

Password contains the password for a DocuShare user.

Port

VB Port as long

C++ long GetPort();

void SetPort( long );

Access Read/Write

Port contains the TCP/IP port number of a DocuShare server.

Protocol

VB Property Protocol as string

C++

Access Read/Write

Protocol contains a protocol scheme identifier used to establish a connection with a DocuShare server.

Remarks
The gateway supports the http and https protocol schemes.

ProxyAddress

VB Property ProxyAddress as string

C++

Access Read/Write

ProxyAddress contains the http or https address for a proxy server.

3–140 DocuShare Windows Client SDK

DSGateway Library Objects

ServerMap

VB ServerMap as Variant

C++ VARIANT* GetServerMap();

void SetServerMap( VARIANT );

Access Read/Write

ServerMap contains a server map for a DocuShare server associated with the DSAccessData instance.

Remarks
ServerMap normally returns a Server object. It is possible to directly obtain an integer server map instance
ID from ServerMap. To do so in C++, set the vt member of the VARIANT variable that stores the return
value to VT_I4 as in:

VARIANT var;
var.vt = VT_I4;
var.lVal = 0;
pDSAccessData->get_ServerMap(&var);
The lVal member variable contains the instance ID number of the server map. This works only if the
gateway instance is in the process space of the calling application.

SupportDS1x

VB SupportDS1x as boolean

C++ BOOL GetSupportDS1x();

void SetSupportDS1x( BOOL );

Access Read/Write

SupportDS1x determines if the gateway should enable support for the non-XML DocuShare 1.5 protocol.

Remarks
The default value is False. The property's value should not be modified since the client gateway no longer
supports the obsolete DS 1.5 protocol.

DocuShare Windows Client SDK 3–141

Objects DSGateway Library

UseProxy

VB UseProxy as boolean

C++ BOOL GetUseProxy();

void SetUseProxy( BOOL );

Access Read/Write

UseProxy determines if a proxy server is in use.

UserHandle

VB UserHandle as Variant

C++ VARIANT* GetUserHandle();

void SetUserHandle( VARIANT );

Access Read/Write

UserHandle contains the DocuShare handle for a DocuShare User.

Remarks
UserHandle returns a string containing a User handle, for example, User-123. It is possible to directly
obtain an integer handle number, such as 123, from UserHandle. To do so in C++, set the vt member of the
VARIANT variable that stores the return value to VT_I4 as in:

VARIANT var;
var.vt = VT_I4;
var.lVal = 0;
pDSAccessData->get_UserHandle(&var);
The lVal member variable contains the User handle number. This works only if the gateway instance is in
the process space of the calling application.

3–142 DocuShare Windows Client SDK

DSGateway Library Objects

UserName

VB UserName as string

C++ CString GetUserName();

void SetUserName( LPCTSTR );

Access Read/Write

UserName contains the username of a DocuShare user.

Remarks
UserName is set after a call to one of the following GatewayHandler methods successfully completes.

GatewayHandler Method Description

DoLoginDialog UserName and Password are set based on values

entered by an end user in a dialog.

InitiateUserAuth UserName and Password are set based on

parameters passed from a calling application.

VirtualRoot

VB VirtualRoot as string

C++ CString GetVirtualRoot();

void SetVirtualRoot( LPCTSTR );

Access Read/Write

VirtualRoot contains a DocuShare root specifier.

DocuShare Windows Client SDK 3–143

Objects DSGateway Library

3.2.5 ClientRequest
List of ClientRequest methods and properties.

ClientRequest Methods and Properties

Action Header

ActionId HTTPVersionMajor

Broker HTTPVersionMinor

Clear MessageHeader

ContentData Method

ContentType Parameters

Cookie RequestURI

DispatchedTime URL

3.2.5.1 ClientRequest methods

This section contains ClientRequest method definitions.

Clear

VB Clear()

C++ void Clear();

The method clears the MessageHeader and ContentData.

3.2.5.2 ClientRequest properties

This section contains ClientRequest property definitions.

Action

VB Action as String

C++ CString GetAction();

Access Read only

Action contains a display string describing an action that the gateway is taking or has taken regarding
execution of a DocuShare command or an HTTP method.

3–144 DocuShare Windows Client SDK

DSGateway Library Objects

ActionId

VB ActionId as DSX_CMDID

C++ DSX_CMDID GetActionId();

Access Read only

ActionId contains an ordinal number that identifies a DocuShare command or a generic HTTP method that
is being or has been processed.

ActionId contains one of the following CMDID ordinals:

CMDID_AUTHUPLOAD CMDID_HTTP_OPTION

CMDID_CHECKOUT CMDID_HTTP_POST

CMDID_COPY CMDID_HTTP_PROPFIND

CMDID_CUSTOM CMDID_HTTP_PROPPATCH

CMDID_DELETE CMDID_HTTP_PUT

CMDID_DIR CMDID_HTTP_UNLINK

CMDID_DOWNLOAD CMDID_LOCK

CMDID_GETPROPS CMDID_LOGIN (=1)

CMDID_HISTORY CMDID_MKDIR

CMDID_HTTP_DELETE CMDID_MOVE

CMDID_HTTP_GET CMDID_SEARCH

CMDID_HTTP_HEAD CMDID_SETPROPS

CMDID_HTTP_LINK CMDID_UNKNOWN (=0)

CMDID_HTTP_MKCOL CMDID_UNLOCK

CMDID_HTTP_MKRES CMDID_UPLOAD

Remarks
After a connection to a server is established, ActionId, Action, and Parameters are set immediately before
the gateway actuates a GatewayHandlerEvents.ConnectComplete event.

Broker

VB Broker as Variant

C++

Access Read/Write [hidden]

Contains a Server object which provides peer borker services.

DocuShare Windows Client SDK 3–145

Objects DSGateway Library

ContentData

VB ContentData as Object ContentData

C++ IDispatch* GetContentData();

Access Read only

A ContentData object that abstracts storage, access, and parsing of content data in an HTTP message.

Remarks
ClientRequest and ServerResponse both use ContentData to access the content data of both a client
request message and a server response message. A sample script is shown below.

set gateway = server.OpenGateway

set req = CreateObject( "DSGateway.ClientRequest" )
req.Method = "POST"
req.RequestURI = "dscgi/ds.py/PROPFIND/Collection-10"
req.Header("Depth") = "1"
req.ContentType = "text/xml"
req.ContentData.Text = _
"<?xml version="+chr(&H22)+"1.0"+chr(&H22)+" ?>" &_
"<propfind>" & _
"<prop>" & _
"<displayname/>" & _
"<summary/>" & _
"</prop>" & _
"</propfind>"
if 0 = gateway.Submit( req ) then
MsgBox gateway.ServerResponse.ContentData.Text
end if

3–146 DocuShare Windows Client SDK

DSGateway Library Objects

ContentType

VB ContentType as String

C++ void SetContentType( LPCTSTR );

Access Read/Write

ContentType contains a content type specifier for the content data in a client request message.

Remarks
If it modifies ContentData directly, an application should update ContentType to the data type for the data
assigned to ContentData. For example, if a text string containing an XML source is assigned to
ContentData.Text, ContentType should be set to text/xml. See the example in the Remarks section of
ContentData on page 3–146.

Cookie

VB Cookie as String

C++ CString GetCookie();

void SetCookie( LPCTSTR );

Access Read/Write

Cookie contains an HTTP cookie string that is needed by a web server or DocuShare server to process a
client request.

Remarks
A request to a DocuShare server is accompanied by an AmberUser cookie setting which contains access
authorization data for a DocuShare user.

The gateway object obtains access authentication data from a Server object through which the gateway
was opened. There is no need for an application to explicitly set Cookie.

DocuShare Windows Client SDK 3–147

Objects DSGateway Library

DispatchedTime

VB Property DispatchedTime as Date

C++

Access Read only

DispatchedTime contains a time stamp that indicates when the transmission of a client request message to
a server completed.

Remarks
After a request message is dispatched, this property is updated immediately before the gateway actuates
the last GatewayHandlerEvents.Send event.

Header

VB Property Header (Name as String) as Variant

C++

Access Read/Write

Header contains a message header field of a client HTTP request message.

Remarks
An application can use this property to define and assign values to special header fields that are not
directly available as properties of ClientRequest.

set gateway = server.OpenGateway

set req = CreateObject( "DSGateway.ClientRequest" )
req.Method = "GET"
req.RequestURI = "/test/second.htm"
req.Header("MyFavoriteSite") = "http://www.xerox.com/"
status = gateway.Submit( req )

3–148 DocuShare Windows Client SDK

DSGateway Library Objects

HTTPVersionMajor

VB HTTPVersionMajor as long

C++ long GetHTTPVersionMajor();

void SetHTTPVersionMajor( long );

Access Read/Write

HTTPVersionMajor contains a major version number of the HTTP protocol that the gateway supports.

Remarks
The HTTP protocol version of the gateway is 1.1. The major version is fixed at 1 while the minor version at
1. An application should not modify the property's default value.

HTTPVersionMinor

VB HTTPVersionMinor as long

C++ long GetHTTPVersionMinor();

void SetHTTPVersionMinor( long );

Access Read/Write

HTTPVersionMinor contains a minor version number of the HTTP protocol that the gateway supports.

DocuShare Windows Client SDK 3–149

Objects DSGateway Library

MessageHeader

VB MessageHeader as String

C++ CString GetMessageHeader();

void SetMessageHeader( LPCTSTR );

Access Read/Write

MessageHeader contains a message header of a client HTTP request message.

Remarks
An application can use this property to set an entire message header in one assignment call when using
GatewayHandler.Submit to submit a request to a web server.

set gateway = server.OpenGateway

set req = CreateObject( "DSGateway.ClientRequest" )
req.Method = "GET"
req.RequestURI = "/test/first.htm"
req.MessageHeader = _
"Accept: text/html"+vbCr+_
"Cookie: ..."
status = gateway.Submit( req )

3–150 DocuShare Windows Client SDK

DSGateway Library Objects

Method

VB Method as String

C++ CString GetMethod();

void SetMethod( LPCTSTR );

Access Read/Write

Method contains an HTTP method identifier for a DocuShare command or a generic HTTP resource
access.

Remarks
Valid HTTP methods include the following:

• DELETE
• GET
• HEAD
• LINK
• MKCOL
• MKRES
• OPTION
• POST
• PROPFIND
• PROPPATCH
• PUT
• UNLINK

DocuShare Windows Client SDK 3–151

Objects DSGateway Library

Parameters

VB Parameters as String

C++ CString GetParameters();

Access Read only

Parameters contains a display string consisting of parameters used to initiate a DocuShare command or
an HTTP method.

RequestURI

VB RequestURI as String

C++ CString GetRequestURI();

void SetRequestURI( LPCTSTR );

Access Read/Write

RequestURI contains an HTTP request URI for a DocuShare command or a generic HTTP resource
access.

Remarks
When submitting a generic HTTP message, an application can use the GatewayHandler.Submit method.
The application then uses the Method and RequestURI properties of ClientRequest to specify how and
what web resource to access.

set gateway = server.OpenGateway

set req = CreateObject( "DSGateway.ClientRequest" )
req.Method = "GET"
req.RequestURI = "/default.htm"
status = gateway.Submit( req )

3–152 DocuShare Windows Client SDK

DSGateway Library Objects

URL

VB URL as String

C++ CString GetURL();

Access Read only

URL contains a URL for a DocuShare command or a generic HTTP resource access that is being or has
been processed.

Remarks
If URL contains a DocuShare URL, it is segregated into five components:

• protocol scheme specifier

• web server hostname
• web server port
• DocuShare root specifier
• DocuShare resource identifier
If the URL property contains the URL http://www.xyz.com:8080/docushare/dscgi/ds.py/PROPFIND/
Collection-10, the segregation yields the following:

• DSAccessData.Protocol: "http://"
• DSAccessData.HostName: "www.xyz.com"
• DSAccessData.Port: 8080
• DSAccessData.DocuShareAddress: "http://www.xyz.com:8080/docushare/"
• DSAccessData.VirtualRoot: "/docushare/"
• ClientRequest.URI: "dscgi/ds.py/PROPFIND/Collection-10"
If an application uses the GatewayHandler.Submit method to generate a generic HTTP request, the URL
property is not used and remains empty. The application sets the Method and RequestURI properties to
define a request.

Other GatewayHandler methods, such as Upload, internally creates a ClientRequest object and
programmatically generates a DocuShare URL depending on the values of Server.DocuShareAddress,
GatewaySettings.AddDSCGI, the DocuShare HTTP/XML command verb mapped to the invoked
GatewayHandler method, and parameters passed to the method. GatewayHandler, then, automatically
assigns the generated URL to the ClientRequest.URL property.

To read the values of properties for the CientRequest instance created by GatewayHandler, an application
can subscribe to the GatewayHandlerEvents notification service and read the values of the properties it is
interested in when it receives control upon activating a Connect or ConnectComplete event.

The following C++ sample code opens a gateway from a Server object, subscribes to
GatewayHandlerEvents, handles the Connect event, and prints out the values of the URL, Method and
RequestURI properties of a ClientRequest internally generated by GatewayHandler.OpenCollection. The
event handler class GatewayEvents derives from MFC class CCmdTarget.

DocuShare Windows Client SDK 3–153

Objects DSGateway Library

class GatewayEvents : public CCmdTarget {

DECLARE_DYNCREATE(GatewayEvents)
GatewayEvents() {
m_cookie = 0;
EnableAutomation();
AfxOleLockApp();
}
~GatewayEvents() {
Unsubscribe();
AfxOleUnlockApp();
}

public:
BOOL Subscribe( IDispatch* pdispGateway ) {
m_gateway.AttachDispatch( pdispGateway );
return AfxConnectionAdvise( m_gateway.m_lpDispatch,
DIID_DDsAxessEvents, GetIDispatch(FALSE), TRUE, &m_cookie );
}
void Unsubscribe() {
if (!m_dwCookie) return;
AfxConnectionUnadvise( m_gateway.m_lpDispatch,
DIID_DDsAxessEvents, GetIDispatch(FALSE), TRUE, m_cookie );
m_cookie = 0;
}
// GatewayHandlerEvents event handling methods
void OnConnect( long dataType ) {
IClientRequest req( m_gateway.GetClientRequest() );
CString url = req.GetUrl();
CString method = req.GetMethod();
CString uri = req.GetRequestURI();
CString header = req.GetMessageHeader();
printf( "URL: %s\n", url );
printf( "Method: %s\n", method );
printf( "URI: %s\n", uri );
printf( "Header: %s\n", header );
}
...

protected:

3–154 DocuShare Windows Client SDK

DSGateway Library Objects

IDsAxes m_gateway;
DWORD m_cookie;
};

IMPLEMENT_DYNCREATE(GatewayEvents, CCmdTarget)

BEGIN_DISPATCH_MAP(GatewayEvents, CCmdTarget)
//{{AFX_DISPATCH_MAP(GatewayEvents)
DISP_FUNCTION(GatewayEvents, "OnConnect", OnConnect, VT_EMPTY,
VTS_I4)
DISP_FUNCTION(GatewayEvents, "OnConnectComplete", OnConnectComplete,
VT_EMPTY, VTS_PBOOL)
DISP_FUNCTION(GatewayEvents, "OnSend", OnSend, VT_EMPTY, VTS_I4
VTS_I4 VTS_PBOOL)
DISP_FUNCTION(GatewayEvents, "OnReceive", OnReceive, VT_EMPTY, VTS_I4
VTS_I4 VTS_PBOOL)
DISP_FUNCTION(GatewayEvents, "OnClose", OnClose, VT_EMPTY, VTS_I4
VTS_I4)
//}}AFX_DISPATCH_MAP
END_DISPATCH_MAP()

BEGIN_INTERFACE_MAP(GatewayEvents, CCmdTarget)
INTERFACE_PART(GatewayEvents, DIID_DDsAxessEvents, Dispatch)
END_INTERFACE_MAP()

void main {
...
IServer server;
server.CreateDispatch( "DSServerMap.Server" );
...
IDsAxes gateway( server.OpenGateway() );
GatewayEvents* pEvents = new GatewayEvents;
pEvents->Subscribe( gateway.m_lpDispatch );
if ( 0 == gateway.OpenCollection( 10 ) ) {
...
}
delete pEvents;
...
}

DocuShare Windows Client SDK 3–155

Objects DSGateway Library

3.2.6 ServerResponse
List of ServerResponse methods and properties

Methods and Properties

Clear ErrorCode

ContentData ErrorDescription

ContentEncoding HasTextualContent

ContentLength Header

ContentType HTTPResultCode

Cookie MessageHeader

DSError ReceivedTime

DSHandle RemoteTime

DSUser StatusCode

DSVersion StatusLine

3.2.6.1 ServerResponse methods

This section contains ServerResponse method definitions.

Clear

VB Clear()

C++ void Clear();

Clears the MessageHeader and ContentData.

3–156 DocuShare Windows Client SDK

DSGateway Library Objects

3.2.6.2 ServerResponse properties

This section contains ServerResponse property definitions.

ContentData

VB ContentData as Object ContentData

C++ IDispatch* GetContentData();

Access Read only

Contains a ContentData object that encapsulates the content data of a response message.

ContentEncoding

VB ContentEncoding as string

C++ CString GetContentEncoding();

Access Read only

ContentEncoding contains the value of the header field Content-Encoding if the field appears in the
response message.

ContentLength

VB ContentLength as long

C++ long GetContentLength();

Access Read only

ContentLength contains the value of the header field Content-Length if the field appears in the response
message.

Remarks
Content-Length is the length in characters of the content data contained in a response message.

DocuShare Windows Client SDK 3–157

Objects DSGateway Library

ContentType

VB ContentType as string

C++ CString GetContentType();

Access Read only

ContentType contains a content type specifier for the content data included in a server response message.

Remarks
ContentType is empty if a response message does not contain content data.

Cookie

VB Cookie as string

C++ CString GetCookie();

Access Read only

Cookie contains the value of the header field Set-Cookie if the field appears in the response message.

DSError

VB DSError as string

C++ CString GetDSError();

Access Read only

DSError contains the value of the header field DocuShare-Error if the field appears in the response
message.

DSHandle

VB DSHandle as string

C++ CString GetDSHandle();

Access Read only

DSHandle contains the value of the header field DocuShare-Handle if the field appears in the response
message.

Remarks
DocuShare-Handle specifies the DocuShare handle of a DocuShare object executed by the client
application command. If the command was ApplyUpload (invoked by the GatewayHandler.Upload
method), DocuShare-Handle contains the DocuShare handle of a file uploaded to the server, such as File-
123.

3–158 DocuShare Windows Client SDK

DSGateway Library Objects

DSUser

VB DSUser as string

C++ CString GetDSUser();

Access Read only

DSUser contains the value of the header field DocuShare-User if the field appears in the response
message.

DSVersion

VB DSVersion as string

C++ CString GetDSVersion();

Access Read only

DSVersion contains the value of the header field DocuShare-Version if the field appears in the response
message.

Remarks
DocuShare-Version specifies the version of the DocuShare HTTP/XML protocol the DocuShare server
supports if it appears in a response message. If it appears in a request message, DocuShare-Version
specifies the protocol version that the user agent (client application) supports.

ErrorCode

VB ErrorCode as long

C++ long GetErrorCode();

void SetErrorCode( long );

Access Read/Write

ErrorCode contains an error code for the reported error.

DocuShare Windows Client SDK 3–159

Objects DSGateway Library

ErrorDescription

VB ErrorDescription as string

C++ CString GetErrorDescription();

void SetErrorDescription( LPCTSTR );

Access Read/Write

ErrorDescription contains a description of the error the gateway or DocuShare encountered while sending,
receiving, or post-processing a client request.

Remarks
After a response message is received, this property is updated immediately before the gateway actuates
the first GatewayHandlerEvents.Close event.

HasTextualContent

VB HasTextualContent as boolean

C++ BOOL GetHasTextualContent();

Access Read only

HasTextualContent determines if the content data is textual.

Remarks
Determination is based on the Content-Type header field in the response header. HasTextualContent is
True if the Content-Type is a MIME type of text/*—for example, html, xml, or plain, or the MIME type of
application/x-www-form-urlencoded.

Header

VB Header (Name as Variant) as Variant

C++ VARIANT* GetHeader( VARIANT Name );

Access Read only

Header contains the value of a specified header field if the field appears in the response message.

Parameters
Name—a header field name.

3–160 DocuShare Windows Client SDK

DSGateway Library Objects

HTTPResultCode

VB HTTPResultCode as long

C++ long GetHTTPResultCode();

void SetHTTPResultCode( long );

Access Read/Write

HTTPResultCode contains the HTTP result code of a server response message.

Remarks
The value is the 3-digit code indicated on the status line of an HTTP response message. A status line
consists of a protocol version, a result code, and a reason phrase. An example of status line follows.

HTTP/1.1 200 Success

Refer to RFC 2616, Hypertext Transfer Protocol -- HTTP/1.1, for definition of a result code.

MessageHeader

VB MessageHeader as string

C++ CString GetMessageHeader();

Access Read only

MessageHeader contains a message header of an HTTP response message from a DocuShare server.

Remarks
An application uses this property to retrieve an entire message header.

DocuShare Windows Client SDK 3–161

Objects DSGateway Library

ReceivedTime

VB ReceivedTime as date

C++ DATE GetReceivedTime();

Access Read only

ReceivedTime contains a time stamp which indicates the time the last response message was received
from a server.

Remarks
After a response message is received, this property is updated immediately before the gateway actuates
the first GatewayHandlerEvents.Receive event.

RemoteTime

VB RemoteTime as date

C++ DATE GetRemoteTime();

Access Read only

RemoteTime Contains a time stamp that indicates the time DocuShare processed the last client request.

Remarks
The time value is retrieved from a Date header field in a response message from a DocuShare or web
server. If a Date field is not available, the system time is used as the value of RemoteTime for the time the
response was received.

3–162 DocuShare Windows Client SDK

DSGateway Library Objects

StatusCode

VB StatusCode as long

C++ long GetStatusCode();

void SetStatusCode( long );

Access Read/Write

StatusCode contains a DSAXES status code that specifies a class of errors; for example, the processing of
a client request is successful, on-going, canceled, or failed because the server raised an HTTP error.

Status Code Description

DSAXES_E_APPSELECT Application selected

DSAXES_E_BADDIR Bad directory

DSAXES_E_BADDSCMD Bad DocuShare command

DSAXES_E_BADLINK OLE interface error

DSAXES_E_BADPARAM Bad parameter

DSAXES_E_BADSCRCMD Bad Scripting command

DSAXES_E_BADSEL Bad selection

DSAXES_E_BUSY Busy

DSAXES_E_CANCEL Operation canceled

DSAXES_E_CREATEFILE File creation error

DSAXES_E_FAIL General failure

DSAXES_E_HTTP HTTP error

DSAXES_E_LOCALLOCK Local lock

DSAXES_E_LOGIN Login failed

DSAXES_E_LOGIN_REFUSED Login refused

DSAXES_E_MAXELEMENTS Maximum elements exceeded

DSAXES_E_MODNOTFOUND Module not found

DSAXES_E_NOTIMPL Function not implemented

DSAXES_E_OPENFILE File open error

DSAXES_E_PARSEDATA Data parsing error

DSAXES_E_PROPSNOTFOUND Properties not found

DSAXES_E_SERVDOWN Server down

DSAXES_E_SERVLOCKED Server locked

DocuShare Windows Client SDK 3–163

Objects DSGateway Library

Status Code Description

DSAXES_E_SERVREADONLY Server read-only

DSAXES_E_SKIP Operation skipped

DSAXES_E_SYSRES System resource error

DSAXES_E_UNKNOWN Unknown error

DSAXES_E_UPDATELINKS Link update error

DSAXES_E_WINSOCK Windows socket error

DSAXES_INPROG Operation in progress

DSAXES_NOCHANGE No changes detected

DSAXES_NOCONNATTEMPT No connections attempted

DSAXES_SUCCESS Operation succeeded

Remarks
StatusCode specifies the type error for the reported error. ErrorCode contains the error code that specifies
the error type.

For example, if the gateway fails to contact a server because the Windows Socket library could not resolve
or locate the server's host machine on the network, the gateway sets StatusCode to
DSAXES_E_WINSOCK and ErrorCode to WSAEHOSTUNREACH.

If the server aborts the processing of a client request due to an internal error, StatusCode is set to
DSAXES_E_HTTP and ErrorCode to the HTTP result code of 501.

StatusLine

VB StatusLine as string

C++ CString GetStatusLine();

Access Read only

StatusLine contains the status line of a response message.

Remarks
A status line is the first line of an HTTP response message. It consists of an HTTP protocol version, a
result code, and a result phrase.

3–164 DocuShare Windows Client SDK

DSGateway Library Objects

3.2.7 ContentData
List of ContentData methods and properties

ContentData Methods and Properties

Add ParseSchema

CleanText ParsedResultHandle

DeclareXML ParsedResultType

DataCompression ParseSchema

Delta ParseVersionHistory

File ParseUploadResult

ItemDescriptorArray StorageMedium

ItemProperties Stream

ParseDirectory Text

ParseProperties Verify

ParsePropertiesAsDsxInfo XMLDOM

ParseQueryResults

3.2.7.1 ContentData methods

This section contains ContentData method definitions.

Add

VB Add( Data as Variant )

C++ void Add( VARIANT Data );

Add method appends data to the content data repository of the ContentData.

Remarks
The method recognizes the following data types:

1. String
2. Stream object (with interface IStream)
3. ItemProperties object
4. PropertyIDs object
Use item 1 to add textual data. The example below uses Add to generate a request form for creating a
Collection object in Collection-10 on a DocuShare 2.x server.

set req = CreateObject("DSGateway.ClientRequest")

DocuShare Windows Client SDK 3–165

Objects DSGateway Library

req.Method = "POST"
req.RequestURI = "dscgi/ds.py/ApplyUpload/Collection-10"
req.ContentType = "application/x-www-form-urlencoded"
set cd = req.ContentData
cd.Add "parent=Collection-10"
cd.Add "&obj_type=Collection"
cd.Add "&title=New%20Collection"
cd.Add "&summary=..."
set gateway = server.Open
status = gateway.Submit(req)
Use item 2 for data of any data type provided that the application is capable of creating an IStream object.

For item 3, the ContentData enumerates the ItemProperty objects enumerated by the ItemProperties
object and generates a list of XML elements in angle brackets that is useful for a PROPFIND request. A
default XML declaration "<?xml version=1.0 ?>" is automatically inserted. If the DeclareXML method is
called prior to the Add call, a declaration specific to the input parameters of DeclareXML is inserted
instead.

set req = CreateObject("DSGateway.ClientRequest")

set cd = req.ContentData
set props = CreateObjects("DSGateway.ItemProperties")
props.Add "displayname"
props.Add "summary"
props.Add "special_prop"
cd.Add props
The above example generates the following content data:

<?xml version=1.0 ?>

<propfind>
<displayname/>
<summary/>
<special_prop/>
</propfind>
For item 4, the ContentData uses the object's PropertyIDs.List property to generate a list of XML elements
in angle brakets that is useful for a PROPFIND request. A default XML declaration "<?xml version=1.0 ?>"
is automatically inserted. If the DeclareXML method is called prior to the Add call, a declaration specific to
the input parameters of DeclareXML is inserted instead.

set req = CreateObject("DSGateway.ClientRequest")

set cd = req.ContentData
cd.DeclareXML
set propIds = CreateObjects("DSGateway.PropertyIDs")
propIds.Add(DSAXES_PROPID_CORE_TITLE)

3–166 DocuShare Windows Client SDK

DSGateway Library Objects

propIds.Add(DSAXES_PROPID_CORE_SUMMARY)
propIds.Add(DSAXES_PROPID_CORE_CUSTOM, "special_prop")
cd.Add propIds
The above example generates a body of content data similar to the earlier example of item 3.

For items 3 and 4, the content type of a client request message is "text/xml" if no content type has been
specified through ClientRequest.ContentType.

DocuShare Windows Client SDK 3–167

Objects DSGateway Library

DeclareXML

VB DeclareXML( Version as optional Variant, Encoding as optional Variant )

C++ void DeclareXML( VARIANT* Version, VARIANT* Encoding );

DeclareXML method starts content data with an XML declaration "<?XML version=%1 encoding=%2 ?>"
where %1 is the XML version, and %2 is the character encoding.

Parameters

Parameter Description

Version Optional; XML version. If the parameter is omitted,

the version defaults to 1.0.

Encoding Optional; character encoding. If the parameter is

omitted, no encoding assignment is inserted into
the XML declaration element.

Remarks
If the method is called without a version or encoding specification, the following XML declaration element
starts content data: <?XML version=1.0 ?>

Following a call to DeclareXML, an application can add a body of XML text data by assigning the text data
to the Text property.

set req = CreateObject("DSGateway.ClientRequest")

set cd = req.ConentData
cd.DeclareXML
cd.Text = "<propfind><prop><displayname></prop></propfind>"
...
status = gateway.Submit(req)
DeclareXML sets the content type of the client request message to text/xml if no content type has been
specified through ClientRequest.ContentType.

3–168 DocuShare Windows Client SDK

DSGateway Library Objects

ParseDirectory

VB method ParseDirectory ( Flags as Variant ) as long

C++

ParseDirectory parses response data from a server for item listing information. The method stores parsed
results in the ItemDescriptorArray property.

Parameters
Flags are optional; may contain integer flag PARSE_DIRECTORY_TOPLEVEL,
PARSE_DIRECTORY_DIFFDESCENDANTS, or both. It may also contain string flag TopLevel,
DiffDescendants or both.

PARSE_DIRECTORY_TOPLEVEL or TopLevel specifies that the response data regards the home site of a
DocuShare server and contains listing information for top-level collections.

PARSE_DIRECTORY_DIFFDESCENDANTS or DiffDescendants is specified if the propfind request

contains a depth value greater than 1.

The integer flags have these values:

• const PARSE_DIRECTORY_TOPLEVEL= &H0001

• const PARSE_DIRECTORY_DIFFDESCENDANTS= &H0100

Return value
If the method succeeds, the return value is DSAXES_SUCCESS (0). If the method fails, the return value is
one of the DSAXES status codes shown below.

Status Code Description

DSAXES_E_BADPARAM An invalid XML tag was found; an opening tag is
missing; an extraneous closing tag exists; opening
and closing tags are incompatible; a property
name is too long; the XML data is formatted
incorrectly.
DSAXES_E_BADSEL A parsed handle does not match an input handle.
DSAXES_E_CREATEFILE File creation or file write failed.
DSAXES_E_FAIL Unspecified error.
DSAXES_E_MODNOTFOUND No XML processor exists, or an XML processor
could not be initialized.
DSAXES_E_PARSEDATA An XML root element could not be found; an
element enumerator could not be obtained; a
token could not be found; a vital property is
missing; UTF-8 text could not be unescaped.
DSAXES_E_SYSRES Insufficient memory; an XML stream could not be
opened; an XML file could not be created or data
could not be written to it; an XML URL could not
be attached.
DSAXES_NOCHANGE No XML data exists.

DocuShare Windows Client SDK 3–169

Objects DSGateway Library

Remarks
The method is used when the DocuShare HTTP/XML API PROPFIND command is invoked against a
Collection object with a depth level of 1 or greater.

The following example uses ParseDirectory to parse a response to a PropFind and generate a
DSITEMENUMLib.EnumObj enumerator for listing the queried items.

set req = CreateObject("DSGateway.ClientRequest")

req.Method = "POST"
req.RequestURI = "dscgi/ds.py/PROPFIND/Collection-10"
req.Header("Depth") = "1"
set gateway = server.Open
status = gateway.Submit(req)
set cd = gateway.ServerResponse.ContentData
if cd.ParseDirectory = DSAXES_SUCCESS then
set enumObj = cd.ItemDescriptorArray.Enumerator
enumObj.Reset
while enumObj.NextPos <> 0
set itemObj = enumObj.NextItem
Print itemObj.Handle, itemObj.Title
wend
end if
The gateway internally calls ContentData.ParseDirectory for an operation started by
GatewayHandler.InitiateCollectionOpen or GatewayHandler.OpenCollection. Therefore, for these
methods, an application should not call ContentData.ParseDirectory.

set gateway = server.Open

status = gateway.OpenCollection(10)
set cd = gateway.ServerResponse.ContentData
set enumObj = cd.ItemDescriptorArray.Enumerator
enumObj.Reset
while enumObj.NextPos <> 0
set itemObj = enumObj.NextItem
Print itemObj.Handle, itemObj.Title
wend
The example is functionally equivalent to the earlier example.

3–170 DocuShare Windows Client SDK

DSGateway Library Objects

ParseProperties

VB method ParseProperties() as long

C++

Parses response data from a server for DocuShare properties of an object. The method can limit the
parsing to those properties enumerated by the ItemProperties property. If the ItemProperties contains no
ItemProperty objects before the method is called, all properties for which the server has sent values are
subject to parsing. The method stores the parsed result in the ItemProperties property.

Parameters
None

Return value
If the method succeeds, the return value is DSAXES_SUCCESS (0). If the method fails, the return value is
a DSAXES status code. See ParseDirectory on page 3–169 for a complete listing of the status codes.

Remarks
The method is used when the PROPFIND command of the DocuShare HTTP/XML API is invoked against
a DocuShare object with a depth level of 0.

The following example uses ParseProperties to parse a response to a PROPFIND query and generate an
ItemProperties property enumerator for retrieving the queried properties of a DocuShare object.

set req = CreateObject("DSGateway.ClientRequest")

req.Method = "POST"
req.RequestURI = "dscgi/ds.py/PROPFIND/File-123"
req.Header("Depth") = "0"
set props1 = req.ContentData.ItemProperties
props1.Add "displayname"
props1.Add "summary"
props1.Add "description"
set gateway = server.Open
status = gateway.Submit(req)
set cd = gateway.ServerResponse.ContentData
set props2 = cd.ItemProperties
props1.CopyTo props2
if cd.ParseProperties() = DSAXES_SUCCESS then
for i = 0 to props2.Count-1
set prop = props2.ItemProp(i)
Print prop.ID, prop.DisplayName, prop.Value
next
end if

DocuShare Windows Client SDK 3–171

Objects DSGateway Library

The gateway internally calls ContentData.ParseProperties for an operation started by

GatewayHandler.GetProps. Therefore, when using GetProps, an application should not call
ContentData.ParseProperties.

set gateway = server.Open

status = gateway.GetProps(...)
if status = 0 then
set cd = gateway.ServerResponse.ContentData
set props2 = cd.ItemProperties
for i = 0 to props2.Count-1
set prop = props2.ItemProp(i)
Print prop.ID, prop.DisplayName, prop.Value
next
end if
The example is functionally equivalent to the earlier example.

An application can retrieve a parsed property from the ItemProperties.ItemObject instead of the
ItemProperties.ItemProperty. A display label of a property is not directly available from the ItemObject.

if cd.ParseProperties() = DSAXES_SUCCESS then

set props = cd.ItemProperties.ItemObject.EnumProps
props.Reset
while props.NextPos <> 0
set prop = props.NextItem
Print prop.Name, prop.Label, prop.Value
wend
end if
Provided that the ClientRequest.ContentData includes the <parents> property identifier in the <prop>
properties list, the ContentData.ParsedResultType is set to the item type of the parent DocuShare object.
The ContentData.ParsedResultHandle is set to the parent object's handle number.

3–172 DocuShare Windows Client SDK

DSGateway Library Objects

ParsePropertiesAsDsxInfo

VB method ParsePropertiesAsDsxInfo() as long

C++

ParsePropertiesAsDsxInfo parses response data from a server for DocuShare properties of an object. The
method can limit the parsing to those properties enumerated by the ItemProperties property. If the
ItemProperties contains no ItemProperty objects before the method is called, all properties for which the
server has sent values are subject to parsing. The method stores the parsed result in the
ItemProperties.ItemObject property.

Parameters
None

Return value
If the method succeeds, the return value is DSAXES_SUCCESS (0). If the method fails, the return value is
a DSAXES status code. See ParseDirectory on page 3–169 for a complete listing of the status codes.

Remarks
The method is used when the PROPFIND command of the DocuShare HTTP/XML API is invoked against
a DocuShare object with a depth level of 0.

The following example uses ParsePropertiesAsDsxInfo to parse a response to a PROPFIND query and
generate a DSITEMENUMLib.ItemObj object for retrieving the queried properties of a DocuShare object.

set req = CreateObject("DSGateway.ClientRequest")

req.Method = "POST"
req.RequestURI = "dscgi/ds.py/PROPFIND/File-123"
req.Header("Depth") = "0"
req.ContentData.DeclareXML
req.ContentData.Text = "<propfind><prop>"+_
"<displayname/>"+_
"<summary/>"+_
"<description/>"+_
"</prop></propfind>"
set gateway = server.Open
status = gateway.Submit(req)
set cd = gateway.ServerResponse.ContentData
if cd.ParsePropertiesAsDsxInfo() = DSAXES_SUCCESS then
set itemObj = cd.ItemProperties.ItemObject
set props = itemObj.EnumProps
props.Reset
while props.NextPos <> 0

DocuShare Windows Client SDK 3–173

Objects DSGateway Library

set prop = props.NextItem

Print prop.Name, prop.Value
wend
end if
It is possbile to use ItemProperties.ItemObject for retrieving property values parsed by ParseProperties.
However, custom properties parsed by ParseProperties are always stored as properties with the data type
of String. Therefore, to read the value of a custom property, an application specifies
DSAXES_PROPTYPE_STRING for the type id parameter to reference.

Provided that the ClientRequest.ContentData includes the <parents> property identifier in the <prop>
properties list, the ContentData.ParsedResultType is set to the item type of the parent DocuShare object.
The ContentData.ParsedResultHandle is set to the parent object's handle number.

3–174 DocuShare Windows Client SDK

DSGateway Library Objects

ParseQueryResults

VB method ParseQueryResults

C++

Parses response data from a DocuShare server for search hits. The hits are stored in the
ItemDescriptorArray property and can be enumerated using the DSITEMENUMLib.EnumObj object
contained in the ItemDescriptorArray.Enumerator property.

Parameters
None

Return value
If the method succeeds, the return value is DSAXES_SUCCESS (0). If the method fails, the return value is
a DSAXES status code. See ParseDirectory on page 3–169 for a complete listing of the status codes.

Remarks
The method is used when the SEARCH command of the DocuShare HTTP/XML API is invoked.

The following example uses ParseQueryResults to parse a response to a SEARCH request and generate
a DSITEMENUMLib.EnumObj object for enumerating the search hits.

set req = CreateObject("DSGateway.SearchRequest")

req.MaxHits = 50
req.SearchTermsCollection.Conjunct = "and"
set SearchTypes = req.SearchTermsCollection.Add
SearchTypes.Conjunct = "and"
set SearchTerm1 = SearchTypes.Add("displayname", "contains", "Joe")
set SearchTerm2 = SearchTypes.Add("displayname", "contains", "Cool")
set gateway = server.Open
status = gateway.Submit(req)
set cd = gateway.ServerResponse.ContentData
if 0 = cd.ParseQueryResults then
set enumObj = cd.ItemDescriptorArray.Enumerator(_
DSCONTF_CHILDREN or DSCONTF_DESCENDANTS)
enumObj.Reset
while enumObj.NextPos <> 0
set itemObj = enumObj.NextItem
Print itemObj.Title, itemObj.Handle
wend
end if
ContentData.ParsedResultHandle is set to the number of search hits. ContentData.ParsedResultType is
set to zero.

DocuShare Windows Client SDK 3–175

Objects DSGateway Library

ParseSchema

VB method ParseSchema ( Params as Variant ) as long

C++

ParseSchema parses response data from a DocuShare server for the server's schemata. The parsed
schema is stored in the ItemDescriptorArray property and can be enumerated using the
DSITEMENUMLib.EnumObj object contained in the ItemDescriptorArray.Enumerator property.

Parameters
Params—optional; currently not used.

Return value
If the method succeeds, the return value is DSAXES_SUCCESS (0). If the method fails, the return value is
a DSAXES status code. See ParseDirectory on page 3–169 for a complete listing of the status codes.

Remarks
The method is used when the PROPFIND command of the DocuShare HTTP/XML API is invoked against
the Server object. The request message must specify schemata as the property being retrieved as shown
below.

set req = CreateObject("DSGateway.ClientRequest")

req.Method = "POST"
req.RequestURI = "dscgi/ds.py/PROPFIND/Server"
req.Header("Depth") = "0"
req.ContentData.DeclareXML
req.ContentData.Text = "<propfind><prop><schemata/></prop></propfind>"
set gateway = server.Open
status = gateway.Submit(req)
set cd = gateway.ServerResponse.ContentData
if 0 = cd.ParseSchema then
set enumObj = cd.ItemDescriptorArray.Enumerator( _
DSCONTF_IDENTITY or DSCONTF_CHILDREN or DSCONTF_DESCENDANTS )
enumObj.Reset
while enumObj.NextPos <> 0
set itemObj = enumObj.NextItem
set enumSchema = itemObj.SchemaEnumerator
enumSchema.Reset
while enumSchema.NextPos <> 0
set itemSchema = enumSchema.NextItem

3–176 DocuShare Windows Client SDK

DSGateway Library Objects

Print itemObj.TypeId, _itemSchema.Name,

itemSchema.HelpText
wend
wend
end if
The parsed result can be directly loaded into a schema enumerator object. An application does not need to
obtain an item enumerator and then retrieve a schema enumerator specific to an object type from an item
object. If EnumSchema.Load is not given a type identifier to restrict the schema enumeration to a specific
object type, the schema items of all object types are enumerated.

if 0 = cd.ParseSchema then
set enumSchema = CreateObject( "DSITEMENUMLib.EnumSchema" )
enumSchema.Load gateway.ServerResponse
enumSchema.Reset
while enumSchema.NextPos <> 0
set itemSchema = enumSchema.NextItem
Print itemSchema.ItemObject.TypeId, _itemSchema.Name,
itemSchema.HelpText
wend
end if
ContentData.ParsedResultType is set to DSXITEMTYPE_SERVER. ContentData.ParsedResultHandle is
set to zero.

DocuShare Windows Client SDK 3–177

Objects DSGateway Library

ParseVersionHistory

VB method ParseVersionHistory ( FileHandle as Variant, ContainerHandles as

Variant ) as long

C++

ParseVersionHistory parses response data from a server for a file's version history information. The
method stores parsed result in the ItemDescriptorArray property.

Parameters

Parameter Description

ContainerHandles Optional; contains one or more string handles

(comma separated) of container objects. For
example, Collection objects where the file
specified by FileHandle appears; or the parameter
may contain the integer handle number of a
Collection object.
A custom Collection handle cannot be specified if
an integer handle number is assigned to this
parameter. For example, if the file appears in both
Collection-10 and Collection-20, the parameter
should be set to Collection-10, Collection-20. If the
parameter is omitted, no container handle will be
saved in item descriptors of queried Version
objects.

FileHandle Optional; contains an integer handle number or a

string handle of a File or custom File object.
If the parameter contains a handle number, the
File object's type is File. If a custom File object is
to be specified, set FileHandle to the string handle
of the custom object, such as myFile-123. If the
parameter is omitted, the value of file handle
defaults to File-0.

Return value
If the method succeeds, the return value is DSAXES_SUCCESS (0). If the method fails, the return value is
a DSAXES status code. See ParseDirectory for a complete listing of the status codes.

Remarks
The method is used when the PROPFIND command of the DocuShare HTTP/XML API is invoked against
a Document object with a depth level of 1 and for querying the object's <versions> property.

The following example uses ParseVersionHistory to parse a response to a history query and generate a
DSITEMENUMLib.EnumObj enumerator for listing the queried version items.

set req = CreateObject("DSGateway.ClientRequest")

3–178 DocuShare Windows Client SDK

DSGateway Library Objects

req.Method = "POST"
req.RequestURI = "dscgi/ds.py/PROPFIND/File-123"
req.Header("Depth") = "1"
req.ContentData.Text = "<?xml version=""1.0""?>" +_
"<propfind>" +_
"<prop><displayname/><versions/></prop>" +_
"</propfind>"
set gateway = server.Open
status = gateway.Submit(req)
set cd = gateway.ServerResponse.ContentData
if cd.ParseVersionHistory("File-123", "Collection-10") = DSAXES_SUCCESS then
set enumObj = cd.ItemDescriptorArray.Enumerator
enumObj.Reset
while enumObj.NextPos <> 0
set itemObj = enumObj.NextItem
Print "Version " & CStr(itemObj.VersionNum), itemObj.Name
wend
end if
The gateway internally calls ContentData.ParseVersionHistory for an operation started by
GatewayHandler.InitiateHistory. Therefore, when using InitiateHistory, an application should not call
ContentData.ParseVersionHistory.

set gateway = server.Open

status = gateway.InitiateHistory("", _
123, "?DSPARENTOBJECT=Collection-10", "", "")
status = gateway.AwaitCompletion
set cd = gateway.ServerResponse.ContentData
set enumObj = cd.ItemDescriptorArray.Enumerator
enumObj.Reset
while enumObj.NextPos <> 0
set itemObj = enumObj.NextItem
Print "Version " & CStr(itemObj.VersionNum), itemObj.Name
wend
The example is functionally equivalent to the earlier example.

DocuShare Windows Client SDK 3–179

Objects DSGateway Library

ParseUploadResult

VB method ParseUploadResult( ContainerHandles as Variant ) as long

C++

ParseUploadResult parses response data as a result of uploading a compound file from a DocuShare
server for the Version and Rendition objects. The parsed Version and Rendition handles and other
information are stored in the ItemDescriptorArray property. The created objects may be enumerated using
the DSITEMENUMLib.EnumObj object contained in the ItemDescriptorArray.Enumerator property.

Parameters
ContainerHandles—optional; an integer handle number of a Collection object where the uploaded file
appears.The parameter may contain the string handle of a Collection or Collection subclass object, a
comma separated list of string handles of Collection, or subclass objects where the uploaded file appears.

Return value
If the method succeeds, the return value is DSAXES_SUCCESS (0). If the method fails, the return value is
a DSAXES status code. See ParseDirectory on page 3–169 for a complete listing of the status codes.

Remarks
The method is used when the ApplyUpload command of the DocuShare HTTP/XML API is invoked for
uploading a compound file.

The example below uploads a compound file consisting of a HTML rendition and two content elements—a
script and an GIF image.

QMARK = chr(&H22) ' double quotation mark

CRLF = vbCr+vbLf ' carriage return and line feed
set req = CreateObject("DSGateway.ClientRequest")
req.Method = "POST"
req.RequestURI = "dscgi/ds.py/ApplyUpload/Collection-10"
req.ContentType = "Content-Type: multipart/form-data;
boundary=17b50a4428b262c8"
set cd1 = req.ContentData;
cd1.Add _
"--17b50a4428b262c8"+CRLF+_
"Content-Disposition: form-data; name="+QMARK+"parent"+QMARK+CRLF+_
CRLF+_
"Collection-10"+CRLF+_
"--17b50a4428b262c8"+CRLF+_
"Content-Disposition: form-data;
name="+QMARK+"file1_name"+QMARK+CRLF+_
CRLF+_
"test1.htm"+CRLF+_

3–180 DocuShare Windows Client SDK

DSGateway Library Objects

"--17b50a4428b262c8"+CRLF+_
"Content-Disposition: form-data; name="+QMARK+"title"+QMARK+CRLF+_
CRLF+_
"Test file no. 1"+CRLF+_
"--17b50a4428b262c8"+CRLF+_
"Content-Disposition: form-data;
name="+QMARK+"max_versions"+QMARK+CRLF+_
CRLF+_
"4"+CRLF+_
"--17b50a4428b262c8"+CRLF+_
"Content-Disposition: form-data; name="+QMARK+"file1"+QMARK+CRLF+_
"Content-Type: multipart/mixed; boundary=78db18672a051a16"+CRLF+_
CRLF+_
"--17b50a4428b262c8"+CRLF+_
"Content-Disposition: inline;
filename="+QMARK+"test1.htm"+QMARK+CRLF+_
"Content-Type: text/html"+CRLF+_
"Content-Transfer-Encoding: binary"+CRLF+CRLF
cd1.Add _
"c:\doc\test.htm" ' path of rendition file
cd1.Add _
CRLF+_
"--78db18672a051a16"+CRLF+
"Content-Disposition: attachment;
filename="+QMARK+"a1.js"+QMARK+CRLF+
"Content-Type: text/plain"+CRLF+CRLF
cd1.Add _
"c:\doc\test1\a1.js" ' first content element file
cd1.Add _
CRLF+_
"--78db18672a051a16"+CRLF+
"Content-Disposition: attachment;
filename="+QMARK+"a2.gif"+QMARK+CRLF+
"Content-Type: image/gif"+CRLF+
"Content-Transfer-Encoding: binary"+CRLF+CRLF
cd1.Add _
"c:\doc\test1\a2.gif" ' second content element file
cd1.Add _
CRLF+_

DocuShare Windows Client SDK 3–181

Objects DSGateway Library

"--78db18672a051a16--"+CRLF+
"--17b50a4428b262c8--"+CRLF+CRLF
set gateway = server.Open
status = gateway.Submit(req)
set cd2 = gateway.ServerResponse.ContentData
if 0 = cd2.ParseUploadResult then
set enumObj = cd2.ItemDescriptorArray.Enumerator( _
DSCONTF_IDENTITY or DSCONTF_DESCENDANTS )
enumObj.Reset
while enumObj.NextPos <> 0
set itemObj = enumObj.NextItem
Print itemObj.Handle, itemObj.Name
wend
end if
The gateway internally calls ContentData.ParseUploadResult for an operation started by
GatewayHandler.Upload if the input ItemObj file object has a compound structure. Therefore, when using
Upload, an application should not call ContentData.ParseUploadResult.

set fileObj = server.CreateObject("File")

fileObj.Title = "Test file no. 1"

fileObj.Name = "test1.htm"

fileObj.MaxVersions = 2

set attachEnum = fileObj.EnumObjects(DSCONTF_ATTACH)

set attach1 = attachEnum.NewItem

attach1.Name = "c:\doc\test1\a1.js"

set attach2 = attachEnum.NewItem

attach2.Name = "c:\doc\test1\a2.gif"

set gateway = server.Open

status = gateway.Upload(_

DSAXES_PROPID_TITLE, _

DSAXES_PROPID_FILENAME or DSAXES_PROPID_MAXVERSIONS, _

fileObj, "c:\doc\test1.htm")

if status = 0 then

set cd2 = gateway.ServerResponse.ContentData

set enumObj = cd2.ItemDescriptorArray.Enumerator( _

3–182 DocuShare Windows Client SDK

DSGateway Library Objects

DSCONTF_IDENTITY or DSCONTF_DESCENDANTS )

enumObj.Reset

while enumObj.NextPos <> 0

set itemObj = enumObj.NextItem

Print itemObj.Handle, itemObj.Name

wend

end if

The example is functionally equivalent to the earlier example.

ContentData.ParsedResultType is set to the type number, such as DSXITEMTYPE_DOCUMENT, of the

uploaded File object. ContentData.ParsedResultHandle is set to the handle number of the upload File
object.

DocuShare Windows Client SDK 3–183

Objects DSGateway Library

Verify

VB Verify( idCmd as DSX_CMDID, Param1 as optional Variant, Param2 as

optional Variant, VerifiedItem as optional Variant ) as long

C++ long Verify( DSX_CMDID idCmd, VARIANT* Param1, VARIANT* Param2,

VARIANT* VerifiedItem );

Verifies that a command was successfully processed by comparing the HTTP result code with known
success codes and by comparing the value in the DocuShare-Handle header field of the server response
with a DocuShare handle for which the command was invoked.

Parameters

Parameter Description

idCmd Command identifier that specifies the type of client

request that the client gateway and a DocuShare
server has processed.

Param1 Optional: the parameter depends on the command

identifier. See below.

Param2 Optional: the parameter depends on the command

identifier. See below.

VerifiedItem Optional: holds a DSITEMENUMLib.ItemObj

object whose Handle property is set to the verified
handle.

idCmd Param1 Param2 Verified Item

CMDID_DELETE String handle of deleted Not used. ItemObj.Handle

item. contains the handle of
the deleted item.
Integer handle number. Integer handle type
number.

CMDID_MOVE Source container Destination container ItemObj.Handle

handle. handle. contains the handle of
the moved item.
ItemObj.ParentItemObj
ect contains an ItemObj
object for the
destination container.

3–184 DocuShare Windows Client SDK

DSGateway Library Objects

idCmd Param1 Param2 Verified Item

CMDID_GETPROPS String handle of target Integer handle type ItemObj.Title contains

item. number. the title of the queried
item.
Integer handle number.
ItemObj.ParentItemObj
ect contains an ItemObj
for a parent object.

CMDID_SETPROPS String handle of target Not used. ItemObj.Handle

item contains the handle of
the queried item.
Integer handle number. Integer handle type
number.

CMDID_LOCK String handle of target True ItemObj.Handle

file. contains the handle of
the locked file.
Integer File handle True
number. ItemObj.User contains
the lock owner's name
and handle.

CMDID_UNLOCK String handle of target True ItemObj.Handle

file. contains the handle of
the unlocked file.
Integer File handle True
number

Others Not used Not used ItemObj.Handle

contains the value of
the
"DocuShare-handle"
header field in
response

Return value
If the method succeeds, the return value is DSAXES_SUCCESS (0). If the method fails, the return value is
a DSAXES status code. See ParseDirectory on page 3–169 for a complete listing of the status codes.

Remarks
The method only performs a simple HTTP status code check if the command performed is other than the
ones that appeared in the above table.

The example below uses ContentData.Verify to verify the result of a File MOVE operation.

set req = CreateObject("DSGateway.ClientRequest")

req.Method = "POST"
req.RequestURI = "dscgi/ds.py/MOVE/File-123"
req.Header("SOURCE") = "Collection-10"
req.Header("DESTINATION") = "Collection-12"
set gateway = server.Open

DocuShare Windows Client SDK 3–185

Objects DSGateway Library

status = gateway.Submit(req)
set cd = gateway.ServerResponse.ContentData
if 0 = cd.Verify(CMDID_MOVE, _
req.Header("SOURCE"), req.Header("DESTINATION"), _
verifiedItem) then
Print verifiedItem.Handle
end if
The gateway automatically invokes the method when one of the GatewayHandler following methods is
invoked.

Method idCmd for Verify

InitiateCopy CMDID_MOVE

InitiateMove CMDID_MOVE

InitiateDelete CMDID_DELETE

InitiateLock CMDID_LOCK or CMDID_UNLOCK

GetProps CMDID_GETPROPS

SetProps CMDID_SETPROPS

3–186 DocuShare Windows Client SDK

DSGateway Library Objects

3.2.7.2 ContentData properties

This section contains ContentData property definitions.

CleanText

VB CleanText() as String

C++ CString GetCleanText();

Access Read only

CleanText contains plain text content data. If the content type is text/html, HTML tags are removed.

DataCompression

VB DataCompression as Boolean

C++ BOOL GetDataCompression();

Access Read only

DataCompression determines the following:

• if the content data should be compressed in gzip if the data belongs to a request message
• if the content data belongs to a response message and was compressed in gzip when it was
received from the server and was uncompressed by the gateway

DocuShare Windows Client SDK 3–187

Objects DSGateway Library

Delta

VB Delta as Variant

C++ VARIANT* GetDelta();

Access Read only

Delta contains a portion of content data in text format from a server, but was not retrieved by a previous
reference to Delta.

Remarks
The Delta property, typically used as a DocuShare resource access method of GatewayHandler, is started
asynchronously. As content data of a response message arrives at the client gateway, an application uses
Delta to obtain parts of the data that was not retrieved.

Use Delta only if the content type is in text formats such as html, xml, or plain.

The example below calls an asynchronous method of GatewayHandler, uses Delta to incrementally
retrieve the content data the server sends, and writes it to a local file.

const DSAXES_INPROG = 1
set fso = CreateObject("Scripting.FileSystemObject")
set f = fso.OpenTextFile("c:\temp\dump.txt", 2, True)
set server = CreateObject("DSServerMap.Server")
server.DocuShareAddress = "http://www.xyz.com/docushare/"
server.UserName = "admin"
if server.Logon = 0 then
set gateway = server.Open
gateway.InitiateCollectionOpen("", 10, "", "", "")
while gateway.Wait(100, hasResponse) = DSAXES_INPROG then
if HasResponse then
f.Write gateway.ServerResponse.ContentData.Delta
end if
wend
if HasResponse then
f.Write gateway.ServerResponse.ContentData.Delta
end if
f.Close
end if
In the example above, the Wait method of GatewayHandler is used to ensure that a response is in and that
a ServerResponse object is available.

3–188 DocuShare Windows Client SDK

DSGateway Library Objects

File

VB File as string

C++ CString GetFile();

Access Read/Write

File contains the pathname for a file that stores content data.

ParsedResultHandle

VB property ParsedResultHandle as long

C++

Access Read only

ParsedResultHandle contains the handle number of a DocuShare item that resulted from the parsing of
response data from a DocuShare server.

Remarks
See Remarks in ParsedResultType on page 3–190.

DocuShare Windows Client SDK 3–189

Objects DSGateway Library

ParsedResultType

VB property ParsedResultType as long

C++

Access Read only

ParsedResultType contains the item type number of a DocuShare item that resulted from the parsing of
response data from a DocuShare server.

Remarks
The value of this property is updated whenever any of the methods below is invoked.

Method ParsedResultType (ParsedResultHandle)

ParseDirectory Type (Handle) of queried Collection

ParseProperties Parent of queried object

ParsePropertiesAsDsxInfo Parent of queried object

ParseQueryResults 0 (number of hits)

ParseSchema DSXITEMTYPE_SERVER (0)

ParseUploadResult Type (Handle) of uploaded Document

ParseVersionHistory Type (Handle) of queried Document

3–190 DocuShare Windows Client SDK

DSGateway Library Objects

StorageMedium

VB StorageMedium as DSX_STGMEDIUM

C++ DSX_STGMEDIUM GetStorageMedium();

Access Read only

StorageMedium determines the type of storage medium that the gateway uses to store content data.

Type ID Storage Medium

STGMEDIUM_FILE File on a disk

STGMEDIUM_MEMORY In-memory buffer

STGMEDIUM_STREAM IStream stream object

STGMEDIUM_UNKNOWN Unknown (for example, no content data)

Stream

VB Stream as Variant

C++ VARIANT* GetStream();

Access Read/Write

Stream contains an object of the IStream interface that stores content data.

DocuShare Windows Client SDK 3–191

Objects DSGateway Library

Text

VB Text as String

C++ CString GetText();

void SetText( LPCTSTR );

Access Read/Write

Text contains raw text data that comprises the content data.

Remarks
Use this property if the content type is the following text formats: html, xml, or plain.

If the content data belongs to a request message and the DeclareXML method has been called, assigning
textual data to the Text property causes the textual data to be preceded with an xml declaration of form
"<?xml version=1.0 ?>". See DeclareXML on page 3–168 for more details.

XMLDOM

VB XMLDOM as Object IXMLDOMDocument

C++ IDispatch* GetXMLDOM();’

void SetXMLDOM( IDispatch* );

Access Read/Write

XMLDOM contains an object of the IXMLDOMDocument interface that stores content data if the content
type is text/xml.

3–192 DocuShare Windows Client SDK

DSGateway Library Objects

ItemDescriptorArray

VB ItemDescriptorArray as Object ItemDescriptorArray

C++ IDispatch* GetItemDescriptorArray();

Access Read only

ItemDescriptorArray contains an ItemDescriptorArray object if the ContentData belongs to a

ServerResponse object. ItemDescriptorArray abstracts directory information for items that appear in a
DocuShare collection or other container object.

Remarks
ItemDescriptorArray is reset and loaded with item descriptor data when one of the following methods is
invoked:

• ParseDirectory
• ParseQueryResults
• ParseSchema
• ParseUploadResult
• ParseVersionHistory
The example below calls ParseDirectory to fill ItemDescriptorArray with directory information. It uses the
object to list the items that appear in Collection-10.

set gateway = CreateObject("DSGateway.GatewayHandler")

gateway.DSAccessData.DocuShareAddress = "http://ds.xyz.com/"
set request = CreateObject("DSGateway.ClientRequest")
request.Method = "POST"
request.Header("Depth") = 1
request.RequestURI = "dscgi/ds.py/PROPFIND/Collection-10"
status = gateway.Submit(request)
set response = gateway.ServerResponse
response.ContentData.ParseDirectory
set enumObj = response.ContentData.ItemDescriptorArray.Enumerator
enumObj.Reset
while enumObj.NextPos
set itemObj = enumObj.NextItem
PrintRow itemObj.Handle, itemObj.Title, itemObj.Summary
wend

DocuShare Windows Client SDK 3–193

Objects DSGateway Library

ItemProperties

VB ItemProperties as Object ItemProperties

C++

Access

ItemProperties contains an ItemProperties object that enumerate property settings of a DocuShare item.

Remarks
The methods below updates the current ItemProperties object with property information.

• ParseProperties
• ParsePropertiesAsDsxInfo

3–194 DocuShare Windows Client SDK

DSGateway Library Objects

3.2.8 PropertyIDs
Use property GatewaySettings.QueriedProperties to obtain a PropertyIDs enumerator object.
SearchRequest.QueriedProperties also produces a PropertyIDs object.

List of PropertyIDs methods and properties

Methods and Properties

Add

Clear

Count

List

PropertyID

Remove

3.2.8.1 PropertyIDs methods

This section contains PropertyIDs method definitions.

Add

VB Add(ID as Variant, ItemType as Variant) as PropertyID

C++

Add creates a PropertyID object of a specified identifier and item type, and add it to the PropertyIDs.

Parameters

Parameter Description

ID A DSAXES_PROPID property identifier.

ItemType A DSXITEMTYPE item type number.

Clear

VB Clear()

C++

Clear removes all PropertyID objects from the PropertyIDs.

DocuShare Windows Client SDK 3–195

Objects DSGateway Library

Remove

VB Remove(Index as Variant)

C++

Removes from the PropertyIDs a PropertyID object at a specified index position.

Parameters
Index—a 0-based index number. It must be less than the value of Count.

3–196 DocuShare Windows Client SDK

DSGateway Library Objects

3.2.8.2 PropertyIDs properties

This section contains PropertyIDs property definitions.

Count

VB Property Count as long

C++

Access Read only

Count contains the number of PropertyID objects within the PropertyIDs.

List

VB Property List(Prefix as Variant, Suffix as Variant) as string

C++

Access Read only

List generates a linear list of DocuShare property identifiers enumerated by the PropertyIDs.

Parameters

Parameter Description

Prefix A prefix string to be prepended to each property

name.

Suffix A suffix string to be appended to each property

name.

Remarks
The following script lists the names of properties currently selected for OpenCollection,
InitiateCollectionOpen, and Search of GatewayHandler:

set gateway = server.OpenGateway

set propIds = gateway.GetawaySettings.QueriedPropertyIDs
propList = propIds.List("PropID: ", vbCr)
MsgBox propList

DocuShare Windows Client SDK 3–197

Objects DSGateway Library

PropertyID

VB PropertyID(Index as Variant) as Object PropertyID

C++ IDispatch* GetPropertyID( VARIANT* Index );

Access Read only

PropertyID contains a PropertyID object at a specified index position.

3–198 DocuShare Windows Client SDK

DSGateway Library Objects

3.2.9 PropertyID
List of PropertyID methods and properties

Methods and Properties

ID

ItemType

Text

3.2.9.1 PropertyID methods

There are no methods defined for this object.

3.2.9.2 PropertyID properties

This section contains PropertyID properties.

ID

VB ID as long

C++ long GetID();

void SetID( long );

Access Read/Write

ID contains a DSAXES_PROPID property identifier for the DocuShare property represented by the
PropertyID.

ItemType

VB ItemType as long

C++ long GetItemType();

void SetItemType( long );

Access Read/Write

ItemType contains a DSXITEMTYPE item type number for the item type defined by the PropertyID.

DocuShare Windows Client SDK 3–199

Objects DSGateway Library

Text

VB Text as String

C++ CString GetText();

void SetText( LPCTSTR );

Access Read/Write

Text contains a DocuShare property name for the DocuShare property represented by the PropertyID.

3–200 DocuShare Windows Client SDK

DSGateway Library Objects

3.2.10 ItemProperties
Use ClientRequest.ContentData.ItemProperties or ServerResponse.ContentData.ItemProperties to
retrieve an ItemProperties enumerator object.

List of ItemProperties methods and properties

Methods and Properties

Add

Clear

CopyTo

Count

ItemObject

ItemProperty

Remove

3.2.10.1 ItemProperties methods

This section contains ItemProperties method definitions.

Add

VB Add(ID as optional Variant, Value as optional Variant) as ItemProperty

C++ IDispatch* Add( VARIANT* ID, VARIANT* Value );

Add creates an ItemProperty object of a specified property identifier and property value and adds it to the
ItemProperties.

Parameters

Parameter Description

ID A DocuShare property identifier.

Value A value for the property.

Clear

VB Clear()

C++ void Clear();

Clear removes all ItemProperty objects from the ItemProperties.

DocuShare Windows Client SDK 3–201

Objects DSGateway Library

CopyTo

VB CopyTo( DestProps as ItemProperties );

C++ void CopyTo( IDispatch* DestProps );

CopyTo copies all properties enumerated by the source ItemProperties object to a destination
ItemProperties object.

Remarks
The following example uses CopyTo to pass the properties enumerated by the ContentData of a client
request to the ContentData of a server response so that the ContentData.ParseProperties method knows
which specific properties to retrieve from the response data.

set req = CreateObject("DSGateway.ClientRequest")

req.Method = "POST"
req.RequestURI = "PROPFIND/Collection-10"
req.Header("depth") = "0"
req.ContentData.DeclareXML
set props1 = CreateObject("DSGateway.ItemProperties")
props1.Add "displayname"
props1.Add "summary"
props1.Add "description"
req.ContentData.Add props1
set gateway = server.Open
status = gateway.Submit(req)
set cd = gateway.ServerResponse.ContentData
set props2 = cd.ItemProperties
props1.CopyTo props2
if cd.ParseProperties() = DSAXES_SUCCESS then
for i = 0 to props2.Count-1
set prop = props2.ItemProperty(i)
if vbOK <> MsgBox(_
prop.ID & ": " & prop.Value,_
vbOkCancel,_
prop.DisplayName) then
exit sub
end if
next
end if

3–202 DocuShare Windows Client SDK

DSGateway Library Objects

Remove

VB Method Remove(Index as Variant)

C++

Removes an ItemProperty object from the ItemProperties at a specified index position.

Parameters
Index—a 0-based index number. It must be less than the value of Count.

3.2.10.2 ItemProperties properties

This section contains ItemProperties property definitions.

Count

VB Count as long

C++ long GetCount();

Access Read only

Count contains the number of ItemProperty objects within the ItemProperties.

ItemObject

VB ItemObject as Object DSITEMENUMLib.ItemObj

C++ IDispatch* GetItemObject();

Access Read only

ItemObject contains an ItemObj object that stores the values of DocuShare properties enumerated by the
ItemProperties.

ItemProperty

VB ItemProperty(Index as Variant) as Object ItemProperty

C++ IDispatch* GetItemProperty();

Access Read only

ItemProperty contains an ItemProperty object at a specified index position.

Parameters
Index—a 0-based index number. It must be less than the value of Count.

DocuShare Windows Client SDK 3–203

Objects DSGateway Library

3.2.11 ItemProperty
List of ItemProperty methods and properties

Methods and Properties

DisplayName

ID

Value

3.2.11.1 ItemProperty methods

There are no methods defined for this object.

3.2.11.2 ItemProperty properties

This section contains ItemProperty property definitions.

DisplayName

VB DisplayName as Variant

C++ VARIANT* GetDisplayName();

void SetDisplayName( VARIANT );

Access Read/Write

DisplayName contains a display name for the DocuShare property defined by the ItemProperty.

ID

VB ID as Variant

C++ VARIANT* GetID();

void SetID( VARIANT );

Access Read/Write

ID contains a DocuShare property name for the DocuShare property represented by the PropertyID.

3–204 DocuShare Windows Client SDK

DSGateway Library Objects

Value

VB Value as Variant

C++ VARIANT* GetValue();

void SetValue( VARIANT );

Access Read/Write

Value contains a value for the DocuShare property that the ItemProperty represents.

DocuShare Windows Client SDK 3–205

Objects DSGateway Library

3.2.12 ItemDescriptorArray
Use ContenData.ItemDescriptorArray to obtain an ItemDescriptorArray object.

List of ItemDescriptorArray methods and properties

Methods and Properties

Enumerator

ErrorDescription

File

StorageMedium

3.2.12.1 ItemDescriptorArray
There are no methods defined for this object.

3.2.12.2 ItemDescriptorArray properties

This section contains ItemDescriptorArray property definitions.

Enumerator

VB Enumerator(Flags as optional Variant) as Object DSITEMENUMLib.EnumObj

C++ IDispatch* GetEnumerator( VARIANT* Flags );

Access Read only

Enumerator creates an EnumObj item enumerator object based on the item descriptor array.

Parameters
Flags—Optional; DSCONTF flags used by EnumObj.Load. If Flags are omitted, a value of zero is used to
call EnumObj.Load internally.

Remarks
Internally, the gateway creates an instance of EnumObj; the gateway calls EnumObj.Load to load the item
descriptors into the EnumObj.

ErrorDescription

VB ErrorDescription as string

C++ CString GetErrorDescription();

Access Read only

ErrorDescription contains an error description for a parsing error if the gateway encountered an error while
attempting to convert content data into an item descriptor array.

3–206 DocuShare Windows Client SDK

DSGateway Library Objects

File

VB File as string

C++ CString GetFile();

void SetFile( LPCTSTR );

Access Read/Write

File contains a pathname for a file that stores the item descriptor array.

StorageMedium

VB StorageMedium as DSX_STGMEDIUM

C++ DSX_STGMEDIUM GetStorageMedium();

void SetStorageMedium( DSX_STGMEDIUM );

Access Read/Write

StorageMedium determines the type of storage used to store the item descriptor array.

Remarks
An item descriptor array is a linear collection of DSXCOLLECTIONITEMINFO descriptors. The valid types
are:

• STGMEDIUM_STREAM—stored as an in-memory stream on the descriptor array.

• STGMEDIUM_FILE—stored in a disk-resident file.
• STGMEDIUM_UNKNOWN—defaults to the stream medium.

DocuShare Windows Client SDK 3–207

Objects DSGateway Library

3.2.13 SearchRequest
Applications use the SearchRequest object to build a search request which is passed to the
GatewayHandler.Submit method for submission to a DocuShare server. The search results returned by the
server are parsed from the server response data by calling the ContentData.ParseQueryResults method of
the GatewayHandler.ServerResponse object.

set gateway = CreateObject("DSGateway.GatewayHandler")

set request = CreateObject("DSGateway.SearchRequest")
... ' assign search criteria through SearchRequest
gateway.Submit request
gateway.ServerResponse.ContentData.ParseQueryResults
The parsed results are stored in the ItemDescriptorArray property of the response ContentData. Use the
Enumerator property which contains a DSITEMENUMLib.EnumObj enumerator object to walk through the
found objects.

SearchRequest exposes the SearchTermCollection property. The latter is used to form search criteria. To
build a nested query, an application can use the Terms.NestedTerms property which is
SearchTermsCollection.

The script below creates the query: find objects of File or Collection which were created or modified
between 1/1/03 and 2/1/03.

set request = CreateObject("DSGateway.SearchRequest")

request.SearchTermsCollection.Conjunct = "and"
set types = request.SearchTermsCollection.Add
types.Conjunct = "or"
types.Add "entitytype", "eq", "File"
types.Add "entitytype", "eq", "Collection"
set terms = request.SearchTermsCollection.Add
terms.NestedTerms.Conjunct = "or"
set mtimes = terms.NestedTerms.Add
mtimes.Conjunct = "and"
mtimes.Add "getlastmodified", "gte", #1/1/2003#
mtimes.Add "getlastmodified", "lte", #2/1/2003#
set ctimes = terms.NestedTerms.Add
ctimes.Conjunct = "and"
ctimes.Add "getlastmodified", "gte", #1/1/2003#
ctimes.Add "getlastmodified", "lte", #2/1/2003#

3–208 DocuShare Windows Client SDK

DSGateway Library Objects

List of SearchRequest methods and properties

Methods and Properties

MaxHits

QueriedProperties

Scope

SearchTermsCollection

3.2.13.1 SearchRequest methods

There are no methods defined for this object.

3.2.13.2 SearchRequest properties

This section contains SearchRequest property definitions.

MaxHits

VB MaxHits as long

C++

Access

MaxHits specifies a maximum number of hits a search can generate.

QueriedProperties

VB QueriedProperties as Object PropertyIDs

C++ IDispatch* GetQueriedProperties();

Access Read-only

QueriedProperties contains a property ID enumerator for properties that are to be retrieved for objects
found by a search.

Remarks
If no property ID is added to QueriedProperties, the queried property IDs contained in the
GatewayHandler.GatewaySettings property will be adopted by the search.

The example below uses QueriedProperties to specify which File properties should be retrieved for File
objects found from the query. After the response is parsed, the QueriedProperties is reused to read the
value of each of the retrieved properties from an ItemObj object that encapsulates a found DocuShare File
object.

DocuShare Windows Client SDK 3–209

Objects DSGateway Library

set request = CreateObject("DSGateway.SearchRequest")

request.QueriedProperties.Add "displayname"
request.QueriedProperties.Add "summary"
request.QueriedProperties.Add "handle"
request.QueriedProperties.Add "parents"
request.SearchTermsCollection.Conjunct = "and"
set terms = request.SearchTermsCollection.Add
terms.Conjunct = "and"
terms.Add "entitytype", "eq", "File"
terms.Add "displayname", "contains", "proposal"
terms.Add "entityowner", "eq", "admin"
set gateway = CreateObject("DSGateway.GatewayHandler")
gateway.DSAccessData.DocuShareAddress = "http://www.xyz.com/docushare/"
gateway.GatewaySettings.AddDSCGI = True
status = gateway.Submit(request)
set cd = gateway.ServerResponse.ContentData
cd.ParseQueryResults
set enumObj = cd.ItemDescriptorArray.Enumerator(_
DSCONTF_CHILDREN or DSCONTF_DESCENDANTS )
enumObj.Reset
while enumObj.NextPos <> 0
set itemObj = enumObj.NextItem
for i = 0 to request.QueriedProperties.Count
set propId = request.QueriedProperties.PropertyID(i)
Print itemObj.Prop(propId)
next
wend end if

3–210 DocuShare Windows Client SDK

DSGateway Library Objects

Scope

VB Scope as String

C++ CString GetScope();

void SetScope( LPCTSTR );

Access Read/Write

Scope contains the DocuShare handle of a DocuShare container object which specifies a search scope. A
search scope restricts a search to the container object and to objects contained within.

Remarks
By default, Scope is empty, which means the search scope spans an entire server.

The script below uses Scope to limit the search to contents within Collection-10 and its sub-collections.

set request = CreateObject("DSGateway.SearchRequest")

request.MaxHits = 10
request.Scope = "Collection-10"
request.Header("depth") = "infinity"
set terms = request.SearchTermsCollection.Add
terms.Conjunct = "and"
terms.Add "entitytype", "eq", "File"
terms.Add "displayname", "contains", "proposal"

DocuShare Windows Client SDK 3–211

Objects DSGateway Library

SearchTermsCollection

VB SearchTermsCollection as Object

C++ IDispatch* GetSearchTermsCollection();

Access Read-only

SearchTermsCollection contains a SearchTermsCollection object which is used to specify one or more

groups of search terms and how they are logically joined—for example, logically OR'ed or AND'ed. A
group of search terms is added by calling the SearchTermsCollection.Add method.

Remarks
The script fragment below creates three groups of search terms:

• File objects whose title contains word "proposal"

• Event objects whose title contains word "meeting"
• Bulletin objects whose title contains word "news"
set request = CreateObject("DSGateway.SearchRequest")
request.SearchTermsCollection.Conjunct = "or"
set terms1 = request.SearchTermsCollection.Add
terms1.Conjunct = "and"
terms1.Add "entitytype", "eq", "File"
terms1.Add "displayname", "contains", "proposal"
set terms2 = request.SearchTermsCollection.Add
terms2.Conjunct = "and"
terms2.Add "entitytype", "eq", "Event"
terms2.Add "displayname", "contains", "meeting"
set terms3 = request.SearchTermsCollection.Add
terms3.Conjunct = "and"
terms3.Add "entitytype", "eq", "Bulletin"
terms3.Add "displayname", "contains", "news"

3–212 DocuShare Windows Client SDK

DSGateway Library Objects

3.2.14 SearchTermsCollection
Use SearchRequest.SearchTermsCollection to obtain a SearchTermsCollection object.

List of SearchTermsCollection methods and properties

Methods and Properties

Add

Count

Conjunct

Remove

Terms

XMLText

3.2.14.1 SearchTermsCollection methods

This section contains SearchTermsCollection method definitions.

Add

VB Add( ID as optional Variant ) as object SearchTerms

C++ IDispatch* Add( VARIANT* ID );

Add creates a new SearchTerms and adds it to the SearchTermsCollection.

Parameters
ID—optional string identifier. If the Remove method is called, the index of a SearchTerms object may
change. Because a particular SearchTerms may not stay at the same index, an application which needs to
come back to the SearchTerms, may want to use the ID parameter and supply an application-specific
identifier.

Remove

VB Remove( Index as Variant )

C++ void Remove( VARIANT* Index );

This method removes a SearchTerms object from the SearchTermsCollection.

Parameters
Index— index number of a SearchTerms object.

DocuShare Windows Client SDK 3–213

Objects DSGateway Library

3.2.14.2 SearchTermsCollection properties

This section contains SearchTermsCollection property definitions.

Count

VB Count as long

C++ long GetCount();

Access Read-only

This property contains a count for the SearchTerms objects within the SearchTermsCollection.

Remarks
A call, to Add or Remove, updates the value of Count.

Conjunct

VB Conjunct as String

C++ CString GetConjunct();

Access Read/Write

Conjunct determines if the groups of search terms, as specified by SearchTerms objects, contained in the
SearchTermsCollection are OR- or AND-joined.

Remarks
Conjunct is set to or or and.

The value of Conjunct is irrelevant and ignored if SearchTermsCollection contains only one SearchTerms
object.

Terms

VB Terms( Index as Long ) as object SearchTerms

C++ IDispatch* GetTerms( long Index );

Access Read-only

Terms contains a SearchTerms object attached to the SearchTermsCollection.

Parameters
Index—zero-based index number of a SearchTerms object to reference. The value must be less than
Count.

3–214 DocuShare Windows Client SDK

DSGateway Library Objects

XMLText

VB XMLText as String

C++ CString GetXMLText();

Access Read-only

XMLText generates XML text data based on the groups of search terms contained in the
SearchTermsCollection.

Remarks
GatewayHandler.Submit internally uses XMLText to generate XML content data for a search request to be
sent to a DocuShare server.

The script below uses XMLText to display the xml rendition of search terms contained in a
SearchTermsCollection.

set request = CreateObject("DSGateway.SearchRequest")

request.SearchTermsCollection.Conjunct = "or"
set terms1 = request.SearchTermsCollection.Add
terms1.Conjunct = "and"
terms1.Add "entitytype", "eq", "File"
terms1.Add "displayname", "contains", "proposal"
set terms2 = request.SearchTermsCollection.Add
terms2.Conjunct = "and"
terms2.Add "entitytype", "eq", "Event"
terms2.Add "displayname", "contains", "meeting"
set terms3 = request.SearchTermsCollection.Add
terms3.Conjunct = "and"
terms3.Add "entitytype", "eq", "Bulletin"
terms3.Add "displayname", "contains", "news"
MsgBox request.SearchTermsCollection.XMLText
When executed, the script displays the following XML data in a message box:

<or>
<and>
<eq>
<prop><entitytype/></prop>
<literal><![CDATA[File]]></literal>
</eq>
<contains>
<prop><displayname/></prop>
<literal><![CDATA[proposal]]></literal>

DocuShare Windows Client SDK 3–215

Objects DSGateway Library

</contains>
</and>
<and>
<eq>
<prop><entitytype/></prop>
<literal><![CDATA[Event]]></literal>
</eq>
<contains>
<prop><displayname/></prop>
<literal><![CDATA[meeting]]></literal>
</contains>
</and>
<and>
<eq>
<prop><entitytype/></prop>
<literal><![CDATA[Bulletin]]></literal>
</eq>
<contains>
<prop><displayname/></prop>
<literal><![CDATA[news]]></literal>
</contains>
</and>
</or>

3–216 DocuShare Windows Client SDK

DSGateway Library Objects

3.2.15 SearchTerms
Use SearchRequest.SearchTermsCollection.Terms to obtain a SearchTerms collection object.

List of SearchTerms methods and properties

Methods and Properties

Add

Count

Conjunct

ID

NestedTerms

Remove

Term

XMLText

3.2.15.1 SearchTerms methods

This section contains SearchTerms method definitions.

Add

VB Add( Name as Variant, Operator as Variant, Value as Variant ) as object

SearchTerm

C++ IDispatch* Add( VARIANT* Name, VARIANT* Operator, VARIANT* Value );

Add creates a new SearchTerm and adds it to the SearchTerms.

Parameters

Parameter Description

Name Optional; the string name for a DocuShare

property.

Operator Optional; a string operator that specifies how

Name operates on Value. Valid operators differ,
depending on the data type associated with the
property name specified in Name. For example,
the valid operators of a string property type are
contains and eq.

DocuShare Windows Client SDK 3–217

Objects DSGateway Library

Remove

VB Remove( Index as Variant )

C++ void Remove( VARIANT* Index );

This method removes a SearchTerms object from the SearchTermsCollection.

Parameters
Index—index number of a SearchTerms object.

3.2.15.2 SearchTerms properties

This section contains SearchTerms property definitions.

Count

VB Count as Long

C++ long GetCount();

Access Read-only

This property contains a count for the SearchTerm objects within the SearchTerms.

Remarks
A call, to Add or Remove, updates the value of Count.

Conjunct

VB Conjunct as String

C++ CString GetConjunct();

void SetConjunct( LPCTSTR );

Access Read/Write

Conjunct determines if the search terms, as specified by SearchTerm objects, contained in the
SearchTerms are OR- or AND-joined.

Remarks
Conjunct is set to or or and. Conjunct can also be set to not, to negate the operation for a search term
contained in the SearchTerms.

The or or and value of Conjunct is irrelevant and ignored if SearchTerms contains only one SearchTerm
object.

3–218 DocuShare Windows Client SDK

DSGateway Library Objects

ID

VB ID as String

C++ CString GetID();

void SetID( LPCTSTR );

Access Read/Write

ID contains a identifier application assigned to the SearchTerms for application-specific identification

purposes.

NestedTerms

VB NestedTerms as object SearchTermsCollection

C++ IDispatch* GetNestedTerms();

Access Read only

NestedTerms contains a SearchTermsCollection object which is used to specify one or more groups of
search terms nested within the current SearchTerms.

Term

VB Term( Index as Long ) as object SearchTerm

C++ IDispatch* GetTerm( long Index );

Access Read-only

Terms contains a SearchTerm object attached to the SearchTerms.

Parameters
Index—zero-based index number of a SearchTerm object to reference. The value must be less than
Count.

XMLText

VB XMLText as String

C++ CString GetXMLText();

Access Read only

XMLText generates XML text data based on the search terms contained in the SearchTerms.

DocuShare Windows Client SDK 3–219

Objects DSGateway Library

3.2.16 SearchTerm
Use SearchRequest.SearchTermsCollection.Terms.Term to obtain a SearchTerm object.

List of SearchTerm methods and properties

Methods and Properties

Name

Operator

Value

XMLText

3.2.16.1 SearchTerm methods

There are no methods defined for this object.

3.2.16.2 SearchTerm properties

This section provide details for individual SearchTerm properties.

Name

VB Name as String

C++ CString GetName();

void SetName( LPCTSTR );

Access Read/Write

This property contains the name of a DocuShare property which is also the name of the search term.

3–220 DocuShare Windows Client SDK

DSGateway Library Objects

Operator

VB Operator as String

C++ CString GetOperator();

void SetOperator( LPCTSTR );

Access Read/Write

This property contains an operator for the search term.

Remarks
The valid operators depend on the search term association with the property type. Operators valid for
typical property types are shown below.

Property Type Valid Operators

String or, and, eq

Date gte, lte, gt, lt, eq

DocuShare handle eq

Integer gte, lte, gt, lt, eq

Float gte, lte, gt, lt, eq

Value

VB Value as Variant

C++ VARIANT* GetValue();

void SetValue( VARIANT );

Access Read/Write

This property contains a value for the search term. Property Name operates on property Value based on
the operation specified in property Operator.

XMLText

VB XMLText as String

C++ CString GetXMLText();

Access Read only

XMLText generates XML text data based on the search term contained in the SearchTerm.

DocuShare Windows Client SDK 3–221

Constants DSGateway Library

3.3 Constants
3.3.1 Special handle values

Special Handle Values

const long DSXHANDLENUM_DSOBJECTHANDLE = -2

const long DSXHANDLENUM_SERVERADDRHASHANDLE = -3

const long DSXHANDLENUM_WILDCARD = -1

3.3.2 DSGateway DSX_OBJTYPE object types

Object type variable Object description

OBJTYPE_DOCUMENT Document

OBJTYPE_COLLECTION Collection

OBJTYPE_SERVER Server

OBJTYPE_GATEWAY Gateway

OBJTYPE_CALENDAR Calendar

OBJTYPE_BBOARD Bulletin board

OBJTYPE_URL Uniform Resource Locator

OBJTYPE_BULLETIN Bulletin

OBJTYPE_USER User

OBJTYPE_GROUP Group

OBJTYPE_SAVEDQUERY Saved query

OBJTYPE_EVENT Event

OBJTYPE_UNKNOWN Unknown object

OBJTYPE_SUBSCRIPTION Subscription

OBJTYPE_DOCVERSION Document version

OBJTYPE_RENDITION Document rendition

3–222 DocuShare Windows Client SDK

DSGateway Library Constants

3.3.3 DSX_CMDID Command IDs

Command ID variable Command description

CMDID_UNKNOWN Unknown command

CMDID_LOGIN DocuShare HTTP/XML Login command

CMDID_DIR DocuShare HTTP/XML PROPFIND/Collection

command with depth = 1

CMDID_MKDIR DocuShare HTTP/XML MKCOL or MKRES

command

CMDID_COPY DocuShare HTTP/XML COPY command

CMDID_MOVE DocuShare HTTP/XML MOVE command

CMDID_GETPROPS DocuShare HTTP/XML PROPFIND command

with depth = 0

CMDID_SETPROPS DocuShare HTTP/XML PROPPATCH command

CMDID_LOCK DocuShare HTTP/XML Lock command

CMDID_UNLOCK DocuShare HTTP/XML Unlock command

CMDID_DELETE DocuShare HTTP/XML DELETE command

CMDID_DOWNLOAD DocuShare HTTP/XML GET command

CMDID_CHECKOUT DocuShare HTTP/XML CHECKOUT command

CMDID_UPLOAD DocuShare HTTP/XML ApplyUpload command

CMDID_AUTHUPLOAD DocuShare DS 1.5 Upload command

CMDID_SEARCH DocuShare HTTP/XML Search command

CMDID_HISTORY DocuShare HTTP/XML PROPFIND command for

File property <versions>

CMDID_HTTP_GET HTTP method GET

CMDID_HTTP_HEAD HTTP method HEAD

CMDID_HTTP_PUT HTTP method PUT

CMDID_HTTP_POST HTTP method POST

CMDID_HTTP_DELETE HTTP method DELETE

CMDID_HTTP_LINK HTTP method LINK

CMDID_HTTP_UNLINK HTTP method UNLINK

CMDID_HTTP_OPTION HTTP method OPTION

CMDID_HTTP_PROPFIND HTTP/WEBDAV method PROPFIND

CMDID_HTTP_PROPPATCH HTTP/WEBDAV method PROPPATCH

DocuShare Windows Client SDK 3–223

Constants DSGateway Library

Command ID variable Command description

CMDID_HTTP_MKCOL HTTP/WEBDAV method MKCOL

CMDID_HTTP_MKRES HTTP/WEBDAV method MKRES

CMDID_CUSTOM Custom HTTP method

3.3.4 DSX_STGMEDIUM Storage medium types

Storage Medium variable Storage medium description

STGMEDIUM_UNKNOWN Unspecified medium

STGMEDIUM_FILE File storage

STGMEDIUM_STREAM Stream object (IStream interface)

3.3.5 DSX_DATCOMPR Data compression flags

Data Compression variable Data compression description

DATACOMPR_NONE No compression

DATACOMPR_COMPRESSED Data is compressed

DATACOMPR_EXPANDED Data is expanded (decompressed)

3–224 DocuShare Windows Client SDK

DSGateway Library Submit method

3.4 Submit method

The Submit method is a general method for submitting an HTTP request to a DocuShare or web server.
The method replaces InitiateGet and InitiatePost. The latter two methods are made available for backward
compatibility with existing applications. However, it is recommended to use the Submit method for new
client applications.

To use the Submit method, follow the steps below for sending a request to a server for processing.

1. Build a client request message.

2. Open a gateway.
3. Pass the request to the gateway's Submit method.
4. Parse the server response.
5. Process the response data.

3.4.1 Submit code examples

Build a client request—An HTTP client request is generated using the DSGateway.ClientRequest object.
A ClientRequest object is created using the Visual Basic CreateObject function.

A request message consists of a request line, message header, and message entity body. With
ClientRequest, the request line is formed using ClientRequest.Method and ClientRequest.RequestURI.
The header is built using ClientRequest.Header. The entity body is generated using
ClientRequest.ContentData.

set request = CreateObject("DSGateway.ClientRequest")

request.Method = "POST"
request.RequestURI = "PROPFIND/Collection-10"
request.Header("Depth") = "1"
request.ContentData.DeclareXML
request.ContentData.Text = "<propfind><prop>" & vbCrLf &_
"<displayname/><summary/><handle/><parents/>" & vbCrLf &_
"<memberlength/><getcontentlength/>" & vbCrLf &_
"</prop></propfind>"
The above code generates the HTTP request message shown below.

POST /dscgi/ds.py/PROPFIND/Collection-10 HTTP/1.1

Depth: 1
Host: polaris:443
DocuShare-Version: 3.1
User-Agent: DsAxess/4.1
Accept-Language: en-US
Accept: */*, text/xml
Cookie: AmberUser=gm%fd%7dMt%%1a00443%981%a7%e6%02%105; path=/
Content-Length: 109
Content-Type: text/xml

<?xml version="1.0" ?>

<propfind>

DocuShare Windows Client SDK 3–225

Submit method DSGateway Library

<prop>
<displayname/>
<summary/>
<handle/>
<parents/>
</prop>
</propfind>

The ClientRequest.Cookie needs an AmberUser string in order to authenticate the access to a restricted
DocuShare resource. This may not apply if the gateway is opened from a DSServerMap.Server object and
Server.Logon was invoked successfully. It is because the gateway receives authentication data from the
Server object and stores it in its DSAccessData object. The Submit method internally uses the data and
automatically sends it as the value of a Cookie header field.

Open a gateway—The request message prepared above is sent to the server using
DSGateway.GatewayHandler. GatewayHandler sends a client message and receives a server message
by opening and maintaining an HTTP connection to a DocuShare or web server. GatewayHandler also
provides the ServerResponse property from which applications can retrieve and analyze the response
message the server sent.

If a DSServerMap.Server object is in use, call the Server.Open method to create GatewayHandler. In this
way, GatewayHandler can transparently use the DocuShare server address and other access parameters
as well as the DocuShare user authorization. If it uses CreateObject to create an instance of
GatewayHandler, an application is responsible for making sure GatewayHandler.DSAccessData has the
right DocuShare address, user authentication, and other access parameters before the Submit method is
invoked.

dim server
if SelectServer( server ) then
set gateway = server.Open
...
end if

function SelectServer( selectedServer )

set serverStore = CreateObject("DSServerMap.Store")
serverStore.Load
status = serverStore.DoSelectDialog(0, _
"Select DocuShare Server", _
"", "", 0, 1)
if status <> 0 then
SelectServer = status
exit function
end if
serverStore.Reset
while serverStore.NextPos <> 0
dim nextServer

3–226 DocuShare Windows Client SDK

DSGateway Library Submit method

set nextServer = serverStore.NextItem

if nextServer.IsSelected <> 0 then
set selectedServer = nextServer
SelectServer = selectedServer.Logon
exit function
end if
wend
SelectServer = -1
end function
Pass the request to the gateway's Submit method—The Submit method accepts a ClientRequest
object or an object of its subclass such as SearchRequest.

status = gateway.Submit( request )

A status code of DSAXES_SUCCESS (0) indicates that the request was successfully submitted and
processed by DocuShare. Submit, by default, operates synchronously and does not return until
DocuShare completes the request or until an error occurs.

To submit a request asynchronously, set GatewaySettings.Asynchronous to True. In async mode, Submit

returns immediately after a Windows socket is opened but before a connection to the server is established.

gateway.GatewaySettings.Asynchronous = True
status = gateway.Submit( request )
A DSAXES_SUCCESS status code indicates that the request submission was successfully started. Use
the GatewayHandler.Wait method to pause and check the submission status periodically in a loop.

while DSAXES_INPROG = gateway.Wait(100)

' Do application-specific task while waiting
' for DocuShare to finish processing.
wend
If the status code from Wait is DSAXES_INRPOG, either an attempted connection is in progress or the
server has not completed processing the request. Break out of the loop if the status code is not
DSAXES_INPROG. If the code is DSAXES_SUCCESS, the request was completed; otherwise an error
occurred.

If the status code is DSAXES_E_HTTP, the server has raised an error. Check the value of
GatewayHandler.ServerResponse.HTTPResultCode. This is the error code the server sent. For example,
if the status code is 401, this is a user authentication error that indicates the Submit call was not
accompanied by the proper authentication data. Either the value in ClientRequest.Cookie is incorrect or
missing, or that the user is not authorized to access the requested resource.

Parse the server response—If the status code from Submit is DSAXES_SUCCESS, the server
successfully processed the client request.

For a simple task such as locking a file, checking the status code may be sufficient. Many tasks, however,
require analysis of response data that the server sends. For example, if the request is a PROPFIND for a
Collection object with a depth of one, the server responds by sending XML data regarding objects that
appear in the Collection. The XML data needs to be parsed according to a known schema so that the
application obtains pertinent directory information.

DocuShare Windows Client SDK 3–227

Submit method DSGateway Library

There are two approaches to parsing a server response. One is to use DSClient SDK's built-in parser
services; another is to use an independent XML parser library.

A. Built-in parser methods

The ContentData object of the DSClient gateway comes with several methods dedicated to
parsing XML data that DocuShare generates. Using these methods, you can convert DocuShare
XML data into standard DSClient automation objects (EnumObj, ItemObj, ItemProperties and
ItemProperty) without knowing that the DocuShare response was in XML. There is no prerequisite
to using the parsing methods. Although it is helpful, you are not required to have an understanding
of general XML syntax. You are not required to understand the schemata that DocuShare uses to
generate an XML response.
Continuing with the PROPFIND example above, create a script that transforms the Collection-10
response into an EnumObj enumerator so that you can use properties of ItemObj to directly
access the properties of the queried items within the collection.
set cd = gateway.ServerResponse.ContentData
if cd.ParseDirectory then
set enumObj = cd.ItemDescriptorArray.Enumerator
enumObj.Reset
while enumObj.NextPos <> 0
set itemObj = enumObj.NextItem
MsgBox itemObj.Summary, , itemObj.Title
wend
end if
The above example calls the ContentData.ParseDirectory method to convert the PROPFIND
response data into an enumerator object. It uses the enumerator to walk through the items of the
collection and displays the summary of each item.
Most applications perform much more complex operations than displaying summary text. Once the
ItemObj automation object is obtained, you have direct access to properties of the DocuShare
object which the ItemObj encapsulates. In addition, you gain access to all parents, all children, and
other ancestor DocuShare objects of the item. This makes it possible to perform nested and other
complex tasks that go beyond formatting and displaying queried results.
The example used the ParseDirectory method because the request that the example sent to
DocuShare was a PROPFIND/Collection with a depth of 1, which was a directory query.
ContentData implements other XML parsing methods. The use of a method depends on the
request. The automation object that the parser generates also depends on the request.

HTTP/XML Request Method Automation Object

PROPFIND/Collection with ParseDirectory EnumObj

depth=1

PROPFIND/File for <versions> ParseVersionHistory EnumObj for file versions

PROPFIND/[any DS object ParseProperties ItemProperties for object’s

class] with depth=0 properties

SEARCH ParseQueryResults EnumObj for found DS objects

3–228 DocuShare Windows Client SDK

DSGateway Library Submit method

HTTP/XML Request Method Automation Object

PROPFIND/Server for ParseSchema EnumObj for object

<schemata> class-dependent schema items

ApplyUpload for compound file ParseUploadResult EnumObj for file renditions and
content elements

B. External XML parser-based approach

One technique that is based on the independent parser approach is to feed an external XML
parser library with the raw text/xml data from the server. The data is kept in the ContentData.Text
property.
set xmlParser = CreateObject([ProgId of external XML parser])
' assign the text/xml data from the server to the XML parser
... = gateway.ServerResponse.ContentData.Text
You need to consult the documentation of the external parser library on how to assign the XML
response data and control the parsing process.
Another technique is to use the object model of the XMLDOMDocument implementation of the
Microsoft XML parser library (MSXML). ContentData of the client gateway exposes the XMLDOM
property. Applications can use this property to readily obtain an XMLDOMDocument instance that
already encapsulates the DocuShare response data. The XML data can be analyzed and
information that are interesting to the applications can be extracted using standard methods and
properties of XMLDOMDocument.
For example, suppose that the earlier Submit call retrieved the XML response below; consider a
template-based generation of a directory view in HTML.
HTTP/1.1 207 Multi-Status
Server: Microsoft-IIS/5.0
Date: Sat, 21 Jun 2003 19:48:54 GMT
Connection: close
DocuShare-Version: 2.2
Content-type: text/xml

<?xml version="1.0" encoding="UTF-8" ?>

<multistatus>
<response>
<href>https://polaris/Collection-10</href>
<propstat>
<prop>
<displayname>Very First Collection</displayname>
<summary>A first top-level collection with which to get started.
</summary>
<handle>
<dsref handle="Collection-10">

DocuShare Windows Client SDK 3–229

Submit method DSGateway Library

<displayname>Very First Collection</displayname>

</dsref>
</handle>
<parents/>
<memberlength>66</memberlength>
</prop>
<status>HTTP/1.1 200 OK</status>
</propstat>
<propstat>
<prop>
<getcontentlength/>
</prop>
<status>HTTP/1.1 402 Not Found</status>
</propstat>
... [abreviated] ...
</response>
</multistatus>
The above XML data contain descriptions of the items within the queried collection. The data is
buffered in ServerResponse.ContentData. ContentData.XMLDOM exposes the
XMLDOMDocument interface of the XML data. To generate an HTML directory view, create an
XSL template and apply it to the XML data through DOM's transformNode method. Here is a script
that performs the transformation.
set xml = gateway.ServerResponse.ContentData.XMLDOM
set xsl = CreateObject("Microsoft.XMLDOM")
xsl.load "templates/collection.xsl"
html = xml.transformNode(xsl)
The XSL code is loaded from file collection.xsl. As shown below, the code enumerates through
the queried files and sub-collections described in the XML response data and displays the
DocuShare handle, title, size and last modification date of each item in an easy-to-read tabular
format.
<?xml version="1.0"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/TR/WD-xsl">
<xsl:template match="/">
<HTML>
<HEAD>
<TITLE>
<xsl:value-of select="multistatus/response/propstat/prop/
displayname"/>
</TITLE>
<STYLE>

3–230 DocuShare Windows Client SDK

DSGateway Library Submit method

.headerRow { background-color:bisque;font-weight:bold;font-size:12 }
.itemRow { border-top:thin solid black;font-size:12 }
</STYLE>
</HEAD>
<BODY>
<TABLE BORDER="0" WIDTH="100%">
<TR CLASS="headerRow">
<TD>Handle</TD>
<TD>Title</TD>
<TD>Size</TD>
<TD>Modified</TD>
</TR>
<xsl:for-each select="multistatus/response">
<xsl:if expr="(childNumber(this)) > 1">
<xsl:for-each select="propstat">
<xsl:if test=".[status='HTTP/1.1 200 OK']">
<xsl:for-each select="prop">
<TR CLASS="itemRow">
<TD>
<xsl:for-each select="handle/dsref">
<xsl:value-of select="@handle"/>
</xsl:for-each>
</TD>
<TD>
<xsl:value-of select="displayname"/>
</TD>
<TD>
<xsl:choose>
<xsl:when test="getcontentlength">
<xsl:value-of select="getcontentlength"/> bytes
</xsl:when>
<xsl:otherwise>
<xsl:value-of select="memberlength"/> items
</xsl:otherwise>
</xsl:choose>
</TD>
<TD>
<xsl:value-of select="getlastmodified"/>

DocuShare Windows Client SDK 3–231

Submit method DSGateway Library

</TD>
</TR>
</xsl:for-each>
</xsl:if>
</xsl:for-each>
</xsl:if>
</xsl:for-each>
</TABLE>
</BODY>
</HTML>
</xsl:template>
</xsl:stylesheet>
The XSL transformation yeilds the following HTML code:
<HTML>
<HEAD>
<TITLE>
Very First Collection
</TITLE>
<STYLE>
.headerRow { background-color:bisque;font-weight:bold;font-size:12 }
.itemRow { border-top:thin solid black;font-size:12 }
</STYLE>
</HEAD>
<BODY>
<TABLE BORDER="0" WIDTH="100%">
<TR CLASS="headerRow">
<TD>Handle</TD>
<TD>Title</TD>
<TD>Size</TD>
<TD>Modified</TD>
</TR>
<TR CLASS="itemRow">
<TD>
File-3897
</TD>
<TD>
<A HREF="">
NEWMAILF.WAV

3–232 DocuShare Windows Client SDK

DSGateway Library Submit method

</A>
</TD>
<TD>
10409 bytes
</TD>
<TD>
Wed, 06 Mar 2002 07:07:48 GMT
</TD>
</TR>
... [abreviated] ...
</TABLE>
</BODY>
</HTML>
Server-based ASP applications that need to programmatically generate custom collection views
can utilize the above ContentData.XMLDOM-based technique.

DocuShare Windows Client SDK 3–233

Non-file object creation DSGateway Library

3.5 Non-file object creation

It is recommended to use the DSCreate method of the DSITEMENUMLib.IItemObj interface to create an
object in DocuShare. DSCreate assigns an object type identifier to an ItemObj instance created from a
parent ItemObj.

set parentObj = server.CreateObject("Calendar-123")

set newObj = parentObj.CreateObject("Event")
... ' Initialize event properties before calling DSCreate...
newObj.DSCreate
Refer to DSCreate on page 5–18 for details.

If you need to go directly to the gateway, you can use GatewayHandler's InitiateCreateObject method. For
maximum flexibility and control, consider using the Submit method. InitiateCreateObject is a general
method for creating any type of non-file object on a DocuShare server. This method hides DocuShare
HTTP/XML details that you would otherwise need to know if the Submit method was used. Follow the
steps outlined below.

1. Create an ItemObj instance and use it to specify the type of object to create in Docushare.
2. Specify DocuShare properties for the object. This is done by assigning property values to the
ItemObj properties that correspond to the DocuShare properties. If ItemObj does not define an
explicit property that maps to a DocuShare property, ItemObj.CustomProp property can be used.
3. Obtain DSAXES_PROPID constants that identify the specified DocuShare properties.
4. Open a gateway to the DocuShare server. Either pass to it a valid user credential (via
DSAccessData.AuthToken) or run a user login (via GatewayHandler.InitiateUserAuth).
5. Call InitiateCreateObject to submit the creation request to the server.
6. After the server processes the request, GatewayHandler.DSObjectHandle contains the
DocuShare handle of the created object.
The script below uses InitiateCreateObject to create an Event object.

set itemObj = CreateObject("DSITEMENUMLib.ItemObj")

itemObj.Handle = "Event"
itemObj.ParentHandle = "Calendar-123"
itemObj.Title = "Team Meeting"
itemObj.Description = "Let's go over the progress we've made."
itemObj.CustomProp("year") = 2003
itemObj.CustomProp("month") = 8
itemObj.CustomProp("day") = 1
itemObj.CustomProp("start") = 10*60 ' in minutes from midnight
itemObj.CustomProp("end") = 11*60
set gateway = CreateObject("DSGateway.GatewayHandler)
gateway.DSAccessData.DocuShareAddress = "http://www.xyz.com/docushare"
gateway.DSAccessData.AuthToken = "AmberUser=..."
status = gateway.InitiateCreateObject(_

3–234 DocuShare Windows Client SDK

DSGateway Library Non-file object creation

DSAXES_PROPID_CORE_TITLE or _
DSAXES_PROPID_CORE_DESCRIPTION or _
DSAXES_PROPID_CORE_CUSTOM, _
0, _
itemObj)
if status = 0 then
status = gateway.AwaitCompletion
if status = 0 then
itemObj.Handle = gateway.DSObjectHandle
MsgBox "Generated event handle: " & itemObj.Handle
end if
end if
Refer to the DocuShare object properties that are required for creating an object. Use
ItemObj.CustomProp to assign a value to a property not defined on the IItemObj interface. Make sure the
DSAXES_PROPID_CORE_CUSTOM flag is specified when calling InitiateCreateObject.

To modify one or more properties of an existing non-file object, use GatewayHandler.SetProps. An ItemObj
object passed to SetProps must have its handle property set to the DocuShare handle for the DocuShare
object.

Gateway methods can be used to perform file management type operations, although it may be more
straightforward to use IItemObj interface methods. For deleting, moving, and copying a DocuShare object
of any object type, ItemObj uses these methods: DSDelete, DSMove, and DSCopy.

To delete a non-file object directly from GatewayHandler, use the InitiateDelete method. The
GatewayHandler.DSObjectHandle property may be used to specify the DocuShare handle for the object.
Make sure to specify DSXHANDLENUM_DSOBJECTHANDLE as the value of the handle number
(parameter nDsHandle) for the object that InitiateDelete will operate on. The type number parameter
(nObjType) is not used; set it to zero.

gateway.DSObjectHandle = "Bulletin-456"
status = gateway.InitiateDelete(0, DSXHANDLENUM_DSOBJECTHANDLE, _
"", "", "")
InitiateMove is used to move a non-file object within a DocuShare server. Follow the same procedure as
for InitiateDelete to move a DocuShare non-file object. The non-file object may appear in a non-Collection
container object (source container), and the new container to which the object is being moved may be a
non-Collection object as well. To specify the correct source and destination container objects to
InitiateMove, set the handle number parameters (nNewParentHandle and nOldParentHandle) of the
source, destination, or both containers to the special container handle value,
DSXHANDLENUM_SERVERADDRHASHANDLE and include the DocuShare container handles in the
server address parameter, pszServerUrl.

gateway.DSObjectHandle = "myObject-123"
status = gateway.InitiateMove(0, _
DSXHANDLENUM_DSOBJECTHANDLE, _
DSXHANDLENUM_SERVERADDRHASHANDLE, _
DSXHANDLENUM_SERVERADDRHASHANDLE, _

DocuShare Windows Client SDK 3–235

Non-file object creation DSGateway Library

"http://ds.xyz/com/?SOURCE=myContainer-45?DESTINATION=myContainer-
54", _
"AmberUser=...", _
"")
Notice that the fifth parameter, pszServerUrl, is set to a string containing the handles of both source and
destination containers. The source handle is given in the SOURCE=myContainer-45 assignment. The
destination handle is in the DESTINATION=myContainer-54 assignment. Both assignments are delimited
by question marks.

If the gateway was opened from a Server object, the gateway will have the same DocuShare access
parameters as the server URL. Therefore, the pszServerUrl parameter should only contain the source and
destination handles.

InitiateCopy is used to copy a non-file object within a DocuShare server. To copy a non-file object to a
container object, the method requires the handle for the destination container object. Use the same steps
as InitiateMove for specifying a non-file target object and destination container.

gateway.DSObjectHandle = "myObject-123"
status = gateway.InitiateCopy(0, _
DSXHANDLENUM_DSOBJECTHANDLE, _
DSXHANDLENUM_SERVERADDRHASHANDLE, _
"http://ds.xyz/com/?DESTINATION=myContainer-54", _
"AmberUser=...", _
"")

3–236 DocuShare Windows Client SDK

DSGateway Library Compound document support

3.6 Compound document support

DocuShare 3.0, or greater, supports creation of a Document object class. A Document object encapsulates
a versionable compound file storage. A compound file consists of one or more file versions. Each file
version contains one or more elements of presentation data, called Rendition objects and Content
elements; both are referenced from within the presentation data. A Document object contains one or more
Version objects, of which each contains one or more Rendition objects. Each Rendition object contains
zero or more Content elements.

3.6.1 Advantages of a compound document

Using the Outlook Client as an example, the Client uses DocuShare compound document support to store
two renditions of a mail note as one DocuShare Document object. It also stores any attachments the mail
note may contain in the same object.

The advantages of compound documents are in the following examples:

• Since all elements (the two Renditions and attachment content elements) of the mail note (a
Document object) are contained in a single storage, they stay together. It takes only a single file
management action to move, copy, or delete all the elements. All elements of the file are subject to
the same permission settings. Also, any reference one element makes to another within the file,
stays valid.
• Versioning affects all elements of a file. Uploading a new version creates a Version object with new
renditions plus new content elements. The Rendition and content elements of the previous version
are automatically preserved.
Refer to the DocuShare HTTP/XML Guide for conceptual and structural description of the Document class.
The DS Windows Client SDK uses the item type identifier File, to specify a Document object. The DS
Windows Client SDK continues to use the item type identifier File, to denote a Document object. The SDK
libraries also recognizes the Document type identifier if one is given.

3.6.2 Effect on a Windows file uploaded to DocuShare

The effect depends on how you are presenting the file contents or the data structure of the file. If you want
to use DocuShare as a dumb file storage, compound document storage gives no advantage over flat
document storage.

For example, if you want to show the file contents in a web browser that is without HTML presentation data
and foreign to a generic browser, compound storage becomes a necessity. With DocuShare's compound
storage support, you can proceed to generate an HTML view and upload it as well as the file's original
data. A web browser will be able to use this HTML rendition to show the foreign file's content to a general
audience. To be able to generate an HTML view, either you have detailed knowledge of how the file is
structured to generate the rendition manually, or have an external tool generate the view.

For another example, a file that contains references to external files. With flat storage, you have to upload
the main and external files as separate files and replace the contained references with URLs assigned to
the files after uploading. Depending on the file, such reference adjustments may not be possible at all. With
DocuShare compound storage, you can upload the external files as content elements of the main file. As
long as they are relative to the main file, the internal references do not need adjustment and will continue
to work.

DocuShare Windows Client SDK 3–237

Compound document support DSGateway Library

3.6.3 Uploading a compound document

This section explains how to upload files as a compound file and how to specify and download an element
of a compound file.

The Upload method on the GatewayHandler interface can be used to upload a compound document to a
DocuShare server.

In this example, a file with a proprietry data format (proposal1.bin) and an HTML rendition of the file
(proposal1.htm) are uploaded as a single compound document.

set fileObj = CreateObject("DSITEMENUMLib.ItemObj")

fileObj.Title = "First proposal"
fileObj.PreferredRendition.Name = "c:\team\proposal1.htm"
fileObj.AlternateRendition.Name = "c:\team\proposal1.bin"
status = gateway.Upload( DSAXES_PROPID_CORE_TITLE, 0, fileObj, "" )
This example uses ItemObj's built-in support for a binary rendition scheme. The HTML rendition was
stored as the preferred rendition while the binary rendition was stored as the alternate rendition.

In the example below, if more than a couple of renditions are stored, use ItemObj.EnumObjects with the
DSCONTF_RENDITION selection flag. The method returns an enumerator with which you can create as
many rendition objects as needed.

set fileObj = CreateObject("DSITEMENUMLib.ItemObj")

fileObj.Title = "Second proposal"
set enumObj = fileObj.EnumObjects(DSCONTF_RENDITION)
set rend1 = enumObj.NewItem
rend1.Name = "c:\team\proposal2.htm"
set rend2 = enumObj.NewItem
rend2.Name = "c:\team\proposal2.bin"
set rend3 = enumObj.NewItem
rend3.Name = "c:\team\proposal2.jpg"
status = gateway.Upload( DSAXES_PROPID_CORE_TITLE, 0, fileObj, "" )

3.6.3.1 Storing content elements

Suppose there is an HTML page that contain hyperlinks to files and you want to store the page with the
linked files together as a single compound document. You can use the DSCONTF_ATTACH enumerator
object from ItemObj and attach the link files as attachments to the HTML file. Here is an example.

set fileObj = CreateObject("DSITEMENUMLib.ItemObj")

fileObj.Title = "..."
fileObj.Name = "c:\data\main.htm"
set enumObj = fileObj.EnumObjects(DSCONTF_ATTACH)
set attach1 = enumObj.NewItem
attach1.Name = "c:\data\pict1.jpg"
set attach2 = enumObj.NewItem

3–238 DocuShare Windows Client SDK

DSGateway Library Compound document support

attach2.Name = "c:\data\pict2.gif"
set attach3 = enumObj.NewItem
attach3.Name = "c:\data\script.vbs"
status = gateway.Upload( DSAXES_PROPID_CORE_TITLE, 0, fileObj, "" )
This example creates an HTML rendition as the one and only rendition and stores the hyperlinked image
and script files as content elements of the rendition.

It is also possible to create multiple renditions and assign attachments to one or more of the renditions. To
do so, derive an attachment enumerator from a Rendition object instead of the top-level file ItemObj object.

Regarding file handles, DocuShare 5 assigns a Document handle to an uploaded compound file. The
current version of DS Windows Client SDK, uses the File identifier instead. Therefore, Document-123 is
regarded as File-123 by DSClient libraries. SDK functions that take handles as arguments also accept
handles in the form, Document-n, as valid handles.

An uploaded compound file handle is stored in the ItemObj object that is passed to the
GatewayHandler.Upload method. To retrieve the document handle, use the Handle property on the
principle ItemObj object. DocuShare assigns a unique handle to a rendition as well. This handle is in the
form, Rendition-n. You can use the Rendition handle to access the rendition data directly, such as
PROPFIND query. Rendition handles generated for uploaded renditions are stored in the rendition ItemObj
objects. In one of the earlier examples, Rendition handles are retrieved by reading the values of
rend1.Handle, rend2.Handle, and rend3.Handle. Refer to the DocuShare HTTP/XML Guide on Rendition
properties that can be queried or modified.

As mentioned earlier, a document stored in DocuShare is assigned a DocuShare handle in the form,
Document-n, where n is a positive integer. The document is accessible at a URL in the form:

[DocuShare home]/Get/Document-n

If DocuShare is at http://www.xyz.com/dsweb/ and the document handle is Document-123, the URL for
retrieving the document's content data is:

http://www.xyz.com/dsweb/Get/Document-123

The HTML rendition is accessible at URL:

http://www.xyz.com/dsweb/Get/Document-123/html

Note that the trailing component of the URL, html, is the rendition specifier. It specifies the content type
(MIME type) of the rendition object. This part of the URL depends on the rendition you upload. If you need
to control what DocuShare generates for this part of the URL of a document, you should explicitly specify a
MIME type when uploading the document. You can do so by assigning the MIME type to the MimeType
property on a rendition ItemObj object.

If a content element named example.jpg was stored with the HTML rendition, the element can be found at
the URL:

http://www.xyz.com/dsweb/Get/Document-123/html/example.jpg

DocuShare Windows Client SDK 3–239

Compound document support DSGateway Library

The above URL examples regard the latest or preferred document version. If you need to specify a
different version, you must include a version specifier in the URL. To access an HTML rendition of version
m, use a URL such as:

http://.../dsweb/Get/Document-n/m/html

A URL for a compound element is available from the URL property of an ItemObj object that represents the
element after a successful upload either through GatewayHandler.Upload or query through
GatewayHandler.GetProps.

The above discussion on URLs assumed that the file had:

• a compound structure
• multiple renditions
• attachments
Before you can find URLs for file elements, you need to know if the file or the latest version has more than
one element—a rendition. For example, you did an OpenCollection call and obtained a directory of files. If
the files are unfamiliar, how do you know which files have multiple renditions and have attachments?

There is no fast solution. DocuShare does not expose a pre-defined property that describes structural
aspects of a file. So, a call to OpenCollection or a Submit call for PROPFIND does not yield useful
information as far as which files have more than one rendition element. It is up to the client application to
figure this out, such as making a GetProps call on each Version object a File object contains. As far as
finding contained renditions is concerned, this provides the only structural information.

Although it does not provide a "compoundedness" property, DocuShare does, however, provide a property
exclusively used by client applications. A client application can use this property to store structural
information with a file it uploads. The application can later look for this information and make the necessary
determinations. The special property DocuShare 5 defines for client use is a hidden property of data type
text, called client_data. A client application can set this property to a string defining the compound
attributes that describe the uploaded file.

By default, GatewayHandler's OpenCollection or OpenContainer retrieves the client_data property. The

value is accessible using ItemObj.CustomProp by setting the property name to client_data. A client
application can scan the compound files for the structural information set in client_data.

The ItemObj provides the ClientProp property for accessing parts of the value stored in client_data.
ClientProp allows multiple applications to safely inspect pieces of information. For example,
application-defined file attributes that are stored in client_data. It also allows one application to safely
update the existing value of client_data without overwriting client_data elements that were written by
another application. Because of this, developers writing client applications are encouraged to use
ItemObj.ClientProp to store data in client_data. Refer to ClientProp on page 5–69 for more details.

DocuShare Windows Client and DocuShare Outlook Client both use client_data to store compound file
attributes. File management operations that these applications perform, depend on these attributes.
Therefore, integrity of client_data is important. To maintain client_data, these applications use
ItemObj.ClientProp to get or set client_data values. There are a few important pieces of information
regarding aspects of a compound file which the two applications store and share through the ClientProp
interface. These are listed below.

3–240 DocuShare Windows Client SDK

DSGateway Library Compound document support

ClientProp Name Purpose

DSClientSourceObject Identifies alternate rendition

DSClientAttachObject Identifies attachments

If your application sees a non-empty value for any of the above ClientProp attributes, it can assume the file
has more than one data element. To automatically generate these DSClient attributes for an uploaded
compound file, use ItemObj.DSUpload.

3.6.4 Downloading a compound document

The GatewayHandler.Download method can be used to download an element of a compound file.

To download a rendition:

1. Create an ItemObj instance.

2. Assign the rendition's handle to its Handle property.
3. Pass it together with a file system pathname to GatewayHandler.Download. The gateway
performs an HTTP/XML GET and stores a copy of the rendition at the specified path.
set rendObj = CreateObject("DSITEMENUMLib.ItemObj")
rendObj.Handle = "Rendition-123"
status = gateway.Download( 0, rendObj, "c:\temp\rend123.txt" )
To download a content element of a rendition:

1. Create an ItemObj instance for the File object that contains the content element.
2. Derive a ContElem child object from the File ItemObj object.
3. Assign the content element’s name to its Name property.
4. Pass it together with the flag, DOWNLOADBYNAME and the file system pathname to
GatewayHandler.Download. The gateway performs an HTTP GET and stores a copy of the
content element in the specified directory.
set fileObj = collection.CreateObject( "File-123" )
set contObj = fileObj.CreateObject( "ContElem" )
contObj.Name = "picture.jpg"
status = gateway.Download( DSAXES_FLAG_DOWNLOADBYNAME, contObj, "c:\temp\" &
contObj.Name )

DocuShare Windows Client SDK 3–241

Compound document support DSGateway Library

3.6.5 File Management Tasks

InitiateCopy, InitiateMove and InitiateDelete can be used to copy, move, and delete a compound document
within a DocuShare server.

DSITEMENUMLib.ItemObj uses the compound document support of GatewayHandler to enable its high
level compound document support. You can use it to implement your compound document needs. The
ItemObj interface allows more object-oriented design and implementation than does the GatewayHandler
interface.

3–242 DocuShare Windows Client SDK

 DSServerMap Library
This chapter contains the following:

• Object model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–2

• Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4–3

DocuShare Windows Client SDK 4–1

Object model DSServerMap Library

4.1 Object model

DSServerMap Method or property used to derive

an object precedes the name of
the object in italics.
Store

NextItem
Server

Browser

Wizard

*creates a standalone server object

Server*

ShortcutStore
Store

CustomProps
PropCollection

NextItem
CustomProp

CheckinServiceManager

4–2 DocuShare Windows Client SDK

DSServerMap Library Objects

4.2 Objects
4.2.1 Store
List of Store methods and properties.

Methods Properties

Add BaseRegistryKey

CanAdd ISProtected

Clone NextItem

Close NextPos

DoSelectDialog Options

Find SelectDialogOption

Load

Protect

Remove

Reset

Save

Unprotect

DocuShare Windows Client SDK 4–3

Objects DSServerMap Library

4.2.1.1 Store methods

This section contains the Store method definitions.

Add

VB Add(pServer As Server) As Long

C++ long Add( IDispatch* pServer );

The Add method is used to add a server object to a Store object.

Parameters
pServer—an object of type Server.

Return value

Value Description

SVRMAP_RESULT_SUCCESS The Add was successful.

SVRMAP_NO_MORE_ITEMS The maximum number of servers has been

exceeded; no more servers can be added. A Store
object can only contain a maximum of 16 servers.

SVRMAP_RESULT_AUTHDBLOCKED The storage database is locked by another

instance of Store, or the current instance was not
protected before adding a Server object.

Remarks
The Add method does not save Server object connection information to permanent storage. It only adds
the connection to the current Store object in memory. To save the Server object connection information, a
Store.Save must be invoked. See Save on page 4–15 for details.

4–4 DocuShare Windows Client SDK

DSServerMap Library Objects

CanAdd

VB CanAdd(pServer As Server, IFlags As Long) As Long

C++ long CanAdd(LPDISPATCH pServer, long lFlags);

The CanAdd method is utilized to validate Server connection information. Server objects that fail this
method cannot be added to a Store object.

Parameters

Parameter Description

pServer An object of type Server.

SVRMAP_CANADDFLAG_SHOWERROR Causes CanAdd method to display an Error dialog

box.

Return value

Value Description

SVRMAP_RESULT_SUCCESS The method was successful.

SVRMAP_RESULT_TITLETOOLONG The Server object Name property is too long. The

maximum length is 79 characters.

SVRMAP_RESULT_TITLETOOSHORT The Server object Name property is too short. The

minimum length is 4 characters.

SVRMAP_RESULT_WIPTOOLONG The Server object WIPFolder property is too long.

The maximum length is 79 characters.

SVRMAP_RESULT_WIPTOOSHORT The Server object WIPFolder property is too short.

The minimum length is 4 characters.

SVRMAP_RESULT_TITLEINUSE The Server object Name property value is currently

used by another Server object in the Store.

SVRMAP_RESULT_WIPINUSE The Server object WIPFolder property value is

currently used by another Server object in the
Store.

SVRMAP_RESULT_WIPSYNTAXERROR The Server object WIPFolder property is not a valid

folder string.

DocuShare Windows Client SDK 4–5

Objects DSServerMap Library

Clone

VB Clone() as Object Store

C++ IDispatch* Clone();

The Clone method creates a clone of the current Store object.

Close

VB Close() As Long

C++ long Close();

The Close method is utilized to logoff and store any server that is currently managed by the Store object.

Parameters
None

Return value

Value Description

SVRMAP_RESULT_SUCCESS The method was successful.

SVRMAP_RESULT_NOCHANGE The method was successful. There were no

changes to the Store object state. This result is
typical for Store objects that were designed as
standalone with the flag
SVRMAP_STOREOPT_STANDALONE in the
Options property.
This result is also for Store objects that does not
contain Server objects.

SVRMAP_RESULT_UNKNOWNERROR The method failed due to an unknown error.

SVRMAP_RESULT_MAPLOADFAIL The method failed. This return occurs if there is an

error in loading the servers saved in the
BaseRegistryKey.

Remarks
The Close method is only valid when a Store object is utilized to manage a set of Server objects. Calling
this method will logoff and save any servers to the current BaseRegistryKey. If the Store.Options property
is flagged with SVRMAP_STOREOPT_STANDALONE, this method has no effect.

Calling the Close method will logoff all servers stored in the BaseRegistryKey location. Logoff of servers
will occur even if a Store.Load method has not been called, as Close automatically attempts to Load the
Store and then execute a logoff for each Server object found.

4–6 DocuShare Windows Client SDK

DSServerMap Library Objects

DoSelectDialog

VB DoSelectDialog(lWnd As Long, strTitle As String, strDescript As String,

strHelpFile As String, lHelpIndex As Long, IFlags As Long) As Long

C++ long DoSelectDialog(long lWnd, LPCTSTR strTitle, LPCTSTR strDescript,

LPCTSTR strHelpFile, long lHelpIndex, long lFlags);

The DoSelectDialog method sets the IsSelected parameter (IsSelected on page 4–64) to True for each
server item selected.

Parameters

Parameter Description

lWnd For Visual Basic applications this parameter is

always set to 0.
C/C++ users should pass the handle of the
application window that acts as the parent of the
DoSelect Dialog.

strTitle A string that is displayed on the dialog title bar.

strDescript A string that describes the purpose of the

selection.

strHelpFile The file path to a help file.

lHelpIndex A help index located within the help file.

SVRMAP_SELDLGFLAG_SINGLESEL Restricts the user to selecting one server only.

SVRMAP_SELDLGFLAG_SHOWPRESEL Highlight previously selected servers.

Return value

Value Description

SVRMAP_RESULT_SUCCESS The method was successful.

SVRMAP_RESULT_CANCEL The dialog returned a user Cancel notification.

SVRMAP_RESULT_NOMAPS The Store does not contain Server objects.

Remarks
The following example selects a Server object from a Store object. It takes a Server object as an input
parameter and then sets that object to the selected server.

' This function is used to make a single server selection

Function SelectServer(ByRef objServer)
' First we load the Store object from which
' to make our server selection

DocuShare Windows Client SDK 4–7

Objects DSServerMap Library

Dim objStore
Set objStore = CreateObject("DsServerMap.Store")
Dim lStatus
lStatus = objStore.Load
' Let's make sure we can continue
If SVRMAP_RESULT_SUCCESS = lStatus Then
' Now we can select a server
Dim strTitle, strDesc
strTitle = "Select and Open"
strDesc = "Select a server on which you wish to logon to."
Dim lFlag
lFlag = SVRMAP_SELDLGFLAG_SINGLESEL ' Allow only a single selection
lStatus = objStore.DoSelectDialog(0, strTitle, strDesc, "", 0, lFlag)
If SVRMAP_RESULT_SUCCESS = lStatus Then
'Ok, now iterate through the servers
'and find the selected one
objStore.Reset ' Set to first server
Dim TempServer
While 0 <> objStore.NextPos
Set TempServer = objStore.NextItem
If TempServer.IsSelected = 1 Then
Set objServer = TempServer 'Return the selected server
SelectServer = True
Exit Function
End If
Wend
MsgBox "Selected server never found"
SelectServer = False
Exit Function
End If
End If
MsgBox "Error in SelectServer."
SelectServer = False
End Function

4–8 DocuShare Windows Client SDK

DSServerMap Library Objects

Find

VB Find(vCriteria, flags As Long) As Server

C++ LPDISPATCH Find(VARIANT* vCriteria, long flags);

The Find method searches a Store object and returns the first Server object that meets the criteria.

Parameters

Parameter Description

vCriteria vCriteria is dependent on the flag that is selected.

See individual flags setting for more information.

flags Only a single COMPARE flag may be used to set

the search criteria. Any COMPARE flag can be
ORed with SVRMAP_FIND_NOBLANKSVR.

Flags Description

SVRMAP_COMPARE_NAME Performs the search against the Server object

names. The criteria is a string type.

SVRMAP_COMPARE_DSADDR Performs the search against the Server object

URL addresses. The criteria value is a string type.

SVRMAP_COMPARE_FOLDERHANDLE Performs the search against the Server object

folder handles and those Server objects that are
Collection Maps. The criteria is long type.

SVRMAP_COMPARE_FOLDERTYPE Performs the search against the Server object that

is a Collection Map. The folder type can be passed
to the criteria as a long type.

SVRMAP_COMPARE_INSTANCEID Performs the search against the InstanceId

assigned to the Server object. The criteria is long
type.

SVRMAP_FIND_NOBLANKSVR This flag permits the Find method from returning a

NULL Server object.
If this flag is set and a Server object containing the
specified criteria is not found, then the return value
is NULL (or Nothing in VB).
If the flag is not set, a new Server object is
returned, but the Server object will be empty.

Return value
This function returns an IDispatch pointer to a created Server object.

DocuShare Windows Client SDK 4–9

Objects DSServerMap Library

Load

VB Load() As Long

C++ long Load();

The Load method is used to initialize a Store object with the server connection information stored in the
registry database.

Parameters
None

Return value

Value Description

SVRMAP_RESULT_SUCCESS The method was successful.

SVRMAP_RESULT_NOCHANGE The method was successful. There were no

changes to the Store object state. This result is
typical of a Store object flagged with
SVRMAP_STOREOPT_STANDALONE.

SVRMAP_RESULT_UNKNOWNERROR The method failed due to an unknown error.

SVRMAP_RESULT_COMCREATEFAIL The method failed. Load was unable to create a

successful COM interface to the necessary
resources.

SVRMAP_RESULT_MAPREADFAIL The method failed. This result occurs if there is an

error in loading the servers saved in
BaseRegistryKey.

Remarks
' Load a non stand alone Store object
Function LoadStore(ByRef objStore As Object, ByRef BaseRegKey As String) As
Boolean
' Set the registry key
If BaseRegKey <> "" Then ' Else use default reg key
objStore.BaseRegistryKey = BaseRegKey
End If
' Perform Load operation
Dim lStatus As Long
lStatus = objStore.Load()
' Test for success

4–10 DocuShare Windows Client SDK

DSServerMap Library Objects

If lStatus = SVRMAP_RESULT_SUCCESS Then

LoadStore = True
Else
LoadStore = False
End If
End Function

DocuShare Windows Client SDK 4–11

Objects DSServerMap Library

Protect

VB Protect() As Long

C++ long Protect();

The Protect method is used to ensure that only a single Store object can attempt to write server information
into the permanent server information storage.

Parameters
None

Return value

Value Description

SVRMAP_RESULT_SUCCESS The method was successful.

SVRMAP_RESULT_NOCHANGE The method was successful. There were no

changes to the Store object state. This result is
typical of a Store object flagged with
SVRMAP_STOREOPT_STANDALONE, or the
Store is protected by this application.

SVRMAP_RESULT_AUTHDBERROR Access to the Store database is denied due to an

unknown database error.

SVRMAP_RESULT_AUTHDBLOCKED The storage database is locked by another

instance of Store, or the current instance was not
Protected before adding a Server object.

Remarks
See Save on page 4–15 for details.

4–12 DocuShare Windows Client SDK

DSServerMap Library Objects

Remove

VB Remove(pServer As Server) As Long

C++ long Remove(LPDISPATCH pServer);

The Remove method is used to delete a server object from a Store object.

Parameters
pServer—an object of type Server.

Return value

Value Description

SVRMAP_RESULT_SUCCESS The method was successful.

SVRMAP_NOT_FOUND The Server object to be removed was not found.

SVRMAP_RESULT_AUTHDBLOCKED The Store is not protected, or it is currently

protected by another process.

SVRMAP_RESULT_NOTLOGGEDOUT The Server object is not logged out. This error

occurs only if the Store object
SVRMAP_STOREOPT_LIMITREMOVE option
was set.

Remarks
' Remove a Server object from a Store
' and then save the Store
Function PermRemove(ByRef objStore As Object, ByRef objServer As Object) As
Boolean
' Ensure that the objStore is not currently protected
If objStore.IsProtected = 0 Then
' objStore is not protected
objStore.Protect ' Protect the Store for add and save
objStore.Remove (objServer)
objStore.Save
objStore.Unprotect
PermRemove = True
Else
' objStore is protected
PermRemove = False
End If
End Function

DocuShare Windows Client SDK 4–13

Objects DSServerMap Library

Reset

VB Reset() As Long

C++ long Reset();

The Reset method is used to move the iteration pointer to the first Server object in the object Store.

Parameters
None

Return value

Value Description

SVRMAP_RESULT_SUCCESS The method was successful.

SVRMAP_NO_MORE_ITEMS There are no Server objects in the Store object to

enumerate.

Remarks
See Save on page 4–15 for details.

4–14 DocuShare Windows Client SDK

DSServerMap Library Objects

Save

VB Save() As Long

C++ long Save();

The Save method is used to save a Store object to the registry memory.

Parameters
None.

Return value

Value Description

SVRMAP_RESULT_SUCCESS The method was successful.

SVRMAP_RESULT_NOCHANGE The method was successful. There were no

changes to the Store object state. This result is
typical of a Store object flagged with
SVRMAP_STOREOPT_STANDALONE.

SVRMAP_RESULT_OUTOFRANGE A Store object has been exeeded. It can only

support up to 16 Server objects.

SVRMAP_RESULT_AUTHDBERROR Access to the Store database is denied due to an

unknown database error.

SVRMAP_RESULT_AUTHDBLOCKED The storage database is locked by another

instance of Store, or the current instance was not
Protected before the Save operation.

SVRMAP_RESULT_NOTAUTHORIZED The current user does not have authorization to

perform Save.

SVRMAP_RESULT_MAPWRITEFAIL The method failed. This return occurs if there is an

error in saving the servers to the
BaseRegistryKey.

SVRMAP_RESULT_DUPLICATEINDEX The Store object has attempted to add a Server

object into an index that is being utilized.

Remarks
' Add a Server object to a Store
' and then save the Store
Function PermAdd(ByRef objStore As Object, ByRef objServer As Object) As
Boolean
' Ensure that the objStore is not currently protected
If objStore.IsProtected = 0 Then
' objStore is not protected

DocuShare Windows Client SDK 4–15

Objects DSServerMap Library

objStore.Protect ' Protect the Store for add and save

objStore.Add (objServer)
objStore.Save
objStore.Unprotect
PermAdd = True
Else
' objStore is protected
PermAdd = False
End If
End Function

4–16 DocuShare Windows Client SDK

DSServerMap Library Objects

Unprotect

VB Unprotect() As Long

C++ long Unprotect();

The Unprotect method is used to release a Store object that was protected to perform an Add, Remove, or
Save method.

Parameters
None

Return value

Value Description

SVRMAP_RESULT_SUCCESS The method was successful.

SVRMAP_RESULT_NOCHANGE The method was successful. There were no

changes to the Store object state. This result is
typical of a Store object flagged with
SVRMAP_STOREOPT_STANDALONE.

SVRMAP_RESULT_AUTHDBERROR Access to the Store database is denied due to an

unknown database error.

SVRMAP_RESULT_NOTAUTHORIZED The current user does not have authorization to

perform Unprotect.

Remarks
See Save on page 4–15 for details.

DocuShare Windows Client SDK 4–17

Objects DSServerMap Library

4.2.1.2 Store properties

This section contains the Store property definitions.

BaseRegistryKey

VB BaseRegistryKey As String

C++ CString GetBaseRegistryKey();

void SetBaseRegistryKey(LPCSTR lpszNewValue);

Access Read/Write

The BaseRegistryKey property is used to set the registry key where a Store object saves its list of Server
object connection information.

Remarks
The default base registry is DsNsx\Servers. The default base key is utilized by the DocuShare client. Any
addition or deletion of Server objects to the default base key is reflected in the DocuShare Client
environment.

To create a custom Store object, set the BaseRegistryKey property before performing a Store.Load
method.

' Create a Store object

Dim objStore
Set objStore = CreateObject("DsServerMap.Store")
objStore.BaseRegistryKey = "My\Servers"
lStatus = objStore.Load ' Load the custom Store object
...
To save copy of a Store object:

1. Perform a Store.Load method with the source BaseRegistryKey.

2. Change the BaseRegistryKey to the target Store.
3. Perform a Store.Save operation.

4–18 DocuShare Windows Client SDK

DSServerMap Library Objects

ISProtected

VB IsProtected As Long

C++ long GetIsProtected();

Access Read-only

The IsProtected property is utilized to test a Store object before a Protect method is invoked. The
IsProtected property returns a 0 if the Store object is not protected. A return value of 1 means the Store
object is protected. If a Store object has the SVRMAP_STOREOPT_STANDALONE option set, then this
property always return 0.

Remarks
See Save on page 4–15 for details.

NextItem

VB NextItem As Server

C++ LPDISPATCH GetNextItem();

Access Read-only

The Next Item property returns a Server object when iterating through a Store object.

Remarks
See NextPos on page 4–20 for an example of this property.

DocuShare Windows Client SDK 4–19

Objects DSServerMap Library

NextPos

VB Property NextPos As Long

C++ long GetNextPos();

Access Read-only

This property is used to iterate through the Store. It equals a positive number as long as there are server
objects to be iterated. NextPos equals 0 when the end of the iteration list is reached. To return to the
beginning of the list, call Reset (Reset on page 4–14).

To call a Server object, utilize the NextItem property

Remarks
The following example iterates through a Store object and logs in all of the Server objects.

' Logon all servers

Sub LogonServers(ByRef objStore As Object)
' Create a temp Server object
Dim objServer As Object
' Enumerate through the Server objects
objStore.Reset
While 0 <> objStore.NextPos
Set objServer = objStore.NextItem
objServer.Logon ' Logon the server
Wend
End Sub

4–20 DocuShare Windows Client SDK

DSServerMap Library Objects

Options

VB Options As Long

C++ long GetOptions();

void SetOptions(long nNewValue);

Access Read/Write

The Options property is used to set a variety of flags for the Store object. The flags modify the behavior of
certain store operations.

Remarks
To remove all flag settings and return to the default behavior for a Store object, pass a 0 value into the
Options property. To set more than one flag, OR the flags together.

Flags Description

SVRMAP_STOREOPT_REMOVEBYID Use instance ID to validate the server to be

removed.

SVRMAP_STOREOPT_KEEPDISCON Find and reset should not remove a disconnected

server.

SVRMAP_STOREOPT_LIMITREMOVE Disallow removal if a server is open. User has not

logged out.

SVRMAP_STOREOPT_STANDALONE Use this Store object as a standalone. This option

flag is used when a standalone copy of the default
Store is used.
This prevents the Store object from attempting to
sychronize with any instance of the default Store
that may be created.
This flag does nothing if the BaseRegKey is
changed from the default prior to a Store.Load
operation.

DocuShare Windows Client SDK 4–21

Objects DSServerMap Library

SelectDialogOption

VB SelectDialogOption(Text as string, Flags as Variant) as long

C++ long GetSelectDialogOption(LPCTSTR Text, VARIANT* Flags);

void SetSelectDialogOption(LPCTSTR Text, VARIANT* Flags, long NewValue);

Access Read/Write

SelectDialogOption specifies addition of a check box or radio button control on a dialog window run by
DoSelectDialog; also specifies a text label to be shown next to the control.

The HIWORD of SelectDialogOption has SVRMAP_SDOFLAG_TRISTATE.

The lFlags parameter of method DoSelectDialog contains the SVRMAP_SELDLGFLAG_SHOWOPTION

flag.

Parameters

Parameter Description

Text Contains a label for the control

Flags High word (16th through 31st bits) contains a flag

for specifying the control type, and the low word
(0th through 15th bits) contains a flag for
specifying the selection state.

Use one of the 32-bit wide constants below to choose between check box and radio button.

Constants Description

SVRMAP_SDOFLAG_CHECKBOX Add a check box control to the server selection UI.

SVRMAP_SDOFLAG_RADIOBUTTON Add a radio button control.

SVRMAP_SDOFLAG_CHECKBOX Can be combined with the flag for arming the

check box control with three selection states:
checked, unchecked, and indeterminate.

SVRMAP_SDOFLAG_TRISTATE Use a tri-state check box control.

4–22 DocuShare Windows Client SDK

DSServerMap Library Objects

To pre-select the control's selection state, OR the above flags by one of the state flags below. The state
flags are defined in the Windows Platform SDK.

Flags Description

BST_CHECKED Sets the button state to checked.

BST_INDETERMINATE Sets the button state to grayed, indicating an

indeterminate state. Use this value only if the
button has the BS_3STATE or BS_AUTO3STATE
style.

BST_UNCHECKED Sets the button state to cleared.

SelectDialogOption = SVRMAP_SDOFLAG_CHECKBOX or BST_CHECKED

Remarks
If a value is not assigned, SelectDialogOption contains a value of -1.

If the option, SVRMAP_STOREOPT_STANDALONE, SVRMAP_STOREOPT_SHORTCUTSTORE, or

SVRMAP_STOREOPT_PEERSTORE is enabled, SelectDialogOption contains a value of 0.

If SelectDialogOption is assigned a value and the Text value is not the same as the current Text value of
SelectDialogOption, SelectDialogOption is set to -1.

DocuShare Windows Client SDK 4–23

Objects DSServerMap Library

4.2.2 Browser
List of Browser methods and properties.

Browser Methods and Properties

Cookie Options

DocuShareAddress ProxyAddress

Init View

NavigateTo ViewProps

OwnerHwnd

4.2.2.1 Browser methods

This section contains the Browser method definitions.

Init

VB Init(pServer As Server) As Long

C++ long Init(LPDISPATCH pServer);

Init initializes the Browser object using properties of a Server object.

Parameters
pServer—a valid Server object.

Return value

Value Description

SVRMAP_RESULT_SUCCESS The method was successful.

SVRMAP_RESULT_UNKNOWNERROR The method failed due to an unknown error.

SVRMAP_RESULT_OUTOFMEMORY The method failed due to insufficient memory

resources.

Remarks
The Init method assigns the following Server properties to the Browser object:

• Server.DocuShareAddress to Browser.DocuShareAddress
• Server.ProxyAddress to Browser.ProxyAddress (if Server.UseProxy is True)
• Server.AuthToken to Browser.Cookie
• Server.OwnerHwnd to Browser.OwnerHwnd

4–24 DocuShare Windows Client SDK

DSServerMap Library Objects

NavigateTo

VB NavitgateTo( URL As String, PostData As String) As Long

C++ long NavigateTo(LPCTSTR URL, LPCTSTR PostData, LPCTSTR

HeaderData);

NavigateTo runs a new instance of MS Internet Explorer and opens a specified URL in its window.

Parameters

Parameter Description

URL A required URL string.

PostData An optional string containing form data to post.

HeaderData An optional string containing custom headers to

add to IE's default headers.

Return value

Value Description

SVRMAP_RESULT_SUCCESS The method was successful.

S_FALSE The method failed due to an unknown error.

E_INVALIDARG The method failed due to an invalid argument.

E_OUTOFMEMORY The method failed due to insufficient memory

resources.

Remarks
If the PostData value is empty, the method uses the HTTP GET method to open the URL. If PostData
contains a value, the method uses the HTTP POST method. The NavigateTo method passes the PostData
and HeaderData values as form data and extra headers to IE. Any form data in PostData must be encoded
in 8-bit ANSI.

The NavigateTo method passes the value of the Cookie property to IE for navigating to an
authentication-requiring DocuShare page if the specified URL is located under the URL of the
DocuShareAddress property. For example, if the URL is
http://docushare.xyz.com/dscgi/ds.py/View/Collection-123 and if the DocuShareAddress property contains
http://docushare.xyz.com/, the method passes the Cookie value to IE. If the target URL requires
authentication, IE should open the URL successfully.

DocuShare Windows Client SDK 4–25

Objects DSServerMap Library

Here is a simple VB script for opening the home page of Xerox Corporation.

dim browser
set browser = CreateObject("DSServerMap.Browser")
Browser.URL = "http://www.xerox.com/"
browser.NavigateTo(URL, "", "")
This sample script navigates to a DocuShare collection page which requires user authentication.

dim server
set server = CreateObject("DSServerMap.Server")
server.DocuShareAddress = "http://docushare.xyz.com/"
status = server.Logon
if status = 0 then
dim browser
set browser = CreateObject("DSServerMap.Browser")
browser.Init(server)
status = browser.NaviageTo ("http://docushare.xyz.com/dscgi/ds.py/View/
Collection-123", ", "")
end if

4–26 DocuShare Windows Client SDK

DSServerMap Library Objects

View

VB View(itemType As Long, itemHandle As Long) As Long

C++ long View(long itemType, long itemHandle);

The View method runs a new instance of MS Internet Explorer and opens a DocuShare web page
corresponding to a specified item.

Parameters

Parameter Description

itemType DSXITEMTYPE_xxx type specifier of a valid

DocuShare item.

itemHandle Handle number of a valid Docushare item.

Return value
SVRMAP_RESULT_SUCCESS—The method was successful. A non-zero result signifies failure.

Remarks
If the item to view is Collection-123, itemType is set to DSXITEMTYPE_COLLECTION, and itemHandle is
set to 123.

The following type specifiers are valid:

Specifiers Description

DSXITEMTYPE_SERVER DocuShare Home page

DSXITEMTYPE_DOCUMENT File object

DSXITEMTYPE_CALENDAR Calendar object

DSXITEMTYPE_BBOARD Bulletin board object

DSXITEMTYPE_USER User object

DSXITEMTYPE_GROUP Group object

DSXITEMTYPE_URL URL object

DSXITEMTYPE_SAVEDQUERY Saved query object

DocuShare Windows Client SDK 4–27

Objects DSServerMap Library

For DSXITEMTYPE_DOCUMENT type, the following options can be used:

Specifier Option Description

IELINK_OPTION_NODOCREPR Show the original file contents; do not show file

representation data, such as thumbnail.

IELINK_OPTION_HTMLREPR Show the contents using an HTML rendition.

IELINK_OPTION_PDFREPR Show the contents using a PDF rendition.

IELINK_OPTION_THUMBREPR Show a thumbnail picture of the image file

contents.

For DSXITEMTYPE_CALENDAR type, the following options can be used:

Specifier Option Description

IELINK_OPTION_CALMONTH Show a monthly calendar.

IELINK_OPTION_CALWEEK Show a weekly calendar.

IELINK_OPTION_CALDAY Show a daily calendar.

Here is a sample Visual Basic script for showing Collection-123 in Internet Explorer.

dim server
set server = CreateObject("DSServerMap.Server")
server.DocuShareAddress = "http://docushare.xyz.com/"
status = server.Logon
if status = 0 then
dim browser
set browser = CreateObject("DSServerMap.Browser")
browser.Init(server)
status = browser.View(DSXITEMTYPE_COLLECTION, 123)
end if
If the user is logged into the server, the script immediately runs IE and opens the collection. The collection
is assumed to be access protected, so explicit DocuShare authentication is required. If no authentication is
needed, a server object is not necessary. Set the Browser‘s object DocuShareAddress property to the
DocuShare server home page URL and call Browser.View.

4–28 DocuShare Windows Client SDK

DSServerMap Library Objects

ViewProps

VB ViewProps(itemType As Long, itemHandle As Long) As Long

C++ long ViewProps(long itemType, long itemHandle);

The ViewProps method runs a new instance of MS Internet Explorer and opens a Services page for a
specified DocuShare item.

Parameters

Parameter Description

itemType The type of object whose properties are viewed in

the browser.

itemHandle The handle number of the item whose properties

are viewed in the browser.

Return value
SVRMAP_RESULT_SUCCESS—The method was successful. A non-zero result signifies failure.

Remarks
If the item to view is Collection-123, itemType is set to DSXITEMTYPE_COLLECTION, and itemHandle is
set to 123.

Refer to View on page 4–27 for a list of supported item types.

Here is a sample VB script for showing the services page of Collection-123 in IE.

dim server
set server = CreateObject("DSServerMap.Server")
server.DocuShareAddress = "http://docushare.xyz.com/"
status = server.Logon
if status = 0 then
dim browser
set browser = CreateObject("DSServerMap.Browser")
browser.Init(server)
status = browser.ViewProps(DSXITEMTYPE_COLLECTION, 123)
end if

DocuShare Windows Client SDK 4–29

Objects DSServerMap Library

4.2.2.2 Browser properties

This section contains the Browser property definitions.

Cookie

VB Property Cookie As String

C++ CString IBrowser::GetCookie()

void IBrowser::SetCookie(LPCTSTR lpszNewValue)

Access Read/Write

Cookie property contains a DocuShare session handle that corresponds to Server.AuthToken.

Remarks
A Browser object uses the Cookie property to authenticate the URL navigation request. NavigateTo, View,
and ViewProps methods are affected. If the Cookie value is empty, it is equivalent to Guest access.

Cookie is automatically updated when the Init method is called with a valid Server object. The value of
Server.AuthToken is assigned to Cookie.

DocuShareAddress

VB DocuShareAddress As String

C++ CString GetDocuShareAddress();

void SetDocuShareAddress(LPCTSTR lpszNewValue);

Access Read/Write

DocuShareAddress contains the base URL of a Docushare server. The URL corresponds to the home
page URL when viewed in a web browser.

Remarks
DocuShareAddress is automatically updated when the Init method is called with a valid Server object. The
value of Server.DocuShareAddress is assigned to DocuShareAddress. NavigateTo, View, and ViewProps
methods require this property.

4–30 DocuShare Windows Client SDK

DSServerMap Library Objects

Options

VB Options As Long

C++ long GetOptions();

void SetOptions(long nNewValue);

Access Read/Write

The Options property controls the behaviors for the View method. Refer to View on page 4–27 for more
details.

OwnerHwnd

VB OwnerHwnd As Long

C++ long GetOwnerHwnd();

void SetOwnerHwnd(long nNewValue);

Access Read/Write

OwnerHwnd contains the window handle for a window that owns the Browser object.

Remarks
OwnerHwnd is not currently used.

ProxyAddress

VB ProxyAddress As String

C++ CString GetProxyAddress();

void SetProxyAddress(LPCTSTR lpszNewValue);

Access Read/Write

ProxyAddress is an optional parameter and may contain the address of a proxy server used to contact a
DocuShare server.

Remarks
A valid example address is http://myproxyserver.xyz.com:8000/

DocuShare Windows Client SDK 4–31

Objects DSServerMap Library

4.2.3 Wizard
List of Wizard methods and properties.

Methods and Properties

Init

Options

Run

4.2.3.1 Wizard methods

This section contains the Wizard method definitions.

Init

VB Init(pServer As Server)

C++ void Init(LPDISPATCH pServer);

The Init method initializes the Wizard interface. Initialization passes a Server object to the Wizard interface
for collecting connection information.

Parameters
pServer—an object of type Server.

Return value
None

Remarks
For an example of the Wizard.Init function see Run on page 4–33.

4–32 DocuShare Windows Client SDK

DSServerMap Library Objects

Run

VB Run() As Long

C++ long Run();

The Run method is used to run a Server Mapping Wizard. The wizard gathers connection information from
a user and stored in a Server object.

Parameters
None

Return value

Value Description

SVRMAP_RESULT_SUCCESS The method was successful.

SVRMAP_RESULT_CANCEL The method was canceled by the user.

SVRMAP_RESULT_OUTOFSYSRES The method failed due to insufficient system

resources.

Remarks
This function is used to invoke an instance of a Wizard GUI that aids a developer to gather server
connection information from a user. It does not automatically add the server to a server Store. For
information on adding a server object to a server, see Add on page 4–4.

The example below demonstrates using Wizard.Run.

' First create a server object

Dim objSvr
Set objSvr = CreateObject("DsServerMap.Server")
' Now we create and initialize the objWizard
Dim objWizard
Set objWizard = CreateObject("DsServerMap.Wizard")
objWizard.Init objSvr
Dim lResult
lResult = objWizard.Run
' The objSvr now contains the server object connection information

DocuShare Windows Client SDK 4–33

Objects DSServerMap Library

4.2.3.2 Wizard properties

This section contains the Wizard property definitions.

Options

VB Options As Long

C++ long GetOptions();

void SetOptions(long nNewValue);

Access Read/Write

The Options property, if set, allows a user to create a new user when mapping onto a server.

Remarks
The Options property should be set before a call is made to the Run method.

The only constant flag that is passed to the Options property is:

SVRMAP_WIZOPT_DISALLOW_ACCTCREATE. The default value is hex 0.

4–34 DocuShare Windows Client SDK

DSServerMap Library Objects

4.2.4 Server
List of Server methods and properties.

Methods Properties

AuthenticateUser AuthDigest

BroadcastEvent AuthToken

CacheCredentials ClassSchemaEnumerator

Compare CheckinServiceManager

CopyTo CustomPropName

CreateObject CustomProps

EnsureWIPFolderExist CustomPropValue

Load DBAccessToken

Logoff DocuShareAddress

Logon Domain

Open ErrorDescription

Protect FolderHandle

Save FolderType

Unprotect GuestAccess

UpdateSchemaCache HostServer

Icon

Instanceld

IsLoggedOn

IsProtected

IsSelected

LastError

MapIndex

Name

Options

OwnerHwnd

Param

Password

ProgramFolder

DocuShare Windows Client SDK 4–35

Objects DSServerMap Library

Methods Properties

ProtocolScheme

ProxyAddress

ProxyAuth

ReadOnly

SessionFlags

SHItemDescriptor

ShortcutStore

TypeIndex

UseProxy

UserHandle

UserName

UseWindowsAuth

Version

WIPFolder

WorkFolder

WWWAuth

WWWSecure

4.2.4.1 Server methods

This section contains the Server method definitions.

4–36 DocuShare Windows Client SDK

DSServerMap Library Objects

AuthenticateUser

VB AuthenticateUser() As Long

C++ long AuthenticateUser();

The AuthenticateUser method authenticates a user with a DocuShare server. This method does not
update the logon status and authentication level in the server database.

Parameters
None

Return value

Value Description

SVRMAP_RESULT_SUCCESS The method was successful.

SVRMAP_RESULT_INVALIDARG The user or server properties are invalid.

SVRMAP_RESULT_AXESOPENFAIL The method was unable to access a gateway

resource.

SVRMAP_RESULT_AXESLOGONFAIL The method failed to login.

SVRMAP_RESULT_OUTOFMEMORY The method failed due to insufficent memory

resources.

Remarks
The Logon method internally calls the AuthenticateUser method followed by calls to CacheCredentials and
BroadcastEvent. To control the logon process and do not propagate the logon status and authentication to
concurrent Server instances (opened through a Store object), set necessary credential properties and call
AuthenticateUser only.

The following Server properties are required:

• UserName
• Password
• DocuShareAddress
• UseProxy and ProxyAddress (if UseProxy is set to True)
Following the AuthenticateUser call, the values of the following properties are updated:

• UserHandle
• Version
• SessionFlags
• ReadOnly
• WWWAuth
• WWWSecure

DocuShare Windows Client SDK 4–37

Objects DSServerMap Library

BroadcastEvent

VB BroadcastEvent(IEvent As Long) As Long

C++ long BroadcastEvent(long lEvent);

The BroadcastEvent method notifies a DocuShare Client of a server event.

Parameters
lEvent—can be set to one of the following event flags.

Event Flag Description

SVRMAP_EVENT_LOGON A user has logged into the server represented by

this Server object.

SVRMAP_EVENT_LOGOFF A user has logged off.

SVRMAP_EVENT_ADD The server map represented by this Server object

has been added to the server database.

SVRMAP_EVENT_REMOVE The server map for this Server object has been
removed from the server database.

SVRMAP_EVENT_RENAME The server map has been renamed.

SVRMAP_EVENT_CHANGEATTR An attribute or property of the server map has

changed; for example, the UseProxy property was
changed.

An event flag can be combined with this flag: SVRMAP_EVENT_EXCLUDESELF

The flag excludes the caller from receiving the notification. The flag has no effect if the caller is not
subscribed to the DocuShare Client notification service.

Return value

Value Description

SVRMAP_RESULT_SUCCESS The method was successful.

SVRMAP_RESULT_NOCHANGE The method was successful. No changes to the

session state occurred.

SVRMAP_RESULT_NOTIFYFAIL The method failed to notifiy the other DocuShare

client applications.

SVRMAP_RESULT_NODSNSX There is no DSNSX mechanism to broadcast

events to other applications.

SVRMAP_RESULT_INVALIDARG The method encountered an invalid argument.

SVRMAP_RESULT_OUTOFMEMORY The method failed due to insufficient memory

resources.

4–38 DocuShare Windows Client SDK

DSServerMap Library Objects

Value Description

SVRMAP_RESULT_COMCREATEFAIL The method failed to make a COM object creation

failure.

Remarks
This method is automatically called by Server.Logon.

CacheCredentials

VB CacheCredentials(() As Long

C++ long CacheCredentials();

CacheCredentials method saves the authentication and other logon status information in the server
database so that the DocuShare Client can share the authentication.

Parameters
None

Return value

Value Description

SVRMAP_RESULT_SUCCESS The method was successful.

SVRMAP_RESULT_NOCHANGE The method was successful. No changes to the

session state occured.

SVRMAP_RESULT_AUTHDBERROR Access to the Store database is denied due to an

unknown database error.

Remarks
The Logon method internally calls this method. This method can be used after successfully making an
explicit call to the AuthenticateUser method.

If the AuthenticateUser method is called and CacheCredentials is not called, any DocuShare Client
processes running, does not know a user session was opened by this Server object.

DocuShare Windows Client SDK 4–39

Objects DSServerMap Library

Compare

VB Compare(pServer As Server, IFlags As Long) As Long

C++ long Compare(LPDISPATCH pServer, long lFlags);

The Compare method compares two Server objects.

Parameters

Parameter Description

pServer The target Server object compared to the current

Server object .

lFlags The properties to compare.

Flag Description

SVRMAP_COMPARE_NAME Compare server names.

SVRMAP_COMPARE_DSADDR Compare server addresses.

SVRMAP_COMPARE_USERNAME Compare usernames.

SVRMAP_COMPARE_FOLDERTYPE Compare folder types.

SVRMAP_COMPARE_FOLDERHANDLE Compare folder handles.

SVRMAP_COMPARE_INSTANCEID Compare instance IDs.

SVRMAP_COMPARE_STATUS Compare statuses.

SVRMAP_COMPARE_NSXATTRIB Compare the NSX notification attributes.

SVRMAP_COMPARE_CASESENS Ensure the comparisons are case sensitive.

SVRMAP_COMPARE_REVERSE Compare the properties in reverse order.

Return value
Zero—The method was successful. A non-zero return occurs if the Server objects are dissimiliar.

4–40 DocuShare Windows Client SDK

DSServerMap Library Objects

CopyTo

VB CopyTo(pServer As Server) As Long

C++ long CopyTo(LPDISPATCH pServer);

The CopyTo method copies the properties from one Server object to another.

Parameters
pServer—the target Server object for copies.

Return value

Value Description

SVRMAP_RESULT_SUCCESS The method was successful.

SVRMAP_RESULT_UNKNOWNERROR The method failed due to an unknown error.

Remarks
The following Options flags control how CopyTo performs the copying:

Option Flag Description

SVRMAP_OPTION_COPYPRIV Include the instance-specific (private) properties:

InstanceId, Options, LastError, ErrorDescription
and OwnerHwnd.

SVRMAP_OPTION_COPYCRED Include the credential properties: Password and

AuthToken.

SVRMAP_OPTION_COPYNOIDENTIFY Exclude the identify properties: Name, FolderType

and FolderHandle.

SVRMAP_OPTION_COPYSTATE Copy all session state settings: SessionFlags,

ReadOnly, WWWAuth and WWWSecure.

See Options on page 4–66 for constants and to set the copy options.

DocuShare Windows Client SDK 4–41

Objects DSServerMap Library

CreateObject

VB CreateObject(bstrHandle As String) As ItemObj

C++ LPDISPATCH CreateObject(LPCTSTR bstrHandle);

The CreateObject method creates an object of the specified type and returns an ItemObj representing the
object.

Parameters
bstrHandle—a list of valid string handles.

Bulletin Collection Group URL

BulletinBoard DSClient SavedQuery User

Calendar File Server

Return value
This function returns an IDispatch pointer to a created ItemObj object.

Remarks
SVRMAP_OPTION_OPENWITHOUTAUTH causes the created item object not to run the user logon
dialog automatically when first contacting DocuShare. The flag can be used when creating a user object.

NOTE: The created object is not stored on the DocuShare server. It is a simple local, in-memory only
object.

4–42 DocuShare Windows Client SDK

DSServerMap Library Objects

EnsureWIPFolderExist

VB EnsureWIPFolderExists() As Long

C++ long EnsureWIPFolderExists();

Ensures that the work-in-progress (WIP) folders specified by WIPFolder exist.

Parameters
None

Return value

Value Description

SVRMAP_RESULT_SUCCESS The method was successful.

SVRMAP_RESULT_DIRCREATEFAIL The method failed to create a local directory.

Remarks
The method creates a subfolder and name it by the value of WIPFolder under each of the following three
folders:

[DSCLIENT]\[WORK]\TMP

[DSCLIENT]\[WORK]\WIP

[DSCLIENT]\[WORK]\MON

DSCLIENT is the pathname of the folder where DSClientSDK is installed, and WORK is the name of the
base work folder of the current end user. Typically, DSCLIENT is set to C:\Program Files\Xerox\DSClient,
and WORK to Work.

If the WIPFolder value is MyDocuShare, the following tree exists after a call to this method:

C:\Program Files\Xerox\DSClient\Work\TMP\MyDocuShare

C:\Program Files\Xerox\DSClient\Work\WIP\MyDocuShare

C:\Program Files\Xerox\DSClient\Work\MON\MyDocuShare

The read-only property, Server.WorkFolder, points to the TMP folder. You can use it to store any temporary
file. You are responsible for removing any file you created in the folder. WIP and MON are used by the
DocuShare Client for purposes of file checkout control and should not be used by an SDK application.

DocuShare Windows Client SDK 4–43

Objects DSServerMap Library

Load

VB Load() As Long

C++ long Load();

The Load method loads the serialized server access and user account information consisting of a server
map from an associated server database.

Parameters
None

Return value

Value Description

SVRMAP_RESULT_SUCCESS The method was successful.

SVRMAP_RESULT_BADMAP The method failed to load a map due to a corrupt

map entry in the database.

SVRMAP_RESULT_OUTOFRANGE The method failed due to a database entry

overflow.

SVRMAP_RESULT_MAPREADFAIL The method failed due to an inability to read the

map entry from the database.

Remarks
InstanceId must be set prior to calling this method.

If CustomPropName contains a non-empty string value, the Load method loads the serialized custom
property into CustomPropValue.

4–44 DocuShare Windows Client SDK

DSServerMap Library Objects

Logoff

VB Logoff() As Long

C++ long Logoff();

The Logoff method decreases the logon count increment by a prior call to Logon. If the logon count
reaches zero, the user authentication is cleared, and any open session with the DocuShare server is
closed.

Parameters
None

Return value

Value Description

SVRMAP_RESULT_SUCCESS The method was successful.

SVRMAP_RESULT_NOCHANGE The method was successful. There were no

changes to the Server object state.

SVRMAP_RESULT_CANCEL The method was canceled by the user.

SVRMAP_RESULT_NOTIFYFAIL The method was unable to notify other DocuShare

client applications.

SVRMAP_RESULT_AUTHDBNOTLOADED The method failed due to an inability to load the

authentication database.

SVRMAP_RESULT_AUTHDBERROR Access to the Store database is denied due to an

unknown database error.

SVRMAP_RESULT_AUTHDBLOCKED Access to the Store database is denied due to a

locking contention.

Remarks
The Logoff method fails if the server map is protected in the server database, such as a concurrent
process modifying the server map in a call to Server.Save.

If there are other processes using the same server map, such as an Explorer window showing the
DocuShare Client view, the processes increments the logon count for the server. The call to Logoff does
not decrease the count to zero. If a non-zero count remains, the Logoff method, by default, runs a dialog
box and lets the user choose whether or not to stay logged in so that the other processes are not
interrupted. If the user chooses to log out, the logon count is brought to zero, and the server database
clears the authentication. The logoff event is broadcast to the other running processes on the DocuShare
Client.

To force logout silently, use the SVRMAP_OPTION_LOGOFFSILENT flag. Unconditional logout is

performed.

DocuShare Windows Client SDK 4–45

Objects DSServerMap Library

The Logoff method internally references the IsLoggedOn property. If the property indicates that the user is
not authenticated, the method broadcasts the event to the DocuShare Client and returns. To prevent event
notification, use the SVRMAP_OPTION_NOLOGONNOTIFY option.

If the server object is marked with SVRMAP_OPTION_STANDALONE, the Logoff method performs no
action and returns immediately.

4–46 DocuShare Windows Client SDK

DSServerMap Library Objects

Logon

VB Logon() As Long

C++ long Logon();

The Logon method runs a dialog to obtain server address, username, password, and authenticates the
user with DocuShare. If the user is already logged in, the method returns immediately. If the server object
has DocuShareAddress and UserName already set with values, the dialog box disallow edits to these
properties.

Parameters
None

Return value

Value Description

SVRMAP_RESULT_SUCCESS The method was successful.

SVRMAP_RESULT_CANCEL The method was canceled by the user.

SVRMAP_RESULT_NOTIFYFAIL The method was unable to notify other DocuShare

client applications.

SVRMAP_RESULT_INVALIDARG A user or server property is invalid.

SVRMAP_RESULT_AXESOPENFAIL The method was unable to access a gateway

resource.

SVRMAP_RESULT_AXESLOGONFAIL The method failed to login.

SVRMAP_RESULT_OUTOFMEMORY The method failed due to insufficient memory

resources.

SVRMAP_RESULT_AUTHDBNOTLOADED The method failed due to an error in loading the

authorization database.

SVRMAP_RESULT_AUTHDBERROR Access to the Store database is denied due to an

unknown database error.

SVRMAP_RESULT_AUTHDBLOCKED Access to the Store database is denied due to a

locking contention.

SVRMAP_RESULT_MAPLOADFAIL The method failed due to an inability to read the

map entry from the database.

Remarks
The following options can be used to control the logon dialog's behavior.

Option Description

SVRMAP_OPTION_CANCHANGEADDR Permits server address editing.

DocuShare Windows Client SDK 4–47

Objects DSServerMap Library

Option Description

SVRMAP_OPTION_CANCHANGEUSER Permits username editing.

The Logon method allows two additional retry attempts if the server responds with an authentication error
(HTTP codes 401, 500 or 503). To prevent repeated attempts, use the
SVRMAP_OPTION_NOLOGONRETRY option.

The Password property, regardless of the result, is cleared upon conclusion of the authentication request
with DocuShare.

The Logon method fails if the server map is protected in the server database, such as a concurrent
process modifying the server map in a call to Server.Save.

If the AccessGuest property is set to True, the method may return immediately. However, if
DocuShareAddress is empty, a logon dialog will run to obtain the address of the server.

Open

VB Open() As Object DSGateway.GatewayHandler

C++ LPDISPATCH Open();

The Open method returns a gateway object that can be used to connect to a DocuShare server mapped to
the Server object.

Parameters
None

Return value
Returns a IDispatch pointer to a gateway object.

Remarks:
Use SVRMAP_OPTION_OPENWITHOUTAUTH to open a gateway without being authenticated. See
CreateObject on page 4–42 for using this flag.

4–48 DocuShare Windows Client SDK

DSServerMap Library Objects

Protect

VB Protect())As Long

C++ long Protect();

Protect method protects the server map in the associated server database so that another process cannot
access the server map.

Parameters
None

Return value

Value Description

SVRMAP_RESULT_SUCCESS The method was successful.

SVRMAP_RESULT_NOCHANGE The method was successful. There were no

changes to the Server object state.

SVRMAP_RESULT_AUTHDBNOTLOADED The method failed due to an error in loading the

authentication database.

SVRMAP_RESULT_AUTHDBERROR Access to the Store database is denied due to an

unknown database error.

SVRMAP_RESULT_AUTHDBLOCKED Access to the Store database is denied due to a

locking contention.

Remarks
With the Protect method called and the Unprotect method not called, the IsProtected property returns a
value of True.

Any write operation performed by an associated Store object uses this method to protect the server map
from other running processes.

DocuShare Windows Client SDK 4–49

Objects DSServerMap Library

Save

VB Save() As Long

C++ long Save();

The Save method serializes the server map settings into an associated server database.

Parameters
None

Return value

Value Description

SVRMAP_RESULT_SUCCESS The method was successful.

SVRMAP_RESULT_OUTOFRANGE The method could not save the current Server

object into the Store database due to insufficent
entry space.

SVRMAP_RESULT_AUTHDBLOCKED Access to the Store database is denied due to a

locking contention

SVRMAP_RESULT_MAPWRITEFAIL The method failed due to an inability to write the

map entry to the Store database.

Remarks
If the server map is protected, the method fails.

If CustomPropName is set with a value, the Save method serializes the value of CustomPropValue.

4–50 DocuShare Windows Client SDK

DSServerMap Library Objects

Unprotect

VB Unprotect() As Long

C++ long Unprotect();

Unprotect releases a write protection for the server map in the server database so that the server map can
be accessed by a concurrent process.

Parameters
None

Return value

Value Description

SVRMAP_RESULT_SUCCESS The method was successful.

SVRMAP_RESULT_NOCHANGE The method was successful. There were no

changes to the Server object state.

SVRMAP_RESULT_AUTHDBERROR Access to the Store database is denied due to

unknown database error.

SVRMAP_RESULT_NOTAUTHORIZED Access to the Store database is denied due to a

locking contention.

Remarks
Unprotect always should be called if Protect has been called. Failure to do so may cause a concurrent
process to lock up.

DocuShare Windows Client SDK 4–51

Objects DSServerMap Library

UpdateSchemaCache

VB UpdateSchemaCache() as Long

C++ long UpdateSchemaCache();

UpdateSchemaCache retrieves schemata from a server and updates the schema cache maintained on the
client machine.

Return value

Value Description

SVRMAP_RESULT_SUCCESS A schema cache was successfully updated.

SVRMAP_RESULT_AXESOPENFAIL Gateway could not be opened. Server.LastError is

set to a HRESULT value returned by Win32 API
function CoCreateInstance.

SVRMAP_RESULT_AXESSCHEMAFAIL Schema retrieval failed. Server.LastError is set to

a value returned by
GatewayHandler.GetLastError().

SVRMAP_RESULT_OUTOFMEMORY A status UI could not be created. Server.LastError

is set to 0.

Remarks
If the SVRMAP_OPTION_REUSEGATEWAY option is enabled and a gateway was opened, the same
gateway is used to contact the DocuShare server.

Making the registry entry below disables schema retrieval. UpdateSchemaCache returns
SVRMAP_RESULT_SUCCESS even though schemata was not downloaded.

[HKCU\Software\Xerox\DocuShare Client\DsNsx\Settings]
"SkipSchema"=dword:00000001
The disable registry setting applies to AuthenticateUser and Logon when the option
SVRMAP_OPTION_LOGONLOADSSCHEMA is enabled.

4–52 DocuShare Windows Client SDK

DSServerMap Library Objects

4.2.4.2 Server properties

This section contains the Server property definitions.

AuthDigest

VB AuthDigest as Long

C++ long GetAuthDigest();

Access Read only

The property contains a 32-bit digest of the authentication token. Uniqueness is not guaranteed.

AuthToken

VB AuthToken as String

C++ CString GetAuthToken();

void SetAuthToken( LPCTSTR );

Access Read/Write

Property AuthToken contains a DocuShare session handle which was obtained through a call to Logon or
AuthenticateUser.

Remarks
It is possible to directly assign a value to this property. However, the new value is applicable only to the
current IServer instance; it does not affect a concurrent IServer instance. To cause a global change to the
authentication status, an application must call either Logon or AuthenticateUser

ClassSchemaEnumerator

VB ClassSchemaEnumerator as Object DSItemEnumLib.EnumObj

C++ IDispatch* GetClassSchemaEnumerator();

void SetClassSchemaEnumerator( IDispatch* );

Access Read/Write

Contains a DocuShare object class enumerator. The enumerator contains all standard and custom object
classes defined on a DocuShare server. However, the base Object class of DocuShare is not included.

DocuShare Windows Client SDK 4–53

Objects DSServerMap Library

CheckinServiceManager

VB CheckinServiceManager as Object CheckinServiceManager

C++ IDispatch* GetCheckinServiceManager();

Access Read-only

Contains an object which manages file checkin services available to the server associated with this Server
object.

CustomProps

VB CustomProps(ID as string) as PropCollection

C++

Access Read-only

Contains an enumerator object that enumerates custom properties.

Parameters
ID—contains a string that identifies a collection of custom properties defined for the server map.

Remarks
The following IDs are pre-defined and should not be used by applications:

• SDKProps—ID used by DSClient SDK libraries

• DSPeerServers—ID used by DSClient SDK libraries for peer management
• MAPIProfile_*—IDs used by Outlook Client

4–54 DocuShare Windows Client SDK

DSServerMap Library Objects

CustomPropName

VB CustomPropName As String

C++ CString GetCustomPropName();

void SetCustomPropName(LPCTSTR lpszNewValue);

Access Read/Write

CustomPropName specifies the name of a custom property for the Server object. If the property has a
value, the Save method saves the value of CustomPropValue, while the Load method reloads it into
CustomPropValue.

Remarks
To load the custom property from the server database, use this script.

dim myStore
set myStore = CreateObject(...)
myStore.Load
myStore.Reset
while myStore.NextPos <> 0
dim myServer
set myServer = myStore.NextItem
myServer.CustomPropName = "SpecialProperty"
myServer.Load ' Reload because Store.Load did not know the custom property
wend
To save the custom property in the server database, make sure that Server.CustomPropName is set to a
valid name and call either Server.Save or Store.Save.

CustomPropValue

VB CustomPropValue As String

C++ CString GetCustomPropValue();

void SetCustomPropValue(LPCTSTR lpszNewValue);

Access Read/Write

CustomPropValue specifies the value of CustomPropName.

Remarks
Refer to CustomPropName on page 4–55 to save and load a custom property.

DocuShare Windows Client SDK 4–55

Objects DSServerMap Library

DBAccessToken

VB DBAccessToken as Long

C++ long GetDBAccessToken();

void SetDBAccessToken( long );

Access Read/Write

Contains a 32-bit token that grants access to the global authentication database managed by the
DocuShare Client. Server.DBAccessToken can be set to the value of Store.DBAccessToken following a
call to Store.Protect.

DocuShareAddress

VB DocuShareAddress As String

C++ CString GetDocuShareAddress();

void SetDocuShareAddress(LPCTSTR lpszNewValue);

Access Read/Write

DocuShareAddress specifies the URL address of a DocuShare server.

Remarks
The address value corresponds to the URL of the DocuShare home page as seen in a web browser.

NOTE: The address does not contain the dscgi/ds.py directory specifier.

For a secure address, this property may contain an SHTTP protocol scheme. Valid example addresses
are:

• http://my.xyz.com/
• http://my.xyz.com/docushare/
• http://my.xyz.com:1234/
• http://my.xyz.com/docushare:1234/
• https://securedocushare.xyz.com/

4–56 DocuShare Windows Client SDK

DSServerMap Library Objects

Domain

VB Domain as String

C++ CString GetDomain();

void SetDomain( LPCTSTR );

Access Read/Write

Contains a DocuShare server domain name.

ErrorDescription

VB ErrorDescription As String

C++ LPCTSTR GetErrorDescription();

void SetErrorDescription(LPCTSTR lpszNewValue);

Access Read/Write

ErrorDescription contains a string that describes an error encountered by the Server object.

Remarks
When an assignment is made, the value of the property is saved in the server database. When a reference
is made, the value of the property is updated using the latest value in the server database. If error sharing
is not desired, SVRMAP_OPTION_STANDALONE should be used.

The Server object itself does not update this property, even if it encounters an error while its code
processes an IServer call. The user of a Server object uses the property to attach an error string to the
Server object so that the error string can be shared by concurrent processes which open the same Server
object.

The Store object uses this property to pass an error description to the caller of Store.CanAdd. DocuShare
Client uses this property to store the error description for any network access error it encounters.
Therefore, if an SDK application modifies this property, the value will appear in the Explorer view of the
DocuShare Client. Also, by inspecting this ErrorDescription, LastError, or both, an SDK application can
learn the current error status of the DocuShare Client. This does not apply If
SVRMAP_OPTION_STANDALONE is used.

DocuShare Windows Client SDK 4–57

Objects DSServerMap Library

FolderHandle

VB Property FolderHandle As Long

C++ long IServer::GetFolderHandle()

void IServer::SetFolderHandle(long nNewValue)

Access Read/Write

FolderHandle contains the handle number of a DocuShare collection if FolderType is that of collection
DSXITEMTYPE_COLLECTION. If FolderType is that of server DSXITEMTYPE_SERVER, FolderHandle
contains the database index number of the server map that this Server object represents.

Remarks
The value of the property is automatically set and should not be modified. If
SVRMAP_OPTION_STANDALONE is used, FolderHandle can contain any value that the application
desires.

FolderType

VB FolderType As Integer

C++ short GetFolderType();

void SetFolderType(short nNewValue);

Access Read/Write

FolderType denotes the container type of Server. It can be either DSXITEMTYPE_SERVER or

DSXITEMTYPE_COLLECTION.

Remarks
The value of this property is automatically set when the Server object is loaded from the server database
via a call to Store.Load. Unless SVRMAP_OPTION_STANDALONE is used, an SDK application should
not modify the value. See FolderHandle on page 4–58.

4–58 DocuShare Windows Client SDK

DSServerMap Library Objects

GuestAccess

VB Property GuestAccess As Long

C++ long IServer::GetGuestAccess()

void IServer::SetGuestAccess(long nNewValue)

Access Read/Write

GuestAccess is True if the server map represents a guest account. A guest account is not permitted to
perform any modifying operation against a DocuShare resource.

Remarks
Set this property to True before calling the Open method to open a gateway without user credentials.

An SDK application can use the following script to open a gateway for a guest account.

myServer.DocuShareAddress = "http://my.xyz.com/"
myServer.GuestAccess = True
status myServer.Logon
if status = 0 then
set gateway = myServer.Open
...
end if
The Logon method must be called prior to the Open call.

DocuShare Windows Client SDK 4–59

Objects DSServerMap Library

HostServer

VB HostServer As Long

C++ long GetHostServer();

void SetHostServer(long nNewValue);

Access Read/Write

HostServer contains the InstanceId of another server map if this Server object represents a mapped
collection. The server map referenced by HostServer represents the host DocuShare server containing the
mapped collection.

Remarks
HostServer is set to zero if the Server object represents a server. If HostServer is not zero, FolderType is
DSXITEMTYPE_COLLECTION, and FolderHandle contains the collection handle. If a mapped collection
does not have a host server map, HostServer can be set to zero.

When either the Logon or Logoff methods of a Server object representing a mapped collection is called,
the method delegates the call to the host Server object for actual logon or logoff processing. The mapped
collection uses the user credentials of the host server object to authenticate any DocuShare access. For
example, calling Logon for a mapped collection automatically opens a session for the host server object;
conversely, logging onto a server that hosts mapped collections, will automatically authenticate the user to
access any of the mapped collections.

Assuming that myStore is a valid loaded Store object and hostServer is a valid server object, you can use
the following script to create a collection map.

dim mappedColl
set mappedColl = CreateObject("DSServerMap.Server")
mappedColl.HostServer = hostServer.InstanceId
status = hostServer.CopyTo(mappedColl)
mappedColl.FolderType = DSXITEMTYPE_COLLECTION
mappedColl.FolderHandle = 123 ' Representing Collection-123
mappedColl.Name = "Mapped collection for quick access to my files"
status = myStore.Add(mappedColl)
if status = 0 then
status = myStore.Save
if status = 0 then
mappedColl.BroadcastEvent(SVRMAP_EVENT_ADD)
end if
end if

4–60 DocuShare Windows Client SDK

DSServerMap Library Objects

Icon

VB Icon(asOpenForm As Long, asSmallForm As Long) As Object

C++ LPDISPATCH GetIcon(long asOpenForm, long asSmallForm);

Access Read-only

The Icon property obtains an icon picture associated with the Server object.

Parameters

Parameter Description

OpenForm TRUE to receive a server icon for the opened

folder state. FALSE to receive an icon for the
closed folder state.

SmallForm TRUE to receive a server icon in the 16 pixel by 16

pixel icon format. FALSE to receive an icon in the
32 pixel by 32 pixel icon format.

Remarks
If the Server object represents a server map, the icon shows a cabinet. If it represents a collection map, the
icon shows overlapping folders.

To show the icon in Visual Basic, you can use a PictureBox control. If serverIcon is a PictureBox control in
a Visual Basic form, this assignment displays a 32x32 pixel icon of an opened cabinet.

serverIcon.Picture = myServer.Icon(True, False)

DocuShare Windows Client SDK 4–61

Objects DSServerMap Library

Instanceld

VB InstanceId As Long

C++ long GetInstanceId();

void SetInstanceId(long nNewValue);

Access Read/Write

If the server object is created as a standalone, InstanceId is a numeric identifier that uniquely identifies the
instance of a server object. If the server object was obtained from a server store, the server map it
represents is identified by its unique InstanceId.

Remarks
InstanceId is generated once when the server object is created.

dim server1
set server1 = CreateObject("DSServerMap.Server")
At this point, server1.InstanceId has a unique value. Since server1 does not belong to a server store, its
InstanceId uniquely identifies the in-memory instance of server1.

The value of InstanceId for a mapped server or collection loaded from a Store object is automatically set to
the persistent server map identifier stored in the server database.

dim store
set store = CreateObject("DSServerMap.Store")
status = store.Load
store.Reset
dim server2
set server2 = store.NextItem
store.Reset
dim server3
set server3 = store.NextItem
Since server2 and server3 are obtained as the first item from a store object, they both have the same
InstanceId although their in-memory instances are different. They are merely two copied instances of the
first server map of the store.

An SDK application should not modify the InstanceId in a server object obtained by this way.

4–62 DocuShare Windows Client SDK

DSServerMap Library Objects

IsLoggedOn

VB IsLoggedOn As Long

C++ long GetIsLoggedOn();

Access Read-only

IsLoggedOn property is a flag value. If the server is currently logged in, the value is 1; if the server is not
logged in, the value is 0.

Remarks
Whenever this property is referenced, the stated information of the server object is synchronized with the
server database. For example, if your SDK application did not call the Logon method for the server,
DocuShare Client executing a successful call to Logon, IsLoggedOn property returns True. The
synchronization with a server database is not performed if the SVRMAP_OPTION_STANDALONE option
is enabled.

You do not need to inspect the value of IsLoggedOn to skip a Logon call. The Logon method internally
references IsLoggedOn. If IsLoggedOn returns True, the method does not run the logon dialog and returns
immediately.

Functionally, the single statement, status = server.Logon, is equivalent to the following statement block:

status = 0
if server.IsLoggedOn = False then
status = server.Logon
end if

IsProtected

VB Property IsProtected As Long

C++ long GetIsProtected();

Access Read-only

IsProtected is set to True if the associated server database is protected with regard to a write operation
against the server object.

Remarks
This property set to True, indicates that a write operation is in progress. For example, the Protect method
for the server object has been called but its Unprotect method has not been called. An SDK application
should inspect this property prior to calling the Protect and Save methods. If the property yields True, the
application should not engage in a save operation.

DocuShare Windows Client SDK 4–63

Objects DSServerMap Library

IsSelected

VB IsSelected As Long

C++ long GetIsSelected();

void SetIsSelected(long nNewValue);

Access Read/Write

IsSelected property is a flag value. If the server has been marked as selected, the value is 1; if not
selected, the value is 0.

Remarks
There are two ways in which the server IsSelected property can be set:

• Use the DoSelectDialog on page 4–7 method.

• Set the IsSelect property programmatically.

LastError

VB Property LastError As Long

C++ long GetLastError();

void SetLastError(long nNewValue);

Access Read/Write

LastError holds an error code that the server object last encountered.

Remarks
The Server.Logon methods update the value of the LastError property. If a network or server error was
detected during logon processing, LastError is set to the error code that may be a Windows socket or
HTTP error code. For example, LastError can be set to 401 for an HTTP authorization error if the user has
not supplied a correct password.

The Compare method, with the flags parameter set to SVRMAP_COMPARE_STATUS, compares the
values of LastError between two server objects if both have the same stated information such as
IsLoggedOn, ReadOnly, or GuestAccess.

The DocuShare Client uses LastError to attach any detected network error to the server object.

4–64 DocuShare Windows Client SDK

DSServerMap Library Objects

MapIndex

VB MapIndex As Integer

C++ short GetMapIndex();

void SetMapIndex(short nNewValue);

Access Read/Write

MapIndex is the server database index to the server map. FolderHandle contains the same value as
MapIndex if FolderType is DSXITEMTYPE_SERVER. If the server object is standalone, MapIndex is set to
zero and carries no meaning.

Remarks
For a standalone server object, an SDK application can use MapIndex for a private purpose. For a server
object of a shared server map, MapIndex should not be modified.

Name

VB Property Name As String

C++ CString GetName();

void SetName(LPCTSTR lpszNewValue);

Access Read/Write

Name identifies the server map. Name is not necessarily unique across all available server maps as is
InstanceId.

Remarks
Whenever the Name property is modified, BroadcastEvent should be called with the flags parameter set to
SVRMAP_EVENT_RENAME. The notification is sent to the DocuShare Client so that the latter can update
its display.

DocuShare Windows Client SDK 4–65

Objects DSServerMap Library

Options

VB Options As Long

C++ long GetOptions();

void SetOptions(long nNewValue);

Access Read/Write

The Options property controls Server behavior for certain methods and properties.

Remarks

Flag Option Description

SVRMAP_OPTION_CANCHANGEADDR Address can be changed.

SVRMAP_OPTION_CANCHANGEUSER Username can be changed.

SVRMAP_OPTION_COPYCRED Copy credentials.

SVRMAP_OPTION_COPYNOIDENTIFY Do not copy identities (name, type, and handle).

SVRMAP_OPTION_COPYPRIV Copy private parameters, such as InstanceId.

SVRMAP_OPTION_COPYSTATE Copy all session state settings.

SVRMAP_OPTION_LOGOFFSILENT Do not ask user.

SVRMAP_OPTION_LOGONLOADSCHEMA Directs servmap to load schema from DocuShare

server when servermap.Logon is called.

SVRMAP_OPTION_NOAUTOLOGON Disallows automatic logon.

SVRMAP_OPTION_NOLOGOFFNOTIFY Suppresses logoff notification.

SVRMAP_OPTION_NOLOGONNOTIFY Suppresses logon success notification.

SVRMAP_OPTION_NOLOGONRETRY Disallows retry.

SVRMAP_OPTION_OPENWITHOUTAUTH Open gateway even if not authenticated.

SVRMAP_OPTION_OVERRIDE CacheCredentials overrides authentication lock.

SVRMAP_OPTION_STANDALONE Collection map does not piggyback on host server

to authenticate user.

4–66 DocuShare Windows Client SDK

DSServerMap Library Objects

OwnerHwnd

VB OwnerHwnd As Long

C++ long GetOwnerHwnd();

void SetOwnerHwnd(long nNewValue);

Access Read/Write

The OwnerHwnd property, for data type HWND, contains the window handle for a window that owns the
server object.

Remarks
The Logon method uses the window handle to create the logon dialog box. The owner window becomes
the parent window of the dialog box. If OwnerHwnd is not set to a valid window handle, the Logon method
uses the window handle of a currently active window via a call to the Win32 function, GetActiveWindow.
The Logoff method also uses OwnerHwnd to create a message box to prompt the user.

A Visual Basic user cannot assign a value to this property. Instead, the Server object uses an active
window handle.

Param

VB Param As Long

C++ long GetParam();

void SetParam(long nNewValue);

Access Read/Write

The Param property can be used by an SDK application to store any 32-bit integer data.

Remarks
Param is IServer instance specific and not serialized into the server database.

DocuShare Windows Client SDK 4–67

Objects DSServerMap Library

Password

VB Password As String

C++ CString GetPassword();

void SetPassword(LPCTSTR lpszNewValue);

Access Read/Write

The Password property contains the password that is used by Logon and AuthenticateUser methods to
perform user authentication with DocuShare.

Remarks
User authentication requires the following properties:

• Username
• Password
• DocuShareAddress
• UseProxy (defaults to False)
• ProxyAddress (defaults to empty)
Password does not need to be set prior to calliing Logon. Logon runs a dialog to obtain a password from
the end user. However, Password is a required parameter that must be set prior to calling
AuthenticateUser.

ProgramFolder

VB ProgramFolder As String

C++ CString GetProgramFolder();

Access Read-only

The ProgramFolder is the folder where DSClientSDK and DSClient are installed.

Remarks
Typically, the folder is located at: C:\program files\xerox\dsclient

4–68 DocuShare Windows Client SDK

DSServerMap Library Objects

ProtocolScheme

VB ProtocolScheme As String

C++ CString GetProtocolScheme();

void SetProtocolScheme(LPCTSTR lpszNewValue);

Access Read/Write

The ProtocolScheme property contains the transport protocol scheme.

Remarks
Valid values are HTTP and HTTPS.

ProxyAddress

VB ProxyAddress As String

C++ CString GetProxyAddress();

void SetProxyAddress(LPCTSTR lpszNewValue);

Access Read/Write

The ProxyAddress property contains the URL for a proxy server.

Remarks
The UseProxy property toggles usage of the proxy server specified by ProxyAddress.

A valid example address is: http://myproxyserver.xyz.com:8000/

ProxyAuth

VB ProxyAuth as Boolean

C++ BOOL GetProxyAuth();

void SetProxyAuth( BOOL );

Access Read/Write

ProxyAuth determines if user authentication is enforced by the proxy server.

DocuShare Windows Client SDK 4–69

Objects DSServerMap Library

ReadOnly

VB ReadOnly As Long

C++ long GetReadOnly();

void SetReadOnly(long nNewValue);

Access Read/Write

ReadOnly property is set to True if DocuShare is in maintenance mode. Any modify operation, such as
upload, will fail.

Remarks
The ReadOnly property is set automatically when Logon or AuthenticateUser successfully concludes.

SessionFlags

VB SessionFlags As Long

C++ long GetSessionFlags();

void SetSessionFlags(long nNewValue);

Access Read/Write

The SessionFlags property provides DocuShare session and user account status information.

Remarks
The SessionFlags property, when referenced, updates its value with the server database. When an
assignment is made to it, SessionFlags updates the server database. This ensures that all running Server
instances share the same status information. An SDK application may reference SessionFlags to keep
itself in sync with the DocuShare Client. An SDK application should not modify the SessionFlags value.

The following properties of Server are linked to the SessionFlags property:

• MapIndex
• UseProxy
• WWWSecure
• WWWAuth
• IsLoggedOn
• ReadOnly
• LastError
• GuestAccess
An SDK application should use these properties to learn the current session status.

4–70 DocuShare Windows Client SDK

DSServerMap Library Objects

SHItemDescriptor

VB SHItemDescriptor as Variant

C++ VARIANT* SHItemDescriptor();

Access Read-only

Contains a shell item descriptor for the Server object.

DocuShare Windows Client SDK 4–71

Objects DSServerMap Library

ShortcutStore

VB ShortcutStore as Object Store

C++ IDispatch* GetShortcutStore();

Access Read-only

ShortcutStore contains a Store object that enumerates Server objects that represent shortcuts to
DocuShare collections.

Remarks
A Server object that represents a shortcut to a collection sets the SVRMAP_OPTION_SHORTCUT option
flag. A shortcut Server object does not support ShortcutStore. An attempt to delete the ShortcutStore
reference, causes an interface error to be raised. A Server object with the
SVRMAP_OPTION_STANDALONE option, does not support Shortcut.

Each time a ShortcutStore reference is removed, a different Store object is created.

set shortcuts1 = server.ShortcutStore

shortcuts1.Load
set shortcuts2 = server.ShortcutStore
In the script above, shortcuts1 has loaded available shortcuts, therefore, you can enumerate them.
However, shortcuts2 is a different instance and has not loaded the shortcuts. Shortcuts2 cannot
enumerate the shortcuts until its Load method is called.

Use the following Store methods and properties to perform enumeration tasks.

Methods and Properties Description

Add Adds a shortcut Server object to ShortcutStore.

Close Closes ShortcutStore. ShortcutStore is cleared of all

shortcut Server objects. Load must be called again
to enable access to a shortcut object.

Find Finds a shortcut Server object in ShortcutStore. The

Find flags supported are:
• SVRMAP_COMPARE_NAME
• SVRMAP_COMPARE_DSADDR
• SVRMAP_COMPARE_INSTANCEID
• SVRMAP_COMPARE_FOLDERHANDLE
• SVRMAP_COMPARE_FOLDERTYPE
• SVRMAP_FIND_NOBLANKSVR.

Length Contains a count of the shortcuts defined for the

server.

Load Loads shortcuts defined for the server.

4–72 DocuShare Windows Client SDK

DSServerMap Library Objects

Methods and Properties Description

Next Returns a shortcut Server object at the current

enumeration position and increments the position.

NextItem Contains a shortcut Server object.

NextPos Contains the enumeration position of the next

Server object.

Remove Removes a shortcut Server object from

ShortcutStore.

Reset Resets the ShortcutStore enumeration position.

Save Saves shortcuts defined for the server. Protect and

Unprotect calls are not necessary. These methods
simply return SVRMAP_RESULT_NOCHANGE.

An application does not need to call ShortcutStore.CanAdd to add a shortcut. ShortcutStore.CanAdd

always succeeds and returns SVRMAP_RESULT_NOCHANGE.

The following Store methods and properties are not supported by ShortcutStore.

Methods and Properties Description

BaseRegistryKey Always empty.

CanAdd Always returns SVRMAP_RESULT_NOCHANGE.

Clone Raises a COM exception (error code E_NOTIMPL).

DBAccessToken Always 0.

DoSelectDialog Always returns SVRMAP_RESULT_NOCHANGE.

No dialog is run.

IsProtected Always False.

LockCount Always 0.

Protect Always SVRMAP_RESULT_NOCHANGE.

SelectDialogOption Always 0.

Unprotect Always SVRMAP_RESULT_NOCHANGE.

DocuShare Windows Client SDK 4–73

Objects DSServerMap Library

TypeIndex

VB TypeIndex(asOpenForm As Long) As Long

C++ long GetTypeIndex(long asOpenForm);

Access Read-only

The TypeIndex property is linked to the Icon property and contains the value of an index to the Opened or
Closed server icon.

Parameters
asOpenForm—TRUE to obtain the index number of the Opened server icon. FALSE to obtain the index to
the Closed server icon.

Remarks
TypeIndex can be used to build an index table for caching server icons.

UseProxy

VB UseProxy As Long

C++ long GetUseProxy();

void SetUseProxy(long nNewValue);

Access Read/Write

If the proxy server, specified by ProxyAddress, is used to contact DocuShare (DocuShareAddress), the
UseProxy property is set to True.

Remarks
To use a proxy server, set ProxyAddress to the address value and set UseProxy to True. To switch off the
proxy usage, set UseProxy to False while keeping the address in ProxyAddress.

If UseProxy is set to True while ProxyAddress contains an empty value, the Logon and AuthenticateUser
methods disregards the UseProxy setting and proceeds with the authentication request.

4–74 DocuShare Windows Client SDK

DSServerMap Library Objects

UserHandle

VB UserHandle As Long

C++ long GetUserHandle();

void SetUserHandle(long nNewValue);

Access Read/Write

The UserHandle property contains the handle number for the DocuShare user associated with the Server
object.

Remarks
UserHandle is automatically set when Logon or AuthenticateUser is successfully called.

UserName

VB UserName As String

C++ CString GetUserName();

void SetUserName(LPCTSTR lpszNewValue);

Access Read/Write.

Remarks
None

UseWindowsAuth

VB UseWindowsAuth as Long

C++ BOOL GetUseWindowsAuth();

void SetUseWindowsAuth( BOOL );

Access Read/Write

UseWindowsAuth determines if the DocuShare NTLM-based auto login feature is enabled.

Remarks
SessionFlags raises the SVRMAP_SESSFLAG_WINLOGON flag if UseWindowsAuth is True.

AuthenticateUser and Logon clears Server.Password if UseWindowsAuth is True.

DocuShare Windows Client SDK 4–75

Objects DSServerMap Library

Version

VB Version As Long

C++ long GetVersion();

void SetVersion(long nNewValue);

Access Read/Write

The Version property contains the version number of a Docushare server that Login or AuthenticateUser
last contacted.

Remarks
Version is set to a valid DocuShare version only after a successful call to Login or AuthenticateUser.

The high word (16-bit integer) of Version refers to the major version number of DocuShare. The low word
refers to the minor version number.

WIPFolder

VB WIPFolder As String

C++ CString GetWIPFolder();

void SetWIPFolder(LPCTSTR lpszNewValue);

Access Read/Write

The WIPFolder property specifies the name of a subfolder created under the DocuShare Client pre-defined
work folders. The subfolder is specific to the server map that the Server object represents.

Remarks
WIPFolder is automatically set for a Server object loaded from a call to Store.Load. An SDK application
cannot modify the value if the server map belongs to the server database managed by the DocuShare
Client.

Refer to EnsureWIPFolderExist on page 4–43 method on work folders that DocuShare Client maintains.

4–76 DocuShare Windows Client SDK

DSServerMap Library Objects

WorkFolder

VB WorkFolder As String

C++ CString GetWorkFolder();

Access Read-only

The WorkFolder property contains the path to a work folder that an SDK application can use to store
temporary files.

Remarks
The path of WorkFolder is typically C:\program files\xerox\dsclient\work\tmp

The path setting can be edited using the Folder tab of the DocuShare Client Properties dialog. Refer to the
DocuShare Client Help.

WWWAuth

VB WWWAuth As Long

C++ long GetWWWAuth();

void SetWWWAuth(long nNewValue);

Access Read/Write

If the contacted DocuShare server uses the NTLM challenge/response protocol for user authentication, the
WWWAuth property is set.

Remarks
WWWAuth is automatically set to True after a successful call to Login or AuthenticateUser and the web
server is configured to use NTLM.

WWWSecure

VB WWWSecure As Long

C++ long GetWWWSecure();

void SetWWWSecure(long nNewValue);

Access Read/Write

The WWWSecure property is set if the contacted DocuShare server uses a secure HTTP connection.

Remarks
WWWSecure is automatically set after a successful call to Login or AuthenticateUser and the web server
is configured to use secure HTTP connections.

DocuShare Windows Client SDK 4–77

Objects DSServerMap Library

4.2.5 CheckinServiceManager
List of CheckinServiceManager methods.

Methods and Properties

IsCheckinFormRequired

OpenUIService

4.2.5.1 CheckinServiceManager methods

OpenUIService

VB OpenUIService( TaskId as String, ServiceId as optional Variant ) as Object

C++ IDispatch* OpenUIService( LPCTSTR TaskId, VARIANT* ServiceId );

Opens a UI service which can be used to run a dialog for checking an item in DocuShare.

IsCheckinFormRequired

VB IsCheckinFormRequired( TaskId as String, ItemsToCheckIn as optional Variant,

AllowSubclass as optional Variant ) as Boolean

C++ BOOL IsCheckinFormRequired( LPCTSTR TaskId, VARIANT*

ItemsToCheckIn, VARIANT* AllowSubclass );

Determines if an item to be checked into DocuShare has a required custom property, or if a custom type is
defined for the item, a check-in dialog is run and the required properties values are prompted for input from
the end user.

4.2.5.2 CheckinServiceManager properties

There are no properties defined for this object.

4–78 DocuShare Windows Client SDK

DSServerMap Library Objects

4.2.6 PropCollection
List of PropCollection methods and properties

Methods and Properties

Add NextItem

Close Next

Find NextPos

ID Remove

Length Reset

Load Save

Name

4.2.6.1 PropCollection methods

This section contains the PropCollection method definitions.

Add

VB Add(ID as string) as CustomProp

C++ IDispatch* Add( LPCTSTR ID );

Creates a custom property and attaches it to the collection.

Parameters
ID—contains a unique identifier for a custom property to be added.

Return value
If the method succeeds, the return value is a CustomProp object with its ID property set to ID.

Remarks
The method does not affect the current enumeration position.

DocuShare Windows Client SDK 4–79

Objects DSServerMap Library

Close

VB Close() as long

C++ long Close();

Closes the property collection. All CustomProp objects are removed from the PropCollection enumerator.

Return value
If the method succeeds, the return value is SVRMAP_RESULT_SUCCESS (0). If the method fails, the
return value is a non-zero error code.

Remarks
The enumeration position is reset to -1.

Find

VB Find(ID as string) as CustomProp

C++ IDispatch* Find( LPCTSTR ID );

Find locates a custom property by property ID.

Parameters
ID—contains a unique identifier for a custom property search.

Return value
If the method succeeds, the return value is a CustomProp object ID that matches the input ID. If the
method fails, the return value is NULL.

Remarks
Find is case-sensitive.

4–80 DocuShare Windows Client SDK

DSServerMap Library Objects

Load

VB Load()

C++ Load() as long

Loads the collection of CustomProp objects from persistent storage.

Parameters
None

Return value
If the method succeeds, the return value is SVRMAP_RESULT_SUCCESS (0). If the method fails, the
return value is a non-zero error code defined in the Windows Platform SDK (refer to WinError.h”).

Remarks
The enumeration position is set to -1. To start enumeration, make sure that the Reset method is called first.

DocuShare Windows Client SDK 4–81

Objects DSServerMap Library

Next

VB Next(Result as long) as CustomProp

C++ IDispatch* Next( long* Result );

Next retrieves the next CustomProp object. This method has a hidden attribute.

Parameters
Result - [out], a result code, is placed in this parameter on return from the method. A result code of 0
means a CustomProp object was successfully retrieved and the enumeration position was updated to point
to the next object. A result code of ERROR_NO_MORE_ITEMS means no more objects exist. The method
may return a valid CustomProp.

Return value
A valid CustomProp object if the method succeeds. A NULL if not.

This C++ code uses the Next method to perform enumeration of a custom property collection and prints
the names of the properties.

IPropCollection* pc;
pServer->get_CustomProps(L"MySpecialProps", &pc);
long status;
pc->Load(&status);
pc->Reset(&status);
while (status == 0) {
lICustomProp* cprop;
pc->Next(&status, &cprop);
BSTR name = NULL;
cprop->get_Name(&name);
puts(name);
SysStringFree(name);
cprop->Release();
}
pc->Release();

4–82 DocuShare Windows Client SDK

DSServerMap Library Objects

Remove

VB Remove(ID as string)

C++ void Remove( LPCTSTR ID );

Removes a custom property from the collection.

Parameters
ID—contains a unique identifier for a custom property to be removed.

Return value
None

Remarks
The method does not affect the current enumeration position.

Reset

VB Reset() as long

C++ long Reset();

Reset moves the enumeration position to the first item.

Return value
Non-zero if the method succeeds; zero, if no item exists in the collection.

Save

VB Save() as long

C++ long Save();

Saves the collection of CustomProp objects in persistent storage.

Parameters
None

Return value
If the method succeeds, the return value is SVRMAP_RESULT_SUCCESS (0). If the method fails, the
return value is a non-zero error code defined in the Windows Platform SDK (refer to WinError.h").

DocuShare Windows Client SDK 4–83

Objects DSServerMap Library

4.2.6.2 PropCollection properties

This section contains the PropCollection property definitions.

ID

VB ID as string

C++ CString GetID();

void SetID( LPCTSTR );

Access Read/Write

Contains the unique identifier for a custom property collection.

Remarks
Server.CustomProps uses PropCollection.ID to locate a specified collection of custom properties.

Length

VB Length as long

C++ long GetLength();

Access Read-only

Counts the number of CustomProp objects attached to a PropCollection enumerator.

Name

VB Name as string

C++ CString GetName();

void SetName( LPCTSTR );

Access Read/Write

Contains the display name of a property collection.

4–84 DocuShare Windows Client SDK

DSServerMap Library Objects

NextItem

VB NextItem as CustomProp

C++ IDispatch* GetNextItem();

Access Read-only

Contains the next CustomProp object if one is available. If not, NextItem is empty.

Remarks
Check the value of NextPos before referencing NextItem. NextPos contains a non-zero if NextItem
contains a valid ItemProp object.

set propColl = server.CustomProps("MySpecialProps")

propColl.Load
propColl.Reset
while propColl.NextPos <> 0
set propObj = propColl.NextItem
...
wend

NextPos

VB NextPos as long

C++ long GetNextPos();

Access Read-only

Contains the next enumeration position if another CustomProp object is available. If not, NextPos is zero.

DocuShare Windows Client SDK 4–85

Objects DSServerMap Library

4.2.7 CustomProp
List of CustomProp methods and properties

Methods and Properties

Attribute

Description

Flags

ID

Name

Value

4.2.7.1 CustomProp methods

There are no methods defined for this object.

4.2.7.2 CustomProp properties

Attribute

VB Attribute(Name as string) as string

C++ CString GetAttribute( LPCTSTR Name );

void SetAttribute( LPCTSTR Name, LPCTSTR );

Access Read/Write

Contains the value of a named attribute for a custom property.

Parameters
Name—contains an attribute name.

4–86 DocuShare Windows Client SDK

DSServerMap Library Objects

Description

VB Description as string

C++ CString GetDescription();

void SetDescription( LPCTSTR );

Access Read/Write

Contains the description for a custom property.

Flags

VB Flags as long

C++ long GetFlags();

void SetFlags( long );

Access Read/Write

Contains the control settings associated with a custom property.

Remarks
The meaning of a control setting depends on the application. It is the application that decides how to use
the Flags property. The DSClient SDK does not define any setting.

DocuShare Windows Client SDK 4–87

Objects DSServerMap Library

ID

VB ID as string

C++ CString GetID();

void SetID( LPCTSTR );

Access Read/Write

Contains the unique identifier of a custom property defined for a server map.

Remarks
The PropCollection.Find method utilizes CustomProp.ID to search for a particular property.

Name

VB Name as string

C++ CString GetName();

void SetName( LPCTSTR );

Access Read/Write

Contains the display name for a custom property.

Value

VB Value as string

C++ CString GetValue();

void SetValue( LPCTSTR );

Access Read/Write

Contains the value for a custom property.

4–88 DocuShare Windows Client SDK

 DSItemEnumLib Library
This chapter contains the following:

• Object model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–2

• Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–4
• Compound document support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–176

DocuShare Windows Client SDK 5–1

Object model DSItemEnumLib Library

5.1 Object model

DSItemEnumLib Method or property used to derive

an object precedes the name of
the object in italics.

ItemObj

EnumObjects
EnumObj

SchemaEnumerator
(EnumSchema)

NextItem
ItemSchema

Server
DSServerMap.Server

PropsEnumerator
EnumSchemaProps

NextItem
SchemaProp

EnumProps
EnumItemProps

NextItem
ItemProp

ItemObject
ItemObj

ItemSchema
ItemSchema

EnumPropValues
EnumPropValues

NextItem
PropValue

5–2 DocuShare Windows Client SDK

DSItemEnumLib Library Object model

Object model continued

ErrorReportObj

ReplacedItemHandle
NameConflictResolver

StatusObj

XMLDOM
XLMDOMDocument

Server
DSServerMap.Server

OpenGateway
GatewayHandler

ParentItemObject
ItemObj

ContainerItemObject
ItemObj

AlternateRendition
ItemObj

PreferredRendition
ItemObj

CompoundContainer
ItemObj

ReferrerItemObject
ItemObj

EnumObj

NextItem
ItemObj

DocuShare Windows Client SDK 5–3

Objects DSItemEnumLib Library

5.2 Objects
5.2.1 ItemObj
List of ItemObj methods and properties

Methods Properties

Attach SchemaEnumerator

AttachGateway DSErrorCode

AttachParents DSGatewayMode

CancelTask DSServerMapld

Compare Reload

CopyTo Abstract

CreateObject AccessControlGrants

DetachGateway AlternateRendition

DSCopy Author

DSCreate AutoDelete

DSDelete BackgroundImage

DSDownload BaseType

DSEdit BaseTypeNum

DSFind ClientProp

DSLoadChildren CopyTo

DSLoadProps CompoundContainer

DSLock ContainerItemObject

DSMove Contents

DSSaveProps CorePropIds

DSSelect CustomProp

DSUpload Data

GetPropStruct Description

GetStateInfo ExcludedCoreProps

IsChildOf ExcludedProps

LoadDefaultProps Filename

OpenGateway Handle

5–4 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

Methods Properties

PreloadCustomProps HandleNum

SaveDefaultProps HighestVersionUsed

SetPropStruct Icon

UpdateLinks IsContainer

EnumObjects IsCustomType

EnumPresets IsLocked

EnumProps IsPrivate

IsReadOnly

Keywords

Length

LocalProp

LockedBy

LockedByNum

Logo

MaxVersions

MimeType

ModifiedBy

ModifiedbyNum

Name

ObjectTypeNum

Options

Owner

OwnerNum

Parent

ParentCount

ParentHandle

ParentHandleNum

ParentItemObject

ParentType

ParentTypeNum

PreferredRendition

DocuShare Windows Client SDK 5–5

Objects DSItemEnumLib Library

Methods Properties

Picture

Prop

PropIds

ReferrerItemObject

RequiredPropsAreSet

Server

SortOrder

StatusObj

Summary

TaskStatus

Thumbnail

TimeAccessed

TimeCreated

TimeModified

Title

Type

TypeId

TypeIndex

TypeNum

URL

User

UserNum

ValidatedFileHandle

VersionNum

5–6 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

5.2.1.1 ItemObj methods

This section contains the ItemObj method definitions.

Attach

VB Attach(pItemObj As ItemObj) As Long

C++ long Attach(LPDISPATCH pItemObj);

The Attach method attaches an existing item object to the current ItemEnum object.

Parameters
pItemObj—a ItemObj object. The ItemObj object needs to be valid.

Return value

Value Description

NO_ERROR The method was successful.

ERROR_OUTOFMEMORY The system has insufficient memory resources.

ERROR_INVALID_PARAMETER An invalid ItemEnum was passed to the method.

DocuShare Windows Client SDK 5–7

Objects DSItemEnumLib Library

AttachGateway

VB AttachGateway(pGatewayDisp as Object, [bAutoRelease As Boolean = True])

C++ void AttachGateway(LPDISPATCH pGatewayDisp, BOOL bAutoRelease);

The AttachGateway method attaches a DSGateway.GatewayHandler object to an ItemObj.

Parameters

Parameter Description

pGatewayDisp A valid gateway object.

bAutoRelease Determines if the gateway object is released after

releasing ItemObj. A value of True causes the
attached gateway object reference count to be
incremented before the method returns and the
count to be decremented when ItemObj is
destroyed—as an example, the object goes out of
scope. A value of False leaves the gateway object
reference count untouched. Use a value of True
when performing an asynchronous operation.

Return value
None

Remarks
The True value in this instance is for C/C++. The values correspond to TRUE = 1, and FALSE = 0. In Visual
Basic True = -1 and False = 0. Only the C/C++ Boolean definitions are valid for this interface.

5–8 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

AttachParents

VB AttachParents(pEnumDisp As Object) As Long

C++ long AttachParents(LPDISPATCH pEnumDisp);

The AttachParents method attaches a list of parent items.

Parameters
pEnumDisp—a ItemEnum object that contains a list of valid parent handles.

Return value

Value Description

NO_ERROR The method was successful.

ERROR_OUTOFMEMORY The system has insufficient memory resources.

ERROR_INTERNAL_ERROR An unknown internal error occurred performing

this operation.

DocuShare Windows Client SDK 5–9

Objects DSItemEnumLib Library

CancelTask

VB CancelTask() as Long

C++ long CancelTask();

CancelTask cancels an on-going asynchronous DocuShare task.

Parameters

Return value

Value Description

DSAXES_SUCCESS A task was successfully terminated.

DSAXES_NOCONNATTEMPT No task is in progress.

DSAXES_E_FAIL The gateway interface raised an error.

Remarks
An asynchronous task is started by a DocuShare accessing method, such as DSUpload, with
DSGatewayMode containing the mode flags, DSAXES_MODE_ASYNCHRONOUS or
DSAXES_MODE_SYNCTHREAD.

Here is a sample script that starts a background upload task and uses CancelTask to terminate the task if
a cancelation by a user is detected.

set collObj = server.CreateObject("Collection-10")

set fileObj = collObj.CreateObject("File")
fileObj.Name = "c:\doc\proposal.doc"
fileObj.DSGatewayMode = fileObj.DSGatewayMode or _
DSAXES_MODE_SILENT or _
DSAXES_MODE_ASYNCHRONOUS
status = fileObj.DSUpload
if status = DSAXES_INPROG then
while fileObj.TaskStatus = DSAXES_INPROG
'
' do something useful here while waiting.
'
if UserCanceled then
fileObj.CancelTask
end if
wend
status = fileObj.TaskStatus
end if

5–10 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

Compare

VB Compare(pItemObj As IttemObj, lFlags As Long) As Long

C++ long Compare(LPDISPATCH pItemObj, long lFlags);

The Compare method compare properties to those of another item.

Parameters

Parameter Description

pItem A ItemObj that will be compared to the current

ItemObj.

lFlags The flags are used to select properties that will be

compared between the two ItemObj.

NOTE: Comparison flags may be ORs to perform multi-criteria comparisons.

IFlags Description

ITEMOBJ_COMPARE_COLL_ALL Compares all the properties between two

collections.

ITEMOBJ_COMPARE_FILE_ALL Compares all the properties between two files.

ITEMOBJ_COMPARE_TYPE Compares the ItemObj types.

ITEMOBJ_COMPARE_HANDLE Compares the ItemObj handles.

ITEMOBJ_COMPARE_PARENT Compares the ItemObj parents.

ITEMOBJ_COMPARE_LENGTH Compares the number of collection items and the

document file sizes.

ITEMOBJ_COMPARE_OWNER Compares each ItemObj owner property by the

owner’s numeric handle.

ITEMOBJ_COMPARE_USER Compares the last modifier of the ItemObj by the

user's numeric handle.

ITEMOBJ_COMPARE_OWNERNAME Compares the ItemObj owners by the owners’

string name.

ITEMOBJ_COMPARE_USERNAME Compares the last modifier of the ItemObj by the

user's string name.

ITEMOBJ_COMPARE_TITLE Compares the ItemObj titles.

ITEMOBJ_COMPARE_SUMMARY Compares the ItemObj summary text.

ITEMOBJ_COMPARE_FILENAME Compares the ItemObj filenames.

DocuShare Windows Client SDK 5–11

Objects DSItemEnumLib Library

IFlags Description

ITEMOBJ_COMPARE_MIMETYPE Compares the ItemObj mime types.

ITEMOBJ_COMPARE_CREATETIME Compares the ItemObj creation dates.

ITEMOBJ_COMPARE_MODIFYTIME Compares the ItemObj modification times.

ITEMOBJ_COMPARE_VERSION Compares the ItemObj versions.

ITEMOBJ_COMPARE_KEY2_TYPE Secondary key = item type

ITEMOBJ_COMPARE_KEY2_HANDLE Secondary key = item handle

ITEMOBJ_COMPARE_KEY2_PARENT Secondary key = parent handle

ITEMOBJ_COMPARE_KEY2_LENGTH Secondary key = length

ITEMOBJ_COMPARE_KEY2_OWNER Secondary key = owner name

ITEMOBJ_COMPARE_KEY2_USER Secondary key = username

ITEMOBJ_COMPARE_KEY2_TITLE Secondary key = title

ITEMOBJ_COMPARE_KEY2_NAME Secondary key = filename

ITEMOBJ_COMPARE_KEY2_CREATE Secondary key = creation time

ITEMOBJ_COMPARE_KEY2_MODIFY Secondary key = modified time

ITEMOBJ_COMPARE_CASESENS Case sensitive comparison

ITEMOBJ_COMPARE_VALIDATED Use validated filename

ITEMOBJ_COMPARE_REVERSE Reverse order

Return value
Zero—ItemObjs were compared to have no differences for the criteria tested. A non-zero return signifies
an unequal comparison.

5–12 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

CopyTo

VB CopyTo(pItemObj As ItemObj, nNextLevel As Long) As Long

C++ long CopyTo(LPDISPATCH pItemObj, long nNextLevel);

The CopyTo method copies the properties of one ItemObj to another ItemObj.

Parameters

Parameter Description

pItemObj The target ItemObj for the copy operation.

nNextLevel Reserved—must be set to value 0.

Return value

Value Description

NO_ERROR The method was successful.

ERROR_OUTOFMEMORY The system has insufficient memory resources.

ERROR_INVALID_PARAMETER An invalid ItemEnum object was passed to this

method.

DocuShare Windows Client SDK 5–13

Objects DSItemEnumLib Library

CreateObject

VB CreateObject(bstrHandle As String) As Object

C++ LPDISPATCH CreateObject(LPCTSTR bstrHandle);

The CreateObject method creates a child object of the type designated in a passed string.

Parameters
bstrHandle—the object handle to be created. The handle may be a valid DocuShare handle or a valid
DocuShare type specifier. The valid types are:

Bulletin Collection SavedQuery User

BulletinBoard File Server

Calendar Group URL

Return Value
This function returns an IDispatch pointer to a created IItemObj interface object.

Remarks
The method is applicable to item objects for container types only. They are Server, Collection,
BulletinBoard, and SavedQuery.

If the DocuShare handle is known for a DocuShare item, the handle can be given to CreateObject.
Assuming that myCollection was instantiated elsewhere and represents a valid DocuShare collection, the
following code creates an item object representiing File-123 which appears in the DocuShare collection.

dim fileObj
set fileObj = myCollection.CreateObject("File-123")
If a generic file object is desired, the handle number is omitted. The following statement creates a generic
file object whose HandleNum is set to zero.The HandleNum property can be set to a valid DocuShare
handle number at a later time.

dim fileObj
set fileObj = myCollection.CreateObject("File")
It should be kept in mind that an ItemObj created with this method does not create the method on the
attached DocuShare server. The created object is only located within local memory.

5–14 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

DetachGateway

VB DetachGateway() as Object

C++ LPDISPATCH DetachGateway();

The DetachGateway method detaches the current ItemObj gateway object. The object is returned from this
method call.

Parameters
None

Return value
Returns a Gateway object upon call completion.

DocuShare Windows Client SDK 5–15

Objects DSItemEnumLib Library

DSCopy

VB DSCopy( pDestItem As ItemObj) As Long

C++ long DSCopy(LPDISPATCH pDestItem);

The DSCopy method makes a reference or contents copy of the DocuShare item represented by the
current ItemObj object. The destination collection must be on the same server as that of the source item for
reference copy. The destination can be located on a different server for contents copy.

Parameters
pDestItem—an ItemObj representing a valid DocuShare collection either on the same DocuShare server
or on a seperate DocuShare server.

Return value

Value Description

DSAXES_SUCCESS The method was successful.

DSAXES_E_CANCEL The operation was canceled by the user.

DSAXES_E_SERVDOWN Either the target or source server was down.

DSAXES_E_LOGIN_REFUSED Login validation to either server was denied.

DSAXES_E_LOGIN The operation failed due to a general login failure.

DSAXES_E_SYSRES The operation failed due to system resource

limitations.

DSAXES_E_BADSEL The operation attempted to copy an invalid

ItemObj. Only documents and collections are
allowed.

DSAXES_E_BADPARAM One of the ItemObj contains an invalid property

value.

DSAXES_E_BADLINK The operation failed to access a gateway

resource.

Remarks
DSCopy, by default, makes a reference copy of the source in the destination DocuShare collection.
Copying a reference implies that the same copied source item will appear in the destination collection. It
also means that the handle of the destination collection is added to the source item list of parents.

Reference copy is supported for all DocuShare standard item types.

• File
• Collection
• Calendar
• BulletinBoard

5–16 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

• SavedQuery
• URL
For reference copy, the destination collection must exist in the same server as that of the source item.
Otherwise, error DSAXES_E_BADSEL is returned.

For a reference-copied ItemObj, DSCopy updates the parent information. The method adds the destination
collection to the internal parent list of the ItemObj. Therefore, subsequent parent enumeration, such as
calling EnumObjects with DSCONTF_PARENT, yields a parent ItemObj that represents the destination
collection. The DSCopy call does not need to be followed by a DSLoadProps call to obtain updated parent
information. The value of ItemObj.Parent does not change after a call to DSCopy.

By setting the DSAXES_MODE_COPYCONTENTS flag in the DSGatewayMode property, DSCopy can be

instructed to perform contents copy. Contents copy is supported only for the following item types:

• File
• Collection
For contents copy, the DSAXES_MODE_CREATERESULTENUM mode flag can be specified in the
DSGatewayMode property. The flag instructs the method to generate an enumerator object for the result
items—original source items and copied target items. Refer to Moving, copying and deleting an item on
page 2–21 to enumerate the result items. The handle of a copied (target) item is stored in an enumerated
result item, while the handle of a source item is in the ReferrerItemObject property of the result item.

DocuShare Windows Client SDK 5–17

Objects DSItemEnumLib Library

DSCreate

VB DSCreate() As Long

C++ long DSCreate();

The DSCreate method creates an empty DocuShare item represented by the current ItemObj within the
designated server.

Parameters
These are the supported types of objects that can be created.

Value Objects

DSXITEMTYPE_COLLECTION Collection folder

DSXITEMTYPE_DOCUMENT Document

DSXITEMTYPE_CALENDAR Calender

DSXITEMTYPE_BBOARD Bulletin board

DSXITEMTYPE_URL URL link

DSXITEMTYPE_USER New user

Return value

Value Description

DSAXES_SUCCESS The method was successful.

DSAXES_INPROG Another request is in progress.

DSAXES_E_CANCEL The operation was canceled by the user.

DSAXES_E_LOGIN_REFUSED Login validation was denied by the server.

DSAXES_E_LOGIN The operation failed due to a general login failure.

DSAXES_E_CREATEFILE The operation was unable to create a temporary

local storage.

DSAXES_E_BUSY The gateway object was busy.

DSAXES_E_SYSRES The operation failed due to a system resource

failure.

DSAXES_E_BADPARAM The ItemObj properities were not adequately

defined to perform this operation. Ensure that all
necessary properties are initialized.

NOTE: Failure to have a gateway object attached

to the ItemObj also generates this error.

5–18 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

Value Description

DSAXES_E_HTTP The operation failed due to an HTTP protocol

error.

DSAXES_E_BADLINK The operation failed to access a gateway

resource.

Remarks
Depending on the type of current ItemObj object, the properties that are specified may differ. The table
below shows the dependency.

Item Type Supported Properties

Collection Title, Summary, Description, Keywords.

File All standard file and custom properties.

URL Title, Summary, Description, Keywords, and URL.

Calendar Title, Summary, Description, Keywords and

custom property-default scale.

Bulletin Board Title, Summary, Description, Keywords, and

custom property-expire.

User Custom properties for password, email,

first_name, last_name, mailstrop, phone,
homepage, and use_upload_helper.

To set standard properties not listed in the table and to set custom properties except for File, which
supports custom properties, follow the call to DSCreate with a call to DSSaveProps.

An ItemObj of type File may set the MimeType property to an appropriate MIME type. If the Windows
system installed on the client machine registers a template file for generating an empty file of a particular
file type, the DSCreate method uses the template file to generate an empty file in DocuShare. For
example, to generate an empty MS Word file, run this script.

dim file
set file = collection.CreateObject("File")
file.MimeType = "application/msword"
status = file.DSCreate
Collection is an ItemObj object that represents the target DocuShare collection where the empty file will be
created.

DocuShare Windows Client SDK 5–19

Objects DSItemEnumLib Library

DSDelete

VB DSDelete() As Long

C++ long DSDelete();

The DSDelete method deletes or disowns a DocuShare item represented by an ItemObj in a server. If the
item appears in one collection, DSDelete deletes the item. If the item appears in more than one collection,
DSDelete removes the item from the primary collection. The latter operation is regarded as disowning an
item.

Parameters
None

Return value

Value Description

DSAXES_SUCCESS The method was successful.

DSAXES_E_SERVDOWN The server is down.

DSAXES_E_BUSY The gateway object was busy.

DSAXES_E_FAIL An unknown failure occurred.

DSAXES_E_SYSRES The operation failed due to a system resource

failure.

DSAXES_E_BADSEL The operation attempted to delete an invalid

ItemObj.

DSAXES_E_BADPARAM The ItemObj contains an invalid property value.

DSAXES_E_BADLINK The operation failed to access a gateway

resource.

Remarks
The primary collection of an ItemObj is the collection referenced by the ItemObj.Parent property. If the
DocuShare item of an ItemObj object appears in a single collection (ItemObj.ParentCount), the DSDelete
method engages in deleting the item (item contents and properties).

However, if the ItemObj appears in more than one collection, a value greater than one in
ItemObj.ParentCount, DSDelete performs a disowning operation. The item is removed from the collection
identified by the ItemObj.Parent property.

NOTE: The parent information (IItemObj.Parent and IItemObj.ParentCount) that ItemObj holds, does
not change even after the disowning operation succeeded. The caller of DSDelete must
update the parent information by calling ItemObj.DSLoadProps.

5–20 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

DSDelete supports the following item types:

• Collection
• File
• Calendar
• BulletinBoard
• URL
• SavedQuery

DocuShare Windows Client SDK 5–21

Objects DSItemEnumLib Library

DSDownload

VB DSDownload(lFlags As Long) As Long

C++ long DSDownload(long flags);

The method downloads an object to a local file or directory. As an option, it can place a lock on the
downloaded object.

Parameters

Parameters Description

DSAXES_FLAG_DOWNLOADREPR Make the downloaded file a copy.

DSAXES_FLAG_DOWNLOADVALIDATE Verify that the download occurred.

DSAXES_FLAG_DOWNLOADLOCKED Place a lock on the downloaded file.

Return value

Value Description

DSAXES_SUCCESS The method was successful.

DSAXES_INPROG Another request is in progress.

DSAXES_E_CANCEL The operation was canceled by the user.

DSAXES_E_SERVDOWN The server is down.

DSAXES_E_BUSY The gateway object is busy.

DSAXES_E_SYSRES The operation failed due to a system resource

failure.

DSAXES_E_CREATEFILE The operation was unable to create a local file.

DSAXES_E_BADSEL The operation attempted to download an invalid

ItemObj.

DSAXES_E_BADPARAM The ItemObj contains an invalid property value.

DSAXES_E_BADLINK The operation failed to access a gateway

resource.

Remarks
DSDownload supports the following item types:

• File
• Version
• Collection

5–22 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

This VB script downloads a copy of a DocuShare file to a temporary path in the client machine.

dim file
set file = server.CreateObject("File-123")
file.Name = "c:\temp\test.doc"
status = file.DSDownload(0)
The script assumed that the file had a DocuShare file handle of File-123. The server object is a valid
IServer object representing a DocuShare server.

To download a specific version of a file, you can either set ItemObj.VersionNum to the desired version
number or create a version object using CreateObject with a version handle. For the former method, the
type of ItemObj can be either File or Version. The latter always generates a Version type ItemObj object.
The following script creates a version object for DocuShare file of File-123 version 4 and downloads the file
version.

dim fileVer
set fileVer = server.CreateObject("File-123/4")
fileVer.Name = "c:\temp\test_v4.doc"
status = fileVer.DSDownload(0)
For a File type ItemObj, the DSAXES_FLAG_DOWNLOADLOCKED flag can be used. DSDownload will
lock the file before downloading the file. The following VB script utilizes the flag to check out a file.
Following a successful download, the script opens the file with MS Word.

dim file
set file = server.CreateObject("File-456")
status = file.DSLoadProps
status = file.DSDownload(DSAXES_FLAG_DOWNLOADLOCKED)
if status = 0 then
dim msword
set msword = CreateObject("Word.Application")
msword.Visible = True
msword.Documents.Open(fileObj.Name)
end if
For a Collection type ItemObj, DSDownload downloads all files and sub-collections that appear in the
collection.

ItemObj.Name may contain a valid file pathname. For a File or Version download, the pathname should be
for a file. The pathname may or may not be for an existing file. If the file already exists, it will be overwritten
by the downloaded contents.

For a Collection download, the pathname may be for an existing folder. If the folder already exists, the
contents of the collection will be downloaded to the folder. If the folder does not exist, a folder will be
created.

DocuShare Windows Client SDK 5–23

Objects DSItemEnumLib Library

If the existing destination folder contains files and the filename of a downloaded file conflicts with an
existing file, DSDownload can run a dialog and ask the user whether or not to replace the existing file with
the downloaded contents. By default, DSDownload does not run the dialog and proceeds to make the
replacement. To run the dialog, set the DSAXES_MODE_DNLDNAMECLASHPROMPT flag in
ItemObj.DSGatewayMode.

If ItemObj.Name is empty, DSDownload generates a temporary path. The generated path is stored in
ItemObj.Name. Make sure the temporary file is deleted after it is no longer needed.

For a collection download, use the DSAXES_MODE_CREATERESULTENUM mode flag to generate an

enumerator object for the downloaded items. The ItemObj objects obtainable through the result
enumerator holds handle information only. You need to call DSLoadProps for each ItemObj if other
properties are needed.

The following VB script downloads a DocuShare collection and displays the names of the downloaded
items.

Dim collObj
Set collObj = server.CreateObject("Collection-123")
collObj.Name = "c:\temp\test"
collObj.DSGatewayMode = collObj.DSGatewayMode Or
DSAXES_MODE_CREATERESULTENUM
status = collObj.DSDownload(0)
if status = 0 then
dim downloadedList
set downloadedList = collObj.EnumObjects(DSCONTF_CHILDREN)
downloadedList.Reset
dim theList
while downloadedList.NextPos <> 0
dim downloadedItem
set downloadedItem = downloadedList.NextItem
theList = theList + downloadedItem.Handle + Chr(10)
' You may call downloadedItem.DSLoadProps to get all properties.
wend
MsgBox( "Downloaded total: " + CStr(downloadedList.Length) + Chr(10) +
theList)
end if

5–24 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

DSEdit

VB DSEdit() As Long

C++ long DSEdit();

The DSEdit method downloads, locks (optional), and opens a file for editing.

Parameters
None

Return value

Value Description

DSAXES_SUCCESS The method was successful.

DSAXES_E_SERVDOWN The server is down.

DSAXES_E_LOGIN_REFUSED Login validation by the server was denied.

DSAXES_E_BUSY The gateway object was busy.

DSAXES_E_FAIL An unknown failure occurred.

DSAXES_E_BADSEL The operation attempted to edit an invalid

ItemObj.

DSAXES_E_BADPARAM The ItemObj contains a property that was

inadequately or improperly defined to perform this
operation.

DSAXES_E_BADLINK The operation failed to access a gateway

resource.

Remarks
The DSEdit method requires installation of DocuShare Client. If the Client is not installed, error
DSAXES_E_BADLINK is returned.

DSEdit supports only File type. The ItemObj.DSServerMapId property must contain a valid
IServer.InstanceId. If the ItemObj was created by IServer.CreateObject, the property is automatically set to
a correct value.

If ItemObj.Name contains a valid pathname, DSEdit downloads a copy of the DocuShare file to the
indicated location. If ItemObj.Name is either invalid or empty, DSEdit assigns a temporary pathname to
ItemObj.Name and downloads the file copy there.

If ItemObj.IsReadOnly is set to False, DSEdit locks the file before downloading it from DocuShare.

DocuShare Windows Client SDK 5–25

Objects DSItemEnumLib Library

DSEdit opens the downloaded file with an editor application available in the client machine. DSEdit
determines which application to use based on the file type, such as file extension name or MIME type. For
example, if the filename contains a .doc extension, DSEdit launches MS Word if the application is
available. The DocuShare Client manages the associations between file types and editor applications. The
end user can reconfigure editor associations using the DocuShare Client Properties dialog. Refer to the
DocuShare Client Help for more information.

Once the file is successfully opened with an associated editor application, the DSEdit call should not
attempt to modify the file. The DocuShare Client owns the file and performs a check in to include unlocking
the file when the user closes the file, and the editor application releases it.

The following VB script uses DSEdit to check out a DocuShare file (File-123).

dim file
set file = server.CreateObject("File-123")
file.IsReadOnly = False
status = file.DSEdit
The server object is assumed to be a valid IServer object representing a DocuShare server.

5–26 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

DSFind

VB DSFind( Criteria as optional Variant ) as Long

C++ long DSFind( VARIANT* Criteria );

DSFind finds items that matches criteria in a collection or other container items or finds all items that
appear in the container item if no criteria is given.

Parameters
Criteria is optional. An ItemObj object specifies an item to be found. String, date, and other data types may
be specified in place of an ItemObj. If the parameter is omitted, all items that appear in the container item
are obtained. See Remarks for container types.

SDK version
The minimum Windows Client SDK version is 3.6.

The version number of the installed SDK can be obtained by referencing the Version property,
DSUtilityLib.HelperObj.

set helperObj = CreateObject( "DSUtilityLib.HelperObj" )

MsgBox CStr(helperObj.Version), , "DSClientSDK Version"

Return value

Value Description

DSAXES_SUCCESS An item was successfully found and stored in an

enumerator object. To retrieve the items found,
use ItemObj.EnumObjects
DSCONTF_CHILDREN.

DSAXES_E_BADSEL No items were found that matched the search

criteria or matched a name pattern specified in
ItemObj.Name of the search criteria. This return
value has an integer value of 1.

DSAXES_E_PARSEDATA Property data in parameter Criteria could not be

parsed.

DSAXES_E_BADLINK A gateway interface error occurred.

DSAXES_NOEXACTMATCH One or more items were found that partially

matched the search criteria.

DSAXES_E_SKIP The operation was skipped by a user in response

to a prompt. The caller should resume the
remaining operation. The user is prompted to
choose an action, such as overwrite a file with the
same name, and skip the current copy operation if
the DSGatewayMode flag,
DSAXES_MODE_UPLDNAMECLASHPROMPT
is set.

DocuShare Windows Client SDK 5–27

Objects DSItemEnumLib Library

Remarks
Valid container types are:

• Server
• Collection
• Calendar
• BulletinBoard
• Group
• SavedQuery
The Criteria parameter may contain any of the following data types:

• String—Specifies a value for DocuShare property <displayname>. The same value is used to set
the DocuShare property <document> if the container item is Collection.
• Date—Specifies a last modification date. Items, last modified since this date, will be found.
• ItemObj object—Contains restrictions in ItemObj properties.
Valid property settings are:

• ItemObj.Title—search by <displayname>
• ItemObj.Summary—search by <summary>
• ItemObj.Keywords—search by <keywords>
• ItemObj.Description—search by <description>
• ItemObj.Owner—search by <entityowner>
• ItemObj.User—search by <modified_by>
• ItemObj.TimeCreated—search by <creationdate> for items created between now and then
• ItemObj.TimeModified—search by <getlastmodified> for items last modified between now and then
• ItemObj.Name—search files by <document> or search users by <username>
• ItemObj.MimeType—search files by <getcontenttype>
• ItemObj.Author—search files by <author>
A restriction can also be specified by assigning to ItemObj.Prop([PropName]) a property value to base the
search. [PropName] is a DocuShare property name—for example, displayname. The following are
Example Prop specifications for restricting User search.

• ItemObj.Prop("username")—search users by <username>

• ItemObj.Prop("first_name")—search users by <first_name>
• ItemObj.Prop("last_name")—search users by <last_name>
• ItemObj.Prop("email")—search users by <email>
• ItemObj.Prop("phone")—search users by <phone>
• ItemObj.Prop("mailstop")—search users by <mailstop>

5–28 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

A few control settings can be specified using ItemObj.LocalProp.

• ItemObj.LocalProp("MaxHits")—SEARCH maximum number of hits. The default maximum is

10,000.
• ItemObj.LocalProp("QueryDepth")—SEARCH query depth. The default depth is 1.
• ItemObj.LocalProp("Conjunct")—AND for meeting all criteria or OR for meeting any of the criteria.
The default conjunct is AND.
If Criteria is not specified, the maximum number of items that can be retrieved is 10,000.

The following script uses DSFind to find and print out DocuShare users whose usernames start with joe.
Note that a global Group object, of handle Group-0, is used to do the search.

set groupObj = server.CreateObject("Group")

set userCriteria = server.CreateObject("User")
userCriteria.Prop("username") = "joe*"
if groupObj.DSFind(userCriteria) = DSAXES_NOEXACTMATCH then
set users = groupObj.EnumObjects( DSCONTF_CHILDREN )
users.Reset
while users.NextPos <> 0
set userObj = users.NextItem
Print userObj.Prop("first_name"), _
userObj.Prop("last_name"), _
userObj.Handle
wend
end if

DocuShare Windows Client SDK 5–29

Objects DSItemEnumLib Library

DSLoadChildren

VB DSLoadChildren() As Long

C++ long DSLoadChildren();

The DSLoadChildren method retrieves a listing of the contents in a collection or retrieves a listing of the
version files of a document.

Parameters
None

Return value

Value Description

DSAXES_SUCCESS The method was successful.

DSAXES_INPROG Another request is in progress.

DSAXES_NOITEMS The operation returned no items for the current

ItemObj.

DSAXES_E_CANCEL The operation was canceled by the user.

DSAXES_E_SERVDOWN The server is down.

DSAXES_E_BUSY The gateway object was busy.

DSAXES_E_SYSRES The operation failed due to a system resource

failure.

DSAXES_E_BADSEL The operation attempted to retrieve children for an

invalid ItemObj.

DSAXES_E_BADPARAM The ItemObj contains a property that was

inadequately or improperly defined to perform this
operation.

DSAXES_E_BADLINK The operation failed to access a gateway

resource.

Remarks
DSLoadChildren supports these item types: Server, Collection, and File.

• Server ItemObj—reloads the latest top-level collection listing for the represented DocuShare server.
• Collection ItemObj—reloads the latest list of items appearing in the represented collection.
• File ItemObj—reloads the latest version listing for the represented file.

5–30 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

To enumerate the found child items, use the following enumeration technique:

1. Call EnumObjects to obtain an item enumerator object representing the found item list.
2. Call Reset to bring the enumeration position to the beginning of the item list.
3. Iterate the found items by repeatedly inspecting the availability property, NextPos and obtaining
the next item from the property NextItem.
Here is a VB script that shows a simple enumeration for items found in a collection.

dim collection
set collection = server.CreateObject("Collection-123")
status = collection.DSLoadChildren
if status = 0 then
dim foundItems
set foundItems = collection.EnumObjects(DSCONTF_CHILDREN)
foundItems.Reset
while foundItems.NextPos <> 0
dim childItem
set childItem = foundItems.NextItem
if childItem.TypeNum = DSXITEMTYPE_DOCUMENT then
status = childItem.DSLock(True)
end if
wend
end if
Server is an IServer instance representing a DocuShare server. A child ItemObj of childItem obtained
through the enumerator object FoundItems can be used to call any DSxxx server accessing method that is
applicable to the child object. The above example called DSLock on a File object to lock all files that
appear in the collection.

Here is a script that lists the number of current versions for a DocuShare file.

dim file
set file = server.CreateObject("File-456")
status = server.DSLoadChildren
if status = 0 then
dim foundVersions
set foundVersions = file.EnumObjects(DSCONTF_CHILDREN)
MsgBox("File-456 has " + CStr(foundVersions.Length) + " versions")
end if
For more information on item enumeration, refer to IItemObj and Supported Item Types on page 2–5.

For an ItemObj of type Collection, DSLoadChildren updates the collection properties if the current ItemObj
representing the queried collection has a ParentCount of zero. If the ParentCount is not zero, it is assumed
that the collection properties are up-to-date and left untouched.

DocuShare Windows Client SDK 5–31

Objects DSItemEnumLib Library

For an ItemObj of type Server, DSLoadChildren updates the IsReadOnly property. If IsReadOnly is set to
False, the DocuShare server is accessible for a write operation. Otherwise, the server is in maintenance
mode and is only accessible for read operations.

A child ItemObj obtained from DSLoadChildren has these properties updated.

• Title
• Summary
• TimeCreated
• TimeModified
• Owner
• OwnerNum
• User
• UserNum
• Parent
• ParentCount
The EnumObjects method is available for each child ItemObj for obtaining an enumerator for the parent
items. EnumObjects for a child ItemObj is not capable of enumerating grandchild items. To query
grandchild items, DSLoadChildren is called against the child item.

The following child ItemObj types have additional properties set to the latest values in the server.

ItemObj Type Up-to-date Properties

Collection Length (number of contained items)

Server Length (number of top-level collections)

File Length (file size in bytes)

Name (filename)
MimeType, MaxVersions, IsLocked

Version Comment

URL URL

All other properties maintained by DocuShare servers are not loaded by DSLoadChildren. To load other
properties, call DSLoadProps for each of the found child items.

It is possible to modify the list of updated properties so that a single DSLoadChildren queries the child
items and retrieves all the necessary properties that an SDK application requires. For example, an
application wants to include property Keywords for all item types and property Abstract for files, to query
the custom set of properties, the application:

1. Opens a gateway and explicitly attaches it to the collection object.

2. Uses gateway support to reconfigure the property query to enable Keywords and Abstract query.

5–32 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

Here is a script that performs the custom query.

dim gateway
set gateway = server.Open
dim collection
set collection = server.CreateObject("Collection-123")
collection.AttachGateway(gateway, False)
gateway.PropIds = gateway.PropIds Or DSAXES_PROPID_CORE_KEYWORDS
fileProps = gateway.GetItemPropIds( DSXITEMTYPE_DOCUMENT ) Or
SAXES_PROPID_FILE_ABSTRACT
gateway.SetItemPropIds( DSXITEMTYPE_DOCUMENT, fileProps )
status = collection.DSLoadChildren
A child ItemObj object of collection inherits the gateway instance. Therefore, calling the DSLoadChildren
for a child item results in a query for the Keywords and Abstract properties for its child items and grandchild
items relative to the collection.

DocuShare Windows Client SDK 5–33

Objects DSItemEnumLib Library

DSLoadProps

VB DSLoadProps() As Long

C++ long DSLoadProps();

The DSLoadProps method retrieves the properties for the current ItemObj.

Parameters
None

Return value

Value Description

DSAXES_SUCCESS The method was successful.

DSAXES_E_SERVDOWN The server is down.

DSAXES_E_BUSY The gateway object is busy.

DSAXES_E_SYSRES The operation failed due to a system resource

failure.

DSAXES_E_BADSEL The operation attempted to retrieve properties for

an invalid ItemObj.

DSAXES_E_BADPARAM The ItemObj contains an invalid property value.

DSAXES_E_BADLINK The operation failed to access a gateway

resource.

Remarks
DSLoadProps supports the following ItemObj types:

BulletinBoard File Server

Calendar Group URL

Collection SavedQuery User

DSLoadProps update properties of ItemObj with the latest values stored in the DocuShare server. For the
method to work correctly, the Handle and DSServerMapId properties must be set to correct non-zero
values. If an explicit gateway object was assigned through a previous call to AttachGateway,
DSServerMapId can be set to zero.

To query which properties of ItemObj are updated for a particular item type by DSLoadProps, refer to the
ItemObj properties table in IItemObj and Supported Item Types on page 2–5.

By default, DSLoadProps loads all the listed properties. To prevent updating certain properties, set the
corresponding property identifiers in ExcludedCoreProps and ExcludedProps to True.

5–34 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

DSLoadProps can be instructed to obtain custom properties. To query a custom property:

1. Define the custom property using CustomProp.

2. Assign an empty value to CustomProp.
3. Call DSLoadProps.
4. Inspect the value of CustomProp.
If you have defined custom properties using CustomProp, but do not wish to include them in the
DSLoadProps query, specify DSAXES_PROPID_CORE_CUSTOM in ExcludedCoreProps.

For a Server ItemObj, the DSLoadProps method updates the following properties:

• IsReadOnly—set to True if DocuShare is in maintenance mode

• TimeAccessed—set the current time reported by DocuShare
• TimeModified—set the current time reported by the client operating system
• Custom integer property DSServer MajorVersion
• Custom integer property DSServer MinorVersion
• Custom string property DSServer AuthToken

DocuShare Windows Client SDK 5–35

Objects DSItemEnumLib Library

DSLock

VB DSLock( fLock As Boolean) As Long

C++ long DSLock(BOOL fLock);

The DSLock method places a lock on the current ItemObj. The DSLock method is only valid for ItemObj of
type document.

Parameters
fLock—determines if the current ItemObj is locked or unlocked.

Return value

Value Description

DSAXES_SUCCESS The method was successful.

DSAXES_INPROG Another request is in progress.

DSAXES_E_CANCEL The operation was canceled by the user.

DSAXES_E_SERVDOWN The server is down.

DSAXES_E_BUSY The gateway object is busy.

DSAXES_E_SYSRES The operation failed due to a system resource

failure.

DSAXES_E_BADSEL The operation attempted to lock an invalid ItemObj

DSAXES_E_BADPARAM The ItemObj contains an invalid property value.

DSAXES_E_BADLINK The operation failed to access a gateway

resource.

Remarks
DSLock updates the IsLocked property. If DSLock is called with fLock set to True, on a successful return
from the DSLock call, IsLocked is set to True.

DSSelect and DSEdit uses the IsReadOnly property for a file object to indicate a locking action. DSSelect
sets IsReadOnly to True if the end user checks the Lock option in the selection dialog box. DSEdit takes
the input value of IsReadOnly; if it is False, locks the file before downloading it. Once the file is physically
locked by the DocuShare server, the value of property IsLocked reflects the actual locked state of
DocuShare file, provided that DSLoadProps was called for the file object.

The True value in this instance is for C/C++. The values correspond to TRUE = 1, and FALSE = 0. In Visual
Basic True = -1 and False = 0. Only the C/C++ Boolean definitions are valid for this interface.

5–36 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

DSMove

VB DSMove(pDestItem As ItemObj) As Long

C++ long DSMove(LPDISPATCH pDestItem);

The DSMove method moves a DocuShare item, represented by the current ItemObj, from one collection to
another collection within the same server.

Parameters
pDestItem—a ItemObj of type Collection on the same DocuShare server.

Return value

Value Description

DSAXES_SUCCESS The method was successful.

DSAXES_INPROG Another request is in progress.

DSAXES_E_CANCEL The operation was canceled by the user.

DSAXES_E_SERVDOWN The server is down.

DSAXES_E_BUSY The gateway object is busy.

DSAXES_E_SYSRES The operation failed due to system resource

limitiations.

DSAXES_E_BADSEL The operation attempted to move an invalid

ItemObj.

DSAXES_E_BADPARAM The ItemObj contains an invalid property value.

DSAXES_E_BADLINK The operation failed to access a gateway

resource.

Remarks
DSMove updates the parent information it holds. For example, ItemObj has three parents: Collection-A,
Collection-B, and Collection-C. If the primary parent is Collection-A, moving the ItemObj from Collection-A
to Collection-D causes the internal parent list of the ItemObj to contain Collection-B, Collection-C, and
Collection-D.

NOTE: The primary parent, as indicated by ItemObj.Parent, can be set to any of the parents.

DSMove cannot be used to move a DocuShare item from one server to another. To do so, an application
can download an item to the PC from the source server and upload the item to the destination server using
DSDownload and DSUpload. After a successful upload, the application can delete the source item via a
call to DSDelete.

DocuShare Windows Client SDK 5–37

Objects DSItemEnumLib Library

DSSaveProps

VB DSSaveProps() As Long

C++ long DSSaveProps();

The DSSaveProps method saves the ItemObj properties to the object stored within the DocuShare server.

Parameters
None

Return value

Value Description

DSAXES_SUCCESS The method was successful.

DSAXES_E_SERVDOWN The server is down.

DSAXES_E_BUSY The gateway object is busy.

DSAXES_E_SYSRES The operation failed due to a system resource

failure.

DSAXES_E_BADSEL The operation attempted to save properties to an

invalid ItemObj.

DSAXES_E_BADPARAM The ItemObj contains an invalid property value.

DSAXES_E_BADLINK The operation failed to access a gateway

resource.

Remarks
This method is called to apply property changes to the ItemObj object representation of the actual object
stored on a DocuShare server.

DSSaveProps supports the following ItemObj types:

BulletinBoard Collection Group URL

Calendar File SavedQuery User

The DSSaveProps method update properties of a DocuShare item with the values currently held by the
corresponding properties of an ItemObj object representing the DocuShare item.

Modification to a property of an ItemObj does not automatically modifiy the corresponding property for the
represented item on a DocuShare server. DSSaveProps must be called to apply the modification to the
actual item stored on the server.

Refer to the ItemObj properties table in IItemObj and Supported Item Types on page 2–5 for a list of
properties that DSSaveProps updates. By default, DSSaveProps updates all the listed properties. To
exclude properties from being updated by DSSavePropd, set the corresponding property identifiers in
ExcludedCoreProps and ExcludeProps to True.

5–38 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

To update custom properties of a DocuShare item, use CustomProp assignments to assign new values to
the custom property representations in an ItemObj that represents the item. Use call DSSaveProps to save
the new property values.

To disable updating a custom property, specify DSAXES_PROPID_CORE_CUSTOM in

ExcludedCoreProps.

The following sample VB script updates all properties for a DocuShare file (handle File-23) and a custom
property called special_prop, but excludes the Description and MIME type.

dim file
set file = server.CreateObject("File-123")
file.CustomProps("special_prop", 1) = ""
status = file.DSLoadProps
file.Title = "Updated proposal"
... ' Edit other properties
file.ExcludedCoreProps = DSAXES_PROPID_CORE_DESCRIPTION
file.ExcludedProps = DSAXES_PROPID_FILE_MIMETYPE
file.CustomProps("special_prop", 1) = "Updated special_prop value"
status = file.DSSaveProps

DocuShare Windows Client SDK 5–39

Objects DSItemEnumLib Library

DSSelect

VB DSSelect(lFlags As Long) As Long

C++ long DSSelect(long flags)

The DSSelect method provides a dialog that allows the user to select a document or collection. The
current ItemObj inherits the selected object.

Parameters
lFlags—set to 0 for a Collection ItemObj object. It may be set to one or more of the following mode flags
for a non-container object.

IFlag Description

ITEMOBJ_SELFLAG_OPEN Select an item to open. This flag cannot be

combined with ITEMOBJ_SELFLAG_SAVE.

ITEMOBJ_SELFLAG_SAVE Select an item to save. If this flag is not specified,

an open dialog is run.

ITEMOBJ_SELFLAG_READONLY Disable the lock option; by default, lock option is

enabled. If the user checks the lock option,
ItemObj.IsReadOnly is set to True. An SDK
application should take this as an indication to lock
the selected file (calling DSLock). This flag only
sets IsReadOnly. It is not IsLocked. The latter is
used to reflect the actual lock state of the file in
DocuShare.

ITEMOBJ_SELFLAG_APPSEL Enable the application-select button; by default, the

button is disabled. If the user selects the button, the
dialog is closed immediately, and DSSelect returns
a status code of DSAXES_E_APPSELECT. An
SDK application should run a native dialog for item
selection.

ITEMOBJ_SELFLAG_NOVERCHECK Do not perform version check/warning; by default,

version checking is enabled. An ItemObj of a non-
file type should set this flag, or a file ItemObj should
set the flag if the SDK application performs version
checking.

ITEMOBJ_SELFLAG_NONFILE Allow selection of a non-file item. This flag is

automatically used for a non-file ItemObj object.
Use this flag to enable selection of a non-file item
when the item type of an ItemObj is undefined. The
flag does not enforce adherence to the single item
type. This means that if the ItemObj has type
Calendar, the flag does not guarantee a calendar
selection. The end user can select any non-
collection item including a file. The caller of
DSSelect must validate the selection.

5–40 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

IFlag Description

ITEMOBJ_SELFLAG_NAVFREE Specified by property Parent, allows navigation

outside the collection. By default, the item browsing
is limited to the collection.

ITEMOBJ_SELFLAG_SPLASHUI Show DocuShare splash screen. By default, no

splash screen is shown.

ITEMOBJ_SELFLAG_STARTROOT Start at DSClient root folder. With ItemObj.Parent

set to the handle number of a valid DocuShare
collection, and ItemObj.DSServerMapId set to the
server map instance ID, the selection dialog
regards the specified collection as the starting
place to open. This flag overrides that behavior and
makes the dialog to open the DocuShare Client
root folder first.

Return value

Value Description

DSAXES_SUCCESS The method was successful.

DSAXES_E_CANCEL The operation was canceled by the user.

DSAXES_E_SYSRES The operation failed due to a system resource

failure.

DSAXES_E_BADLINK The operation failed to access a gateway

resource.

Remarks
DSSelect requires the full DocuShare Client installation including its ODMA support. If the necessary Client
library is not installed, the method returns DSAXES_E_MODNOTFOUND.

DSSelect supports the following item types:

BulletinBoard Collection SavedQuery

Calendar File URL

To select a server, use IStore.DoSelectDialog. To allow selection of any non-collection item, leave property
Handle undefined and call DSSelect with the ITEMOBJ_SELFLAG_NONFILE flag. Here is an example
script that lets a user select any non-collection item and display the selected item handle and title.

dim item
set item = CreateObject("DSITEMENUMLib.ItemObj")
status status = item.DSSelect(ITEMOBJ_SELFLAG_NONFILE)

DocuShare Windows Client SDK 5–41

Objects DSItemEnumLib Library

if status = 0 then
MsgBox("User selected " + item.Handle + " " + item.Title)
end if
A dialog box for a collection object can only select an existing collection. DSSelect cannot be used to
specify a non-existent collection, such as creating a new collection. A dialog box for a non-collection object
allows specification of a new item name, such as creating a new file.

A non-collection dialog box uses the default caption of Open DocuShare Document in open mode and
uses the default caption of Save DocuShare Document in save mode. A collection dialog box defaults to
the caption, Select a DocuShare collection. Use string custom property DSSelect Caption to change the
caption. Follow this example to set the dialog caption to a custom phrase.

dim file
set file = server.CreateObject("File")
file.LocalProp("Caption", "DSSelect") = "Open Special File"
status = file.DSSelect(0)
If the DSSelect method returns successfully, the following properties are set to valid values for the selected
object.

• DSServerMapId
• Type
• Handle
• Parent
• ParentCount
• Title
• Summary
• Owner
• User
• TimeCreated
• TimeModified
• Length (for Collection and File objects only)
• Name (for File object only)
• IsLocked (for File object only)
• MimeType (for File object only)
• URL (for URL object only)
Properties not listed may be subject to invalidation. The instance-specific properties of ItemObj such as
DSGatewayMode and Thumbnail are not affected. If it needs to keep current property values, an SDK
application should replicate the ItemObj using the CopyTo method.

A collection object selected by DSSelect does not hold child information. To be able to enumerate child
items, an SDK application must call DSLoadChildren for the selected collection.

5–42 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

DSUpload

VB DSUpload() As Long

C++ long DSUpload();

The DSUpload method uploads the current ItemObj. It also sets any current properties applicable for the
item type being uploaded.

Parameters
None

Return value

Value Description

DSAXES_SUCCESS The method was successful.

DSAXES_E_SERVDOWN The server is down.

DSAXES_E_LOGIN_REFUSED Login validation to the server was denied.

DSAXES_E_BUSY The gateway object is busy.

DSAXES_E_FAIL An unknown failure occurred.

DSAXES_E_BADSEL The operation attempted to upload an invalid

ItemObj.

DSAXES_E_BADPARAM The ItemObj contains an invalid property value.

DSAXES_E_HTTP The operation failed due to an HTTP protocol

error.

DSAXES_E_BADLINK The operation failed to access a gateway

resource.

Remarks
DSUpload supports the following item types:

• File
• Version
• Collection
For a File or Version object, the DSUpload method requires the Name property set to the pathname of a
valid file.

For a File object, DSUpload requires the Parent property set to the destination collection. The file specified
by Name will be uploaded to this collection. DSUpload set properties for the uploaded file to the following
ItemObj properties:

• Name
• Title

DocuShare Windows Client SDK 5–43

Objects DSItemEnumLib Library

• Summary
• Description
• Keywords
• Author
• MaxVersions (defaults to 4)
• MimeType (may be overridden by DocuShare)
• Any custom property defined by both DocuShare and ItemObj
This sample VB script uploads a PC file to Collection-123 in a DocuShare represented by IServer (server).

dim file
set file = server.CreateObject("File")
file.Parent = 123
file.Name = "c:\My Documents\draft.doc"
file.Title = "Draft for our proposal"
status = file.DSUpload
For a Version object, DSUpload requires the Handle or HandleNum property set to a valid file handle.
DSUpload set properties for the uploaded file version to the following ItemObj properties:

• Name
• Comment
The sample VB script uploads a PC file as a new version of File-456.

dim fileVer
set fileVer = server.CreateObject("File-456")
fileVer.Name = "c:\My Documents\draft2.doc"
fileVer.Comment = "2nd draft"
status = fileVer.DSUpload
For a Collection object, DSUpload requires that the Name property either contains the pathname of an
existing folder or a file pattern preceded with a proper folder path.

If Name refers to a folder, DSUpload creates a collection in DocuShare and names it after the folder.
DSUpload then uploads any file or subfolder that appears in the folder. The Handle property of the ItemObj
is set to the DocuShare handle of the collection created in DocuShare.

If Name contains a filename pattern such as *.doc, DSUpload uploads all files in the folder whose names
match the file pattern. To upload multiple files to a collection, an SDK application can prepare a list of fully
qualified pathnames of existing files (each double quoted), and set the Name property to the list.

For an upload based on a filename pattern or file list, and if the HandleNum property of the current ItemObj
is set to zero (not set to a valid collection handle), DSUpload creates a collection with the folder's name
under the collection specified by the Parent property.

If the HandleNum value is not set to zero, DSUpload uploads the pattern matching files or listed files to the
existing collection specified by HandleNum.

5–44 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

For a Collection object, DSUpload set properties of the created collection to the following ItemObj
properties:

• Title
• Summary
• Description
• Keywords
• Logo
• BackgroundImage
• SortOrder
• Any custom property defined by both DocuShare and ItemObj
A child item (file or subcollection) created under the collection has both the filename and display name set
to the filename or folder name portion of the path value in Name. With DSLoadProps of the child item
called, its properties—Name and Title, should both yield this filename.

For a collection upload, specify the DSAXES_MODE_CREATERESULTENUM mode flag in

DSGatewayMode to have DSUpload generate an enumerator object for the result items created in the
server.

The sample VB script uploads all MS Word files that are in the folder My Documents to Collection-123 in a
DocuShare server represented by IServer (server). The script uses
DSAXES_MODE_CREATERESULTENUM to obtain a result enumerator and displays the handles of all
uploaded files.

dim newColl
set newColl = server.CreateObject("Collection-123")
newColl.Title = "My Word Documents"
newColl.Name = "c:\My Documents\*.doc"
newColl.DSGatewayMode = newColl.DSGatewayMode or
DSAXES_MODE_CREATERESULTENUM
status = newColl.DSUpload
if status = 0 then
dim enumObj
set enumObj = newColl.EnumObjects(DSCONTF_CHILDREN)
enumObj.Reset
dim resultList
while enumObj.NextPos <> 0
dim uploadedItem
set uploadedItem = enumObj.NextItem
resultList = resultList + uploadedItem.Handle + chr(10)
wend
MsgBox(resultList)
end if

DocuShare Windows Client SDK 5–45

Objects DSItemEnumLib Library

The item objects that are obtainable from the result enumerator have only the Handle and DSServerMapId
properties set to valid values. No other properties contain valid values. Follow the NextItem assignment
with a call to DSLoadProps to obtain any other properties including parent information.

The first item object obtainable from a result enumerator represents the target collection if the target
collection has to be created.

Regarding the example script above, the first item object does not refer to the target collection because the
script upload files to an existing collection. Instead, it refers to the first file that was uploaded to the target
collection.

5–46 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

GetPropStruct

VB GetPropStruct() as Variant

C++ VARIANT GetPropStruct();

The GetPropStruct method retrieves a pointer to the internal DSXCOLLECTIONITEMINFO structure held
by the item object.

Parameters
None

Return value
Return a variant pointer to a collection/item info structure.

Remarks
GetPropStruct can be utilized in conjunction with the bulk methods InitiateBulkReplicate and
InitiateBulkDownload of the IDsAxes client gateway interface.

The sample C++ code below, copies a source IItemObj collection (srcColl) and all items contained in the
collection to a destination IItemObj collection (destColl). The code uses an IDsAxes instance, called
gateway, which was opened using IServer.Open elsewhere.

HRESULT hr;
long status;
VARIANT vDsxInfo;
VariantInit(&vDsxInfo);
hr = srcColl.GetPropStruct(&vDsxInfo);
ASSERT(hr == S_OK);
status = gateway.InitiateBulkReplicate(
1,
&vDsxInfo,
srcColl.GetHandleNum(),
_T(""), _T(""), _T(""),
destColl.GetHandleNum(),
_T(""), _T(""), _T(""));
VariantClear(&vDsxInfo);

DocuShare Windows Client SDK 5–47

Objects DSItemEnumLib Library

GetStateInfo

VB GetStateInfo(Flags as Variant) as long

C++ long GetStateInfo( VARIANT* Flags );

GetStateInfo retrieves information on the state of an ItemObj. Access restriction, lock status, and
compound document configuration can be queried.

Parameters
Flags—optional; the following restriction flags are available for limiting the query.

Flags Description

ITEMOBJ_STATE_ISPRIVATE Same as IsPrivate.

ITEMOBJ_STATE_ISEMPTYLINKEDOBJ Is the ItemObj an empty linked object?

ITEMOBJ_STATE_ISLOCKED Same as IsLocked.

ITEMOBJ_STATE_ISSRCFILE Is the ItemObj a source file (an alternate

rendition)?

ITEMOBJ_STATE_ISSRCCONTAINER Is the ItemObj a source container (compound

element container)?

ITEMOBJ_STATE_ISSHORTCUT Is the ItemObj a shortcut?

ITEMOBJ_STATE_HASATTACH Does the ItemObj have attachments (content

elements of the preferred rendition)?

ITEMOBJ_STATE_HASSRCFILE Does the ItemObj have a source file (an alternate

rendition)?

ITEMOBJ_STATE_HASSRCCONTAINER Does the ItemObj have a source container

(compound element container)?

ITEMOBJ_STATE_HASSRCCONTENT Does the ItemObj's source file have content data?

ITEMOBJ_STATE_HASRENDITIONS Does the ItemObj contain one or more renditions?

ITEMOBJ_STATE_RELOAD Load linked objects from <client_data> if they

have not been loaded.

If this Flag’s parameter is empty, all of the above flags are raised and all the State information queried.

ITEMOBJ_STATE_LINKEDFILEMASK = _
ITEMOBJ_STATE_HASATTACH or _
ITEMOBJ_STATE_HASSRCFILE or _
ITEMOBJ_STATE_HASSRCCONTAINER
ITEMOBJ_STATE_COMPOUNDFILEMASK = _
ITEMOBJ_STATE_HASRENDITIONS

5–48 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

Return value
ITEMOBJ_STATE flags that determine the current ItemObj state. The flags are OR. Perform a logical AND
operation to isolate a flag that an application is interested in.

set fileObj = server.CreateObject("File-234")

fileObj.DSLoadProps
stateInfo = fileObj.GetStateInfo
if stateInfo and ITEMOBJ_STATE_HASATTACH then
...
end if
if stateInfo and ITEMOBJ_STATE_ISPRIVATE
...
end if

Remarks
Use the ITEMOBJ_STATE_RELOAD flag to cause reloading (de-serialization) of compound elements from
the <client_data> property of a compound document.

IsChildOf

VB IsChildOf(pItemObj As ItemObj) As Boolean

C++ BOOL IsChildOf(LPDISPATCH pItemObj);

The IsChildOf method returns a Boolean that determines if the current ItemObj is a child object of another
ItemObj.

Parameters
pItemObj—the ItemObj tests for parentage.

Return value
TRUE = 1; FALSE = 0

Remarks
The True value in this instance is for C/C++. The values correspond to TRUE = 1, and FALSE = 0. In Visual
Basic True = -1 and False = 0. Only the C/C++ Boolean definitions are valid for this interface.

DocuShare Windows Client SDK 5–49

Objects DSItemEnumLib Library

LoadDefaultProps

VB LoadDefaultProps(CorePropIds as long, ItemPropIds as long, PropStore as

optional Variant, ExcludedProps as optional Variant, Criteria as optional
Variant) as long

C++ long LoadDefaultProps(long CorePropIds, long ItemPropIds, VARIANT*

PropStore, VARIANT* ExcludedProps, VARIANT* Criteria);

LoadDefaultProps loads default values for properties defined for an ItemObj type. Client-side default
values are stored in a temporary file on the client machine by the SaveDefaultProps method. Server-side
default values are retrieved from the DocuShare server schemata. If a client-side default value does not
exist on the client machine, the server-side default value is used.

Parameters

Parameter Description

CorePropIds DSAXES_PROPID_CORE flags for core

properties to be loaded.

Criteria One of the following flags can be specified:

DSLOADPROPF_IFREQUIRED
DSLOADPROPF_IFEMPTYVALUED

ExcludedProps Optional; contains a list of custom property names

that should be not be loaded. CorePropIds must
include the DSAXES_PROPID_CORE_CUSTOM
flag.

ItemPropIds DSAXES_PROPID flags for item type-specific

properties.

PropStore Optional; contains the name of a value storage

that exists in the DSClient section of the system
registry. If PropStore is omitted, the default store
of SDKProps is used.

Return value
DSAXES_SUCCESS—default values were successfully loaded.

5–50 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

OpenGateway

VB OpenGateway() as Object DSGateway.GatewayHandler

C++ IDispatch* OpenGateway();

Parameters
OpenGateway opens a gateway to DocuShare.

Return value
A DSGateway.GatewayHandler object.

PreloadCustomProps

VB PreloadCustomProps(NamesOnly as boolean) as long

C++ long PreloadCustomProps(BOOL NamesOnly);

PreloadCustomProps updates an ItemObj with the names and default values of custom properties defined
on a DocuShare server.

Parameters
NamesOnly—specifies if the names of custom properties alone should be loaded, which results in
creating custom property fields that leaves field values empty. If the parameter is set to False, default
values specified in the schemata are loaded.

Return value
DSAXES_SUCCESS—custom properties were successfully incorporated into the ItemObj.

Remarks
The method collects custom properties based on the schema data cached for a global server map. This
means the Server property must contain a valid global server map (for example, a server mapped in
Windows Explorer). DSLoadProps internally calls this method with NamesOnly set to True.

DocuShare Windows Client SDK 5–51

Objects DSItemEnumLib Library

SaveDefaultProps

VB SaveDefaultProps( CorePropIds as Long, ItemPropIds as Long, PropStore as

optional Variant ) as Long

C++ long SaveDefaultProps(long CorePropIds, long ItemPropIds, VARIANT*

PropStore);

SaveDefaultProps saves property values that exist in an ItemObj as default property values in a temporary
file on the client machine.

Parameters

Parameter Description

CorePropIds DSAXES_PROPID_CORE flags for core

properties to be saved.

ItemPropIds DSAXES_PROPID flags for item type-specific

properties.

PropStore Optional; contains the name of a value storage to

be created in the DSClient section of the system
registry. If PropStore is omitted, the default store
of SDKProps is used.

Return value
DSAXES_SUCCESS—the default values were successfully saved.

Remarks
The following script runs a wizard-style form dialog of the DocuShare Windows Client and saves default
property values for item types, File and Collection, using the SaveDefaultProps method.

set helper = CreateObject("DSUtilityLib.HelperObj")

progId = helper.ProfileString(_
"DsNsx\Helpers\SetDefaultProps\Handler0", _
"ProgID")
set store = CreateObject("DSServerMap.Store")
store.Load
store.DiSelectDialog
store.Reset
while store.NextPos <> 0
set server = store.NextItem
if server.IsSelected then
set servObj = server.CreateObject("Server")
set enumObj = CreateObject("DSITEMENUMLib.EnumObj")

5–52 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

set fileObj = enumObj.NewItem

set collObj = enumObj.NewItem
fileObj.Server = server
collObj.Server = server
set service = CreateObject(progId)
service.Client.Library = "TestLib"
service.Client.WindowHandle = ...
service.RequestData.Task = "SetDefaultProps"
service.RequestData.Server = server
service.RequestData.TargetFolder = servObj
if service.ProcessRequest(enumObj) = DSAXES_NOCONNATTEMPT
then
corePropIds = fileObj.CorePropIds
itemPropIds = fileObj.PropIds
fileObj.SaveDefaultProps corePropIds, itemPropIds
corePropIds = collObj.CorePropIds
itemPropIds = collObj.PropIds
collObj.SaveDefaultProps corePropIds, itemPropIds
end if
end if
wend

DocuShare Windows Client SDK 5–53

Objects DSItemEnumLib Library

SetPropStruct

VB SetPropStruct(pvStruct as Variant) As Long

C++ long SetPropStruct(VARIANT* pvStruct);

The SetPropStruct method set properties based on a DSXCOLLECTIONITEMINFO structure.

Parameters
pvStruct—a variant structure that stores the properties to be set.

Return value

Value Description

NO_ERROR The method was successful.

ERROR_OUTOFMEMORY The system has insufficient memory resources.

ERROR_INVALID_PARAMETER A parameter exists in the variant structure.

UpdateLinks

VB UpdateLinks( Param as optional Variant )

C++ void UpdateLinks([in, optional] VARIANT* Param);

UpdateLinks forces reloading of AlternateRendition and other linked objects from <client_data>.

Parameters
Param—currently not used.

Return value
None

Remarks
Use this method to update linked objects of AlternateRendition, CompoundContainer, and
DSCONTF_ATTACH attachment objects (content elements of the preferred rendition). Normally, invoking
DSLoadProps automatically causes updating of linked objects. However, if it updates the <client_data>
property manually, an application can manually update the linked objects by calling UpdateLinks.

5–54 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

EnumObjects

VB EnumObjects(lFlags As Long) As Object

C++ LPDISPATCH EnumObjects(long lFlags);

The EnumObject method returns an ItemEnum object that enumerates selected parents or children of the
current ItemObj.

Parameters

IFlag Description

DSCONTF_CHILDREN Set the created ItemEnum object to enumerate

children of the current ItemObj.

DSCONTF_PARENT Set the created ItemEnum object to enumerate

parents of the current ItemObj.

ITEMOBJ_EOFLAG_FREEENUM Free master IEnumObj on a successful allocation

of IEnumObj

ITEMOBJ_EOFLAG_SHAREENUM Share master IEnumObj with returned IEnumObj.

Return value
Object/LPDISPATCH—the return value is a VB Object or a C/C++ dispatch interface to a EnumObj.

DocuShare Windows Client SDK 5–55

Objects DSItemEnumLib Library

EnumPresets

VB EnumPresets(lFlags As Long) As Object

C++ LPDISPATCH EnumPresets(long lFlags);

The EnumPresets method returns an object that can be used to enumerate presets. The lFlags parameter
identifies what types of presets to return. In DocuShare 5.0, the only supported presets are Records
Management classification presets identified by DSPRESETF_CLASSIFICATION.

Parameter
IFlags—possible value is DSPRESETF_CLASSIFICATION

5–56 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

EnumProps

VB EnumProps(Flags as long) as Object EnumItemProps

C++ IDispatch* EnumProps( long Flags );

EnumProps retrieves a property enumerator object for interface IEnumItemProps.

The following script retrieves properties from DocuShare and use EnumProps to walk through all
properties defined for the File object.

on error resume next

set fileObj = server.CreateObject("File-456")
fileObj.DSLoadProps
set props = fileObj.EnumProps
props.Reset
while props.NextPos <> 0
set prop = props.NextItem
set values = prop.EnumValues
if err then
err.clear
else
values.Reset
while values.NextPos <> 0
set value = values.NextItem
MsgBox value.FormattedValue, vbOK, prop.Name
wend
end if
wend

Parameters
Flags—chooses one or more properties categories to enumerate.

Parameter Description

DSPROPF_CLIENTCOREPROPS Standard DocuShare Client ItemObj properties.

DSPROPF_CLIENTCUSTOMPROPS Custom DocuShare Client ItemObj properties.

DSPROPF_CLIENTPROPS =_
DSPROPF_CLIENTCOREPROPS or _

DSPROPF_CLIENTCUSTOMPROPS

DSPROPF_DSSCHEMATA Preload a schema enumerator.

DocuShare Windows Client SDK 5–57

Objects DSItemEnumLib Library

Parameter Description

DSPROPF_NOCONT Do not include content data properties.

DSPROPF_NOOBJ Do not include automation object properties.

DSPROPF_NOPICT Do not include picture object properties.

DSPROPF_SERVERAPPPROPS DocuShare Client libaries and applications

properties.

DSPROPF_SERVERCOREPROPS Standard DocuShare object class properties.

DSPROPF_SERVERCUSTOMPROPS Custom DocuShare properties.

DSPROPF_SERVERPROPS = _

DSPROPF_SERVERCOREPROPS or _

DSPROPF_SERVERCUSTOMPROPS or _

DSPROPF_SERVERAPPPROPS

If the Flags parameter is omitted, the following flags are used automatically:

• DSPROPF_DSSCHEMATA
• DSPROPF_SERVERCOREPROPS
• DSPROPF_SERVERCUSTOMPROPS

5–58 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

5.2.1.2 ItemObj properties

This section contains the ItemObj property definitions.

SchemaEnumerator

VB SchemaEnumerator as Object EnumSchema

C++ IDispatch* GetSchemaEnumerator();

void SetSchemaEnumerator( IDispatch* );

Access Read/Write

SchemaEnumerator contains a schema enumerator object with interface IEnumSchema. The object
enumerates SchemaItem objects of interface ISchemaItem. SchemaItem is an abstraction of a DocuShare
object property.

The following script uses SchemaEnumerator to print the names and values of all File properties.

set fileObj = server.CreateObject("File-123")

if 0 = fileObj.DSLoadProps then
set schemaEnum = fileObj.SchemaEnumerator
schemaEnum.Reset
while schemaEnum.NextPos <> 0
set item = schemaEnum.NextItem
Print item.Name, fileObj.Prop(item.Name)
wend
end if

Remarks
An enumerator is generated based on cached schemata from a server. For the correct schemata to be
used, the DSServerMapId property must contain the instance ID (Server.InstanceId) of the correct server
before this property is referenced. Provided that the Server represents a global server map,
DSServerMapId is preset if the ItemObj was instantiated by a call to Server.CreateObject. See Chapter 4,
DSServerMap Library.

Schemata is retrieved from a DocuShare server and cached when the server is mapped to a client
machine. Call Server.UpdateSchemaCache to update the schema cache if a new property has been
added to DocuShare.

DocuShare Windows Client SDK 5–59

Objects DSItemEnumLib Library

DSErrorCode

VB DSErrorCode As Long

C++ long GetDSErrorCode();

Access Read only

The DSErrorCode property returns an error code from the DS server or gateway.

Remarks
Common errors are listed below.

HTTP result codes:

200 HTTP_OK

201 HTTP_CREATED

202 HTTP_ACCEPTED

203 HTTP_NON_AUTHORITATIVE_INFO

204 HTTP_NO_CONTENT

207 HTTP_MULTI_STATUS

300 HTTP_MULTIPLE_CHOICE

301 HTTP_MOVED_PERMANENTLY

302 HTTP_MOVED_TEMPORARILY

303 HTTP_SEE_OTHER

304 HTTP_NOT_MODIFIED

400 HTTP_BAD_REQUEST

401 HTTP_NOT_AUTHORIZED

402 HTTP_PAYMENT_REQUIRED

403 HTTP_FORBIDDEN

404 HTTP_NOT_AVAILABLE

405 HTTP_NOT_SUPPORTED

406 HTTP_NONE_ACCEPTABLE

407 HTTP_PROXYAUTHREQUIRED

408 HTTP_REQUEST_TIMEOUT

409 HTTP_CONFLICT

410 HTTP_GONE

411 HTTP_AUTHORIZATION_REFUSED

5–60 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

500 HTTP_INTERNALSERVERERROR

501 HTTP_NOT_IMPLEMENTED

502 HTTP_BADGATEWAY

503 HTTP_MAXCONNECTS

504 HTTP_GATEWAYTIMEOUT

Windows socket error codes*:

WSAEINTR

WSAEBADF

WSAEACCES

WSAEFAULT

WSAEINVAL

WSAEMFILE

WSAEWOULDBLOCK

WSAEINPROGRESS

WSAEALREADY

WSAENOTSOCK

WSAEDESTADDRREQ

WSAEMSGSIZE

WSAEPROTOTYPE

WSAENOPROTOOPT

WSAEPROTONOSUPPORT

WSAESOCKTNOSUPPORT

WSAEOPNOTSUPP

WSAEPFNOSUPPORT

WSAEAFNOSUPPORT

WSAEADDRINUSE

WSAEADDRNOTAVAIL

WSAENETDOWN

WSAENETUNREACH

DocuShare Windows Client SDK 5–61

Objects DSItemEnumLib Library

WSAENETRESET

WSAECONNABORTE

WSAECONNRESET

WSAENOBUFS

WSAEISCONN

WSAENOTCONN

WSAESHUTDOWN

WSAETOOMANYREFS

WSAETIMEDOUT

WSAECONNREFUSED

WSAELOOP

WSAENAMETOOLONG

WSAEHOSTDOWN

WSAEHOSTUNREACH

WSAENOTEMPTY

WSAEPROCLIM

WSAEUSERS

WSAEDQUOT

WSAESTALE

WSAEREMOTE

WSAEDISCON

WSANOTINITIALISED

WSASYSNOTREADY

WSAVERNOTSUPPORTED

WSAHOST_NOT_FOUND

WSATRY_AGAIN

WSANO_RECOVERY

WSANO_DATA

5–62 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

Operating system error codes*:

ERROR_FILE_NOT_FOUND

ERROR_PATH_NOT_FOUND

ERROR_TOO_MANY_OPEN_FILES

ERROR_ACCESS_DENIED

ERROR_NOT_ENOUGH_MEMORY

ERROR_OUTOFMEMORY

ERROR_WRITE_PROTECT

ERROR_SECTOR_NOT_FOUND

ERROR_READ_FAULT

ERROR_GEN_FAILURE

ERROR_SHARING_VIOLATION

ERROR_LOCK_VIOLATION

ERROR_NETWORK_BUSY

ERROR_NETWORK_ACCESS_DENIED

ERROR_FILE_EXISTS

ERROR_INVALID_PARAMETER

ERROR_FILENAME_EXCED_RANGE

ERROR_DISK_OPERATION_FAILED

ERROR_INVALID_DRIVE

ERROR_MEDIA_CHANGED

ERROR_DRIVE_LOCKED

ERROR_NOT_DOS_DISK

ERROR_NOT_READY

ERROR_DISK_FULL

NOTE: * Refer to Windows documentation for the numeric values.

DocuShare Windows Client SDK 5–63

Objects DSItemEnumLib Library

DSGatewayMode

VB Property DSGatewayMode As Long

C++ long GetDSGatewayMode();

void SetDSGatewayMode(long nNewValue);

Access Read/Write

The DSGatewayMode property sets and retrieves the mode setting for the gateway object attached to the
ItemObj.

Remarks
The mode flags are OR together. See SetMode on page 3–71 for additional information on flags.

DSServerMapld

VB Property DSServerMapId As Long

C++ long GetDSServerMapId();

void SetDSServerMapId(long nNewValue);

Access Read/Write

The DSServerMapId property sets or retrieves the server map ID for the current ItemObj. The server map
ID is utilized in conjunction with the DocuShare Server Map interface for managing persistant server
connections.

Remarks
An SDK application normally does not directly modify DSServerMapId. DSServerMapId is automatically
set if an ItemObj is created using IServer.CreateObject. A child ItemObj created through
IItemObj.CreateObject inherits the container ItemObj DSServerMapId.

5–64 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

Reload

VB Reload As Boolean

C++ BOOL GetReload();

void SetReload(BOOL bNewValue);

Access Read/Write

The Reload property controls whether the thumbnail property of the current ItemObj should be
automatically reloaded. Setting the Reload property to True causes the thumbnail picture to be reloaded
the next time the Thumbnail property is referenced.

Remarks
The True value in this instance is for C/C++. The values correspond to TRUE = 1, and FALSE = 0. In Visual
Basic True = -1 and False = 0. Only the C/C++ Boolean definitions are valid for this interface.

Abstract

VB Abstract As String

C++ CString GetAbstract();

Access Read only

The Abstract property contains a DocuShare File item machine-generated abstract.

DocuShare Windows Client SDK 5–65

Objects DSItemEnumLib Library

AccessControlGrants

VB AccessControlGrants as Long

C++ long GetAccessControlGrants();

void SetAccessControlGrants( long );

Access Read/Write

The AccessControlGrants property indicates the permissions for the DocuShare Group or User that is
identified by this IItemObj. The property value is a set of bits representing a combination of Reader, Writer,
and Manager access.

The permissions for an individual group or user are specified in an IItemObj using the
AccessControlGrants property. The identity of the individual group or user is specified using the IItemObj's
Handle property. A complete set of permissions for a DocuShare object are grouped into an IEnumObj
object. This IEnumObj object is then associated with a DocuShare object using the CustomProp property.

dim permissionsList, groupObj, userObj

set permissionsList = CreateObject("DSITEMENUMLib.EnumObj")
set groupObj = permissionsList.NewItem
groupObj.Handle = "Group-5"
groupObj.AccessControlGrants = DSGRANT_READER
set userObj = permissionsList.NewItem
userObj.Handle = "User-67"
userObj.AccessControlGrants = DSGRANT_READER Or DSGRANT_WRITER
calendarObj.CustomProp( "acl", DSAXES_PROPTYPE_ACE ) = permissionsList

5–66 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

AlternateRendition

VB AlternateRendition as Object ItemObj

C++ IDispatch* GetAlternateRendition();

void SetAlternateRendition( IDispatch* );

Access Read/Write

AlternateRendition contains an ItemObj object of type DSXITEMTYPE_DOCUMENT or

DSXITEMTYPE_RENDITION that represents an alternate rendition of a compound document.

set docObj = server.CreateObject("File-456")

docObj.DSLoadProps
if docObj.AlternateRendition.Name <> "" then
Print docObj.Title + _
" has alternate rendition " + _
docObj.AlternateRendition.Name
end if

Author

VB Author As String

C++ CString GetAuthor();

void SetAuthor(LPCTSTR lpszNewValue);

Access Read/Write

The Author property accesses the author of a document stored in a DocuShare server.

AutoDelete

VB AutoDelete As Boolean

C++ BOOL GetAutoDelete()

void SetAutoDelete(BOOL bNewValue);

Access Read/Write

The AutoDelete property determines if a local file associated with the current ItemObj should be
automatically deleted upon deletion of the ItemObj.

The True value in this instance is for C/C++. The values correspond to TRUE = 1, and FALSE = 0. In Visual
Basic True = -1 and False = 0. Only C/C++ Boolean definitions are valid for this interface.

DocuShare Windows Client SDK 5–67

Objects DSItemEnumLib Library

BackgroundImage

VB BackgroundImage As String

C++ CString GetBackgroundImage();

void SetBackgroundImage(LPCTSTR lpszNewValue);

Access Read/Write

The BackgroundImage property retrieves or sets the background image to be displayed for a collection.
The background image is only displayed when the collection is viewed through a browser.

BaseType

VB BaseType as String

C++ CString GetBaseType();

void SetBaseType( LPCTSTR );

Access Read/Write

BaseType contains a base type identifier that determines a class of DocuShare objects on which the
current item type is based. For a custom type item derived from Collection, BaseType is set to Collection.

BaseTypeNum

VB BaseTypeNum as Long

C++ long GetBaseTypeNum();

void SetBaseTypeNum( long );

Access Read/Write

BaseTypeNum contains a base DSXITEMTYPE type number that specifies the current item base type. For
a custom type item derived from Collection, BaseTypeNum is set to DSXITEMTYPE_COLLECTION.

5–68 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

ClientProp

VB ClientProp as Variant

C++ VARIANT* GetClientProp();

void SetClientProp( VARIANT );

Access Read/Write

ClientProp contains the property value of a DocuShare Client library or application.

Parameters
PropName—a string that contains the name of a client property, a Property.

To read the value of a ClientProp, set the PropName parameter to a client application-specific property
name.

PropValue = ItemObj.ClientProp(PropName)

Remarks
ClientProp is an entry in the value field of the <client_data> property of a DocuShare object. DSClient SDK
libraries and applications use ClientProp to store client-specific control settings and other metadata.

All ClientProp entries are stored using <client_data> which is a TEXT property type in DocuShare. The
maximum data size that can be stored in <client_data> is 1024 bytes. If the combined ClientProp entries
exceed this limit, entries that fall out of the range are lost or truncated.

Referencing ClientProp can raise an OLE interface error.

• E_FAIL—loading of <client_data> properties failed.

• E_INVALIDARG—the specified property could not be found.

DocuShare Windows Client SDK 5–69

Objects DSItemEnumLib Library

Comment

VB Comment As String

C++ CString GetComment();

void SetComment(LPCTSTR lpszNewValue);

Access Read/Write

The Comment property provide comments to the various versions of a document.

CompoundContainer

VB CompoundContainer as Object ItemObj

C++ IDispatch* GetCompoundContainer();

void SetCompoundContainer( IDispatch* );

Access Read/Write

CompoundContainer contains a DSXITEMTYPE_COLLECTION ItemObj object type that represents a

collection in DocuShare where an alternate rendition and attachments are stored as separate files.
CompoundContainer is also used to specify a folder in a client machine where alternate rendition files and
attachments are located. DSUpload checks to see if CompoundContainer.Name is set to a folder in a PC,
and if the folder contains one or more rendition files, uses it to upload a compound document with one or
more content element files or both.

ContainerItemObject

VB ContainerItemObject as Object ItemObj

C++ IDispatch* GetContainerItemObject();

void SetContainerItemObject( IDispatch* );

Access Read/Write

ContainerItemObject contains a ItemObj that represents a container item where the current item appears.
A container item is a container class such as Collection, Calendar, and Bulletin Board.

5–70 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

Contents

VB Contents as Variant

C++ VARIANT* GetContents();

void SetContents( VARIANT );

Access Read/Write

Contents contains a stream of content data. If the MIME type (MimeType) is text/xml, Contents returns an
XML interface IXMLDOMDocument document object. If the type is text/html, Contents returns an HTML
interface IHTMLDocument2 document object. For other text types, Contents returns the content data as a
text string. If the type is application/msword, an MS Word Document object is returned. For all other types,
a generic stream object with interface IStream is returned.

Remarks
A pathname of a valid file may be assigned to Contents. However, when Contents is referenced, the
pathname is not returned; instead, the file stream is opened. Depending on the file's MIME type, Contents
contains an object or text string.

To clear Contents from the ItemObj, set the type member of an assigning VARIANT variable to
VT_EMPTY. The Contents properties of the linked objects (AlternateRendition, CompoundContainer,
PreferredRendition, ReferrerItemObject and DSCONTF_ATTACH attachment objects) are all cleared.

DocuShare Windows Client SDK 5–71

Objects DSItemEnumLib Library

CorePropIds

VB CorePropIds as Long

C++ long GetCorePropIds();

Access Read only

CorePropIds contains DSAXES_PROPID property IDs of server-side core properties that can be queried
for the ItemObj.

Parameters
WantAllIds—optional; if set to True, causes CorePropIds to return a set of all core property IDs that can
be queried. The set of IDs is defined as DSAXES_PROPID_CORE_GETTABLE. If WantAllIds is set to
False, CorePropIds returns a set of property IDs that are editable. This set of IDs is defined as
DSAXES_PROPID_CORE_SETTABLE.

DSAXES_PROPID_CORE_CUSTOM is also included if one or more custom properties are defined for the
item's class.

Remarks
CorePropIds exclude IDs that are contained in ExcludedCorePropIds.

If the option flag ITEMOBJ_OPTION_PRELOADCUSTPROPS is set, CorePropIds internally calls

PreloadCustomProps and collects the names of all custom properties defined for the item's class.

For GatewayHandler.GetProps to successfully retrieve a custom property, it needs the property name.
Setting DSAXES_PROPID_CORE_CUSTOM to True alone is not sufficient. By using the option
ITEMOBJ_OPTION_PRELOADCUSTPROPS, an ItemObj can ensure the custom property is recognized
by GetProps and the property's value is retrieved correctly.

5–72 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

CustomProp

VB CustomProp(Name As String, typeId As Long) As Variant

C++ VARIANT GetCustomProp(LPCTSTR Name, long typeId);

void SetCustomProp(LPCTSTR Name, long typeId, VARIANT* newValue);

Access Read/Write

The CustomProp property sets or gets custom property values. The property and value of custom property
is determined by name and ID type.

Parameters

Parameter Description

name A string containing the name of the custom

property to be queried.

typeId DSAXES data type. If the specified item data type

is different from the actual data type, or if the type
conversion is not possible, a COM interface error
is raised with the error code E_NOTIMPL.

pvPropValue Address of a VARIANT variable whose vt member

is initialized to VT_EMPTY. On return, the vt
member is set to the variant data type of the
queried property value. The property value is
copied to an appropriate data member of this
variant structure.

Remarks
Refer to Working with properties on page 2–46 to utilize CustomProp.

DocuShare Windows Client SDK 5–73

Objects DSItemEnumLib Library

Data

VB Data As Variant

C++ VARIANT GetData();

void SetData(VARIANT* newValue);

Access Read/Write

Data property is private to this object.

Remarks
This variant provides the developer with a location to store and retrieve information for this object.

Description

VB Description As String

C++ CString GetDescription();

void SetDescription(LPCTSTR lpszNewValue);

Access Read/Write

The Description property provides extended information on a DocuShare server object.

5–74 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

ExcludedCoreProps

VB ExcludedCoreProps As Long

C++ long GetExcludedCoreProps();

void SetExcludedCoreProps(long nNewValue);

Access Read/Write

The ExcludedCoreProps property limits the properites that will be loaded.

Remarks
This property is used to specify one or more core properties that should be excluded from a query by
DSLoadProps or from a property update by DSSaveProps. Core properties are those properties which are
common to all standard item types.

ExcludedCoreProps Flags ItemObj Properties

DSAXES_PROPID_CORE_TITLE Title

DSAXES_PROPID_CORE_SUMMARY Summary

DSAXES_PROPID_CORE_DESCRIPTION Description

DSAXES_PROPID_CORE_KEYWORDS Keywords

DSAXES_PROPID_CORE_OWNER Owner *

DSAXES_PROPID_CORE_MODIFIEDBY User *

DSAXES_PROPID_CORE_CREATEDATE TimeCreated *

DSAXES_PROPID_CORE_MODIFIEDDATE TimeModified *

DSAXES_PROPID_CORE_PARENTHANDLES Parent, ParentCount *

DSAXES_PROPID_CORE_CUSTOM Custom Properties

NOTE: The properties marked with asterisks (*) can be queried and therefore can be excluded using
ExcludedCoreProps in conjunction with DSLoadProps but not DSSaveProps.

DocuShare Windows Client SDK 5–75

Objects DSItemEnumLib Library

ExcludedProps

VB ExcludedProps As Long

C++ long GetExcludedProps();

void SetExcludedProps(long nNewValue);

Access Read/Write

The ExcludedProps property excludes properties from DSLoadProps.

Remarks
This property is used to specify one or more item type-specific properties that should be excluded from a
query by DSLoadProps or from a property update by DSSaveProps. Type-specific properties are those
properties which are specific to the item type of the current ItemObj.

ItemObj Type ExcludedProps Flags ItemObj Properties

File DSAXES_PROPID_FILE_FILENAME Name*

DSAXES_PROPID_FILE_MIMETYPE MimeType

DSAXES_PROPID_FILE_AUTHOR Author

DSAXES_PROPID_FILE_MAXVERSION MaxVersions *

DSAXES_PROPID_FILE_LOCKEDBY IsLocked, User *

DSAXES_PRODID_FILE_SIZE Length *

DSAXES_PROPID_FILE_ABSTRACT Abstract *

Collection DSAXES_PROPID_COLL_LOGO Logo

DSAXES_PROPID_COLL_BGIMAGE Background Image

DSAXES_PROPID_COLL_SORTORDER Sort Order

DSAXES_PROPID_COLL_SIZE Length *

URL DSAXES_PROPID_URL_URL URL

NOTE: The properties marked with asterisks(*) can be queried and therefore can be excluded using
ExcludedProps in conjunction with DSLoadProps, but not DSSaveProps.

5–76 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

Filename

VB Filename as String

C++ CString GetFilename();

void SetFilename( LPCTSTR );

Access Read/Write

Filename contains the string value of the DocuShare <document> property of a file item.

Remarks
Filename is used to specify a name different from the name stored in ItemObj.Name prior to invoking
ItemObj.DSUpload to upload the file from the PC. If Filename is not specified, DSUpload uses the title part
of the file's pathname stored in ItemObj.Name to name the uploaded file in DocuShare. If it needs to assign
a different name, an application can use Filename.

For an ItemObj of type File, ItemObj.Filename equals to ItemObj.Name after DSLoadProps is called.

Handle

VB Handle As String

C++ CString GetHandle();

void SetHandle(LPCTSTR lpszNewValue);

Access Read/Write

The Handle property is the string handle value of the current ItemObj.

Remarks
Property TypeNum corresponds to the textual type identifier part of property Handle, while property
HandleNum corresponds to the textual handle number part of property Handle.

For example, with the Handle property set to File-123, TypeNum yields the numeric type identifier File,
which is DSXITEMTYPE_DOCUMENT, and HandleNum yields the integer handle number value 123.

Modifying Handle automatically modifies TypeNum and HandleNum and vice versa.

HandleNum

VB HandleNum As Long

C++ long GetHandleNum();

void SetHandleNum(long nNewValue);

Access Read/Write

The property HandleNum is the numeric handle for the current ItemObj.

DocuShare Windows Client SDK 5–77

Objects DSItemEnumLib Library

HighestVersionUsed

VB HighestVersionUsed as Long

C++ long GetHighestVersionUsed();

Access Read only

HighestVersionUsed contains the highest version number of a file item.

set fileObj = server.CreateObject("File-123")

fileObj.DSLoadProps
MsgBox cstr(fileObj.HighestVersionUsed), vbOK, "HighestVersionUsed"

Remarks
HighestVersionUsed corresponds directly to the DocuShare <highest_version_used> property. The
property is supported on DocuShare Release 3.0 or higher.

Icon

VB Icon( asOpenForm As Boolean, asSmallForm As Boolean) as Object

C++ LPDISPATCH GetIcon(BOOL asOpenForm, BOOL asSmallForm);

Access Read only

The Icon property is used to retrieve the icon picture for an object.

Parameters

Parameter Description

asOpenForm Determines if the returned icon represents the

image as an open or closed item. A True value
returns the open form of the icon.

asSmallForm Determines if the generated icon is 32x32 or

16x16 pixels. A True value returns a 16x16 pixel
icon.

Remarks
The True value in this instance is for C/C++. The values correspond to TRUE = 1, and FALSE = 0. In Visual
Basic True = -1 and False = 0. Only the C/C++ Boolean definitions are valid for this interface.

5–78 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

IsContainer

VB IsContainer as Boolean

C++ BOOL GetIsContainer();

Access Read only

IsContainer determines if the ItemObj represents a collection, calendar, bulletin board, or other container
item.

IsCustomType

VB IsCustomType as Boolean

C++ BOOL GetIsCustomType();

Access Read only

IsCustomType determines if the ItemObj represents an item of a custom DocuShare object class.

IsLocked

VB IsLocked As Boolean

C++ BOOL GetIsLocked();

void SetIsLocked(BOOL bNewValue);

Access Read/Write

The IsLocked property determines if a DocuShare file represented by an ItemObj object is locked.

Remarks
The IsLocked property represents the actual lock state of a file in DocuShare. ItemObj has a related
property called IsReadOnly. Method DSSelect or DSEdit uses IsReadOnly to relay an intent for modifying
the lock state of the file to the caller or to the DocuShare Client.

The True value in this instance is for C/C++. The values correspond to TRUE = 1, and FALSE = 0. In Visual
Basic True = -1 and False = 0. Only the C/C++ Boolean definitions are valid for this interface.

DocuShare Windows Client SDK 5–79

Objects DSItemEnumLib Library

IsPrivate

VB IsPrivate as Boolean

C++ BOOL GetIsPrivate();

void SetIsPrivate( BOOL );

Access Read/Write

IsPrivate determines if the access to a DocuShare object represented by the ItemObj is restricted to the
owner.

Remarks
The following script obtains a list of items contained in a collection and depending on the IsPrivate setting,
prints out the title for each found item differently.

set collObj = server.CreateObject("Collection-456")

collObj.DSLoadChildren
set enumObj = collObj.EnumObjects(DSCONTF_CHILDREN)
enumObj.Reset
while enumObj.NextPos <> 0
set item = enumObj.NextItem
if item.IsPrivate then
Print item.Title & " (private)"
else
Print item.Title
end if
wend
To persist the IsPrivate setting in the server, DSSaveProps and DSUpload must be called.

set fileObj = server.CreateObject("File")

fileObj.Name = "c:\doc\proposal.doc"
fileObj.Options = fileObj.Options or ITEMOBJ_OPTION_SETACL
fileObj.IsPrivate = True
fileObj.DSUpload

NOTE: The ITEMOBJ_OPTION_SETACL option must be specified before DSUpload is called.

5–80 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

Querying an ACL setting such as IsPrivate can be time consuming for a DocuShare server. To avoid a
performance hit, it is recommended that applications that invoke ItemObj.DSLoadChildren switch off the
IsPrivate query, which by default, is included (refer to the section on ItemObj.CorePropIds). To exclude the
IsPrivate property from the query, add DSAXES_PROPID_CORE_PRIVATE to
ItemObj.ExcludedCorePropIds.

set collObj = server.CreateObject("Collection-456")

collObj.ExcludedCorePropIds = collObj.ExcludedCorePropIds or
DSAXES_PROPID_CORE_PRIVATE
collObj.DSLoadChildren

DocuShare Windows Client SDK 5–81

Objects DSItemEnumLib Library

IsReadOnly

VB IsReadOnly As Boolean

C++ BOOL GetIsReadOnly();

void SetIsReadOnly(BOOL bNewValue);

Access Read/Write

The IsReadOnly property determines whether the current ItemObj is a read only object.

Remarks
IsReadOnly is applicable to the following item types:

• Server
• File
For a server object, IsReadOnly property is set if the represented DocuShare server is in maintenance
mode and not accessible for write operations.

For a file object, IsReadOnly property is used by DSSelect and DSEdit to indicate a locking action.
DSSelect sets IsReadOnly to True if the end user checks the Lock option in the selection dialog box.
DSEdit takes the input value of IsReadOnly, and if it is False, locks the file before downloading it. Once the
file is physically locked by the DocuShare server, the value of IsLocked property reflects the actual locked
state of the file in DocuShare, provided that DSLoadProps was called for the file object.

The True value in this instance is for C/C++. The values correspond to TRUE = 1, and FALSE = 0. In Visual
Basic True = -1 and False = 0. Only the C/C++ Boolean definitions are valid for this interface.

Keywords

VB Keywords As String

C++ CString GetKeywords();

void SetKeywords(LPCTSTR lpszNewValue);

Access Read/Write

The Keywords property accesses the keyword list associated with the current ItemObj.

5–82 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

Length

VB Length As Long

C++ long GetLength();

void SetLength(long nNewValue);

Access Read/Write

The Length property returns the length of the current ItemObj. For a collection, the returned value is the
number of objects within the collection. For a document object, the return value is Getlengthof item (file
size, number of items).

LocalProp

VB LocalProp( Name as String, AppId as optional Variant, TypeId as optional

Variant ) as Variant

C++ VARIANT GetLocalProp(LPCTSTR Name, VARIANT* AppId, VARIANT*

TypeId);
void SetLocalProp(LPCTSTR Name, VARIANT* AppId, VARIANT* TypeId,
VARIANT* Value);

Access Read/Write

LocalProp contains the value of a temporary property specific to a DocuShare Client library or another
client application.

Remarks

LocalProp is typically used by a calling application to pass a control parameter specific to the invoked
ItemObj method. For example, an application passes a dialog caption string to the implementation of
ItemObj.DSSelect as follows:

set collObj = server.CreateObject("Collection")

collObj.LocalProp( "Caption", "DSSelect" ) = "Select DocuShare Collection"
status = collObj.DSSelect
The value of a LocalProp is lost when the ItemObj owner object is destroyed. A LocalProp property is not
saved in DocuShare even if ItemObj.DSSaveProps is called. Contrast this to a ClientProp which is saved
in DocuShare, as a value of the DocuShare client_data property of the item that the ItemObj object
represents, when the method is called.

DocuShare Windows Client SDK 5–83

Objects DSItemEnumLib Library

LockedBy

VB LockedBy as String

C++ CString GetLockedBy();

void SetLockedBy( LPCTSTR );

Access Read/Write

Contains a string consisting of a full name and handle for the DocuShare user who currently owns a lock
on a file. An example is Joe Cool (User-123).

LockedByNum

VB LockedByNum as Long

C++ long GetLockedByNum();

void SetLockedByNum( long );

Access Read/Write

Contains a handle number of a full name and handle for the DocuShare user who currently owns a lock on
a file. If a user handle is User-123, LockedByNum contains an integer of 123. The item type, User, is
assumed.

Logo

VB Logo As String

C++ CString GetLogo();

void SetLogo(LPCTSTR lpszNewValue);

Access Read/Write

The Logo property sets the logo for a collection object.

MaxVersions

VB MaxVersions As Long

C++ long GetMaxVersions();

void SetMaxVersions(long nNewValue);

Access Read/Write

The MaxVersions property accesses the maximum number of versions that a document object can contain
in a DocuShare server.

5–84 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

MimeType

VB MimeType As String

C++ CString GetMimeType();

void SetMimeType(LPCTSTR lpszNewValue);

Access Read/Write

The MimeType property sets the mime type for a document object stored on a DocuShare server.

ModifiedBy

VB ModifiedBy as String

C++ CString GetModifiedBy();

void SetModifiedBy( LPCTSTR );

Access Read/Write

ModifiedBy contains a string consisting of a full name and handle for the DocuShare user who last
modified the item. An example is Joe Cool (User-123).

Remarks
ModifiedBy corresponds to the <modified_by> DocuShare property. ModifiedBy is different from the User
property. User tracks who last modified or locked a file.

ModifiedbyNum

VB ModifiedByNum as Long

C++ long GetModifiedByNum();

void SetModifiedByNum( long );

Access Read/Write

Contains the handle number of a DocuShare user who last modified the item. If a user handle is User-123,
ModifiedByNum contains an integer of 123. The item type, User, is assumed.

DocuShare Windows Client SDK 5–85

Objects DSItemEnumLib Library

Name

VB Name As String

C++ CString GetName();

void SetName(LPCTSTR lpszNewValue);

Access Read/Write

The Name property refers to the intrinsic name of an item stored in DocuShare.

Remarks
The Name property is applicable to item types File, Version, Collection, and User.

For File, Version, and Collection, the applicability and meaning of Name depends on the context in which
ItemObj is used. For example, for a file or version object calling the DSUpload method, Name refers to the
fully qualified pathname of a PC file. The Name property of a file object after a call to DSLoadProps
contains the filename as stored in DocuShare.

For a collection object calling DSUpload, Name refers to either a pathname of a folder or a list of filenames
or a filename pattern. A collection object updated by DSLoadProps clears the Name property since a
collection as indexed by DocuShare does not have any filename associated with it.

For a User object, Name refers to the user account name. The display name of a user object is obtained
through custom properties first_name and last_name.

IItemObj defines a related read-only property called ValidatedFileName. ValidatedFileName is derived

from the Name and Title properties and is used by the DocuShare Client to generate a filename which is
composed of legal characters in the Windows file system.

ObjectTypeNum

VB

C++ Integer

Access Read/Write

ObjectTypeNum contains a DSX_OBJTYPE number that corresponds to the DSXITEMTYPE number

assigned to the item.

Remarks
Certain GatewayHandler methods takes item type identifiers for data type DSX_OBJTYPE. Applications
use this property to translate an ItemObj to a DSX_OBJTYPE value.

5–86 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

Options

VB Options as Long

C++ long GetOptions();

void SetOptions( long );

Access Read/Write

Options property ontains the flag settings for optional settings that control the operations performed by
ItemObj.

Remarks
The following option flags are available.

Option Flags Description

ITEMOBJ_OPTION_AUTODEL Read only; auto deletes a file specified in

ItemObj.Name when ItemObj is destroyed.

ITEMOBJ_OPTION_RELOAD Read only; reloads thumbnail when

ItemObj.Thumbnail is referenced.

ITEMOBJ_OPTION_RELEASEGATE Release GatewayHandler attached via

ItemObj.AttachGateway.

ITEMOBJ_OPTION_RELEASESERV Release Server attached via

ItemObj.AttachServerMap.

ITEMOBJ_OPTION_USESYSTIME Use system time (GMT) for ItemObj.TimeCreated,

TimeModified, and TimeAccessed.

ITEMOBJ_OPTION_CHANGESTORE Use a non-default server map store.

ITEMOBJ_OPTION_ASYNCSLEEP Read only; this ItemObj is running on a worker

thread.

ITEMOBJ_OPTION_ASYNCTHREAD TaskStatus can sleep 100 msec before returning.

ITEMOBJ_OPTION_ASYNCDONE Read only; indicates that an asynchronous task

has completed.

ITEMOBJ_OPTION_DONTLINK Do not deserialize linked objects.

ITEMOBJ_OPTION_DOWNLOADALT Download an alternate rendition specified in

ItemObj.AlternateRendition. The flag also
redirects ItemObj.ValidatedFileName to return
AlternateRendtion.Name if AlternateRendition is
not empty and AlternateRendtion.Name contains
a name string with a non-empty file extension part.

ITEMOBJ_OPTION_UPLOADALT DSUpload, DSSaveProps, and DSCreate should

upload AlternateRendition.

DocuShare Windows Client SDK 5–87

Objects DSItemEnumLib Library

Option Flags Description

ITEMOBJ_OPTION_UPLOADATTACH DSUpload, DSSaveProps, and DSCreate should

upload attachment items which have been
attached to the ItemObj through an enumerator
obtained from
ItemObj.EnumObjects(DSCONTF_ATTACH).

ITEMOBJ_OPTION_KEEPALLVER DSUpload should, if necessary, increase the

<max_versions> property of a file and preserve all
of the file's existing versions before uploading the
newest version.

ITEMOBJ_OPTION_LINKTOGATEWAY Read only; indicates that an asynchronous task

ItemObj is performing, has subscribed to the event
notification of GatewayHandler and is receiving
network events. The received events are
forwarded to either an event sink DItemObjEvents
interface or the application’s status UI object
IDsAccessStatusUI interface.

ITEMOBJ_OPTION_MULTICOMMANDS Read only; indicates that a method call such as

DSMove, invoked multiple gateway commands,
such as rename before move, following a name
conflict arbitration. Visibility of this flag is limited to
a DItemObjEvents event sink.

ITEMOBJ_OPTION_PRELOADCUSTPROPS Specifies that when referenced,

ItemObj.CorePropIds, should call
ItemObj.PreloadCustomProps internally and
identify all custom properties that are currently
defined in a DocuShare server. If a custom
property exists, CorePropIds sets the
DSAXES_PROPID_CORE_CUSTOM flat to True.

ITEMOBJ_OPTION_ALWAYSDELETE DSDelete should always delete the item. If this

flag is not set, DSDelete removes the item from
the collection that ItemObj.ParentItemObject
represents; if the item appears in multiple
collections, it does not delete the item.

ITEMOBJ_OPTION_SKIPIPCNOTIFY A DocuShare task that the ItemObj performs (for

example DSUpload), should not cause a refresh
notification to be sent to peer processes on the
client machine.

ITEMOBJ_OPTION_SETACL DSUpload, DSSaveProps, and DSCreate should

save ItemObj.IsPrivate and other ACL settings in
the server.

ITEMOBJ_OPTION_EMBEDDEDATTACH Signifies that the ItemObj is an OLE attachment

and ItemObj.Data contains a numeric position
where the attachment should appear within the
content data of the preferred rendition. This flag is
used by a content preprocessor of Outlook Client.

5–88 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

Option Flags Description

ITEMOBJ_OPTION_ADDATTACHLIST A content preprocessor should add a rendition of a

list for attachments contained in the ItemObj. This
flag is used by a content preprocessor of Outlook
Client.

ITEMOBJ_OPTION_NOCOMPOUNDDOC DSUpload should upload as separate files:

• the preferred file rendition (files contained in
ItemObj.Contents)
• an alternate rendition
• attachments
If the server is DocuShare 3.0 or higher,
DSUpload stores a file with alternate attachments
as elements of a compound document.

ITEMOBJ_OPTION_KEEPDEFPROPSSTORE Preserves the PropStore setting previously set by

a ItemObj.SaveDefaultProps call. For example, if
this flag is not specified, a DSUpload DocuShare
task, causes clearing of the PropStore.

ITEMOBJ_OPTION_PREPROCESSCONT Instructs DSUpload, DSSaveProps, and DSCreate

to invoke a content preprocessor whose ProgID is
stored as Prop("DSClient
ContentPreprocessorProgID").

To keep the current settings, use a bitwise OR operation when enabling an optional setting in VB scripting.
In a C++ application, the following control flags may be OR with one or more option flags.

Option Flags Description

ITEMOBJ_OPTION_OFF Disables only the specified option flags.

ITEMOBJ_OPTION_ON Enables only the specified option flags.

A bit mask for the read-only options is defined as follows:

• ITEMOBJ_OPTIONS_READONLY =
– ITEMOBJ_OPTION_AUTODEL or
– ITEMOBJ_OPTION_RELOAD or
– ITEMOBJ_OPTION_ASYNCSLEEP or
– ITEMOBJ_OPTION_ASYNCDONE or
– ITEMOBJ_OPTION_LINKTOGATEWAY or
– ITEMOBJ_OPTION_MULTICOMMANDS

DocuShare Windows Client SDK 5–89

Objects DSItemEnumLib Library

ItemObj.CopyTo and EnumObj.CopyTo regard the following flags as uninheritable. Do not copy them to a
target ItemObj:

• ITEMOBJ_OPTION_AUTODEL
• ITEMOBJ_OPTION_RELOAD
• ITEMOBJ_OPTION_RELEASEGATE
• ITEMOBJ_OPTION_RELEASESERV
• ITEMOBJ_OPTION_ASYNCTHREAD
• ITEMOBJ_OPTION_ASYNCDONE
• ITEMOBJ_OPTION_LINKTOGATEWAY
• ITEMOBJ_OPTION_MULTICOMMANDS
• ITEMOBJ_OPTION_PRELOADCUSTPROPS
• ITEMOBJ_OPTION_SETACL
• ITEMOBJ_OPTION_PREPROCESSCONT

NOTE: The above constants are defined in C header file dsclient.h.

5–90 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

Owner

VB Owner As String

C++ CString GetOwner();

void SetOwner(LPCTSTR lpszNewValue);

Access Read/Write

The Owner property accesses the ItemObj owner’s name.

OwnerNum

VB OwnerNum As Long

C++ long GetOwnerNum();

void SetOwnerNum(long nNewValue);

Access Read/Write

The OwnerNum property accesses the current ItemObj owner’s numeric ID.

Parent

VB Parent As Long

C++ long GetParent();

void SetParent(long nNewValue);

Access Read/Write

The Parent property accesses the primary parent’s numeric handle for the current ItemObj. The parent of
an ItemObj is the location where the ItemObj appears. This property returns the primary parent, as ItemObj
can have more than one parent.

Parent is obsolete. Use ParentHandle instead.

ParentCount

VB ParentCount As Long

C++ long GetParentCount();

Access Read only

The ParentCount property returns the number of parents for the current ItemObj.

DocuShare Windows Client SDK 5–91

Objects DSItemEnumLib Library

ParentHandle

VB ParentHandle as String

C++ CString GetParentHandle();

void SetParentHandle( LPCTSTR );

Access Read/Write

ParentHandle contains the DocuShare handle for the primary parent object.

ParentHandleNum

VB ParentHandleNum as Long

C++ long GetParentHandleNum();

void SetGetParentHandleNum( long );

Access Read/Write

ParentHandleNum contains the handle number of the primary parent object.

ParentItemObject

VB ParentItemObject as Object ItemObj

C++ IDispatch* GetParentItemObject();

void SetParentItemObject( IDispatch* );

Access Read/Write

ParentItemObject contains a ItemObj that represents a parent item. A parent item may not be a collection.
If the item is a Version, it is a File.

Remarks
Contrast ParentItemObject to ContainerItemObj. The latter property always contains an item of a container
class, such as Collection, Calendar, or Bulletin Board.

The Parent property is equivalent to ContainerItemObject.HandleNum to maintain backward compatibility.

Whereas, the ParentHandleNum property is equivalent to ParentItemObject.HandleNum.

5–92 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

ParentType

VB ParentType as String

C++ CString GetParentType();

void SetParentType( LPCTSTR );

Access Read/Write

ParentType contains the type identifier for the primary parent object.

ParentTypeNum

VB ParentTypeNum as Long

C++ long GetParentTypeNum();

void SetParentTypeNum( long );

Access Read/Write

ParentTypeNum contains the type number for the primary parent object.

DocuShare Windows Client SDK 5–93

Objects DSItemEnumLib Library

PreferredRendition

VB PreferredRendition as Object ItemObj

C++ IDispatch* GetPreferredRendition();

void SetPreferredRendition( IDispatch* );

Access Read/Write

Picture

VB Picture as Object

C++ IDispatch* GetPicture();

Access Read only

Picture contains an interface IPicture object for an image MIME type file item. Picture attempts to load the
image content data from a file specified in ItemObj.Name. To cause automatic downloading of the file, set
ItemObj.Reload to True before referencing Picture. Alternately, call ItemObj.DSDownload and download
the file explicitly.

set fileObj = server.CreateObject("File-567")

fileObj.Reload = True
set pict = fileObj.Picture

Remarks
The image types for which IPicture objects can be created are:

• image/jpeg
• image/gif
• image/bmp

NOTE: IPicture is described in the Windows Platform SDK documentation.

5–94 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

Prop

VB Prop( PropName as Variant ) as Variant

C++ VARIANT GetProp( VARIANT* PropName );

void SetProp( VARIANT* PropName, VARIANT* NewValue );

Access Read/Write

Prop contains a DocuShare property value.

Parameters
PropName—a string containing the name of a property. A DSAXES_PROPID integer specifying a
DocuShare property, a PropertyID whose ID and ItemType properties specify a DocuShare property, or an
ItemSchema whose Name property specifies a DocuShare property.

Remarks
Prop offers a generalized method to access any property that is recognized by ItemObj. Internally, Prop
retrieves CustomProp if PropName contains a custom property or retrieves ClientProp if PropName
contains a client property.

Prop supports special property names but do not strickly represent actual properties. They are names that
Prop understands as aliases of official property names with either string pre-formatting or type screening
added. A special property name starts with an exclamation mark '!'. The table below lists the special
names.

Special Name Prop Value

!MediaType Same as Type for a non-file; file type for a file.

!MediaSize n items for a collection; n KB for a file.

!FileTitle Same as ValidatedFileName for a file; otherwise,

empty.

!UnderscoredFilename ValidatedFileName with space characters

converted to underscore characters.

!Document File title and file extension of Name.

!MaxVersions Same as MaxVersions for a file; otherwise,

E_INVALIDARG error.

!IsLocked Same as IsLocked for a file; otherwise,

E_INVALIDARG error.

!VersionNum Same as VersionNum for a file version; otherwise,

E_INVALIDARG error.

!Server.[PropName] Same as Server.[PropName] if Server is a valid

IServer; otherwise, E_FAIL error.

DocuShare Windows Client SDK 5–95

Objects DSItemEnumLib Library

Special Name Prop Value

!Gateway.[PropName] Same as GatewayHandler.[PropName] if ItemObj

can open a GatewayHandler; otherwise, E_FAIL
error.

!EventStartDateTime

!EventEndDateTime

!EventStartTime

!EventEndTime

A name in PropName that starts with an @ sign, specifies an ItemObj property. Therefore,
ItemObj.Prop(@Title) is equivalent to ItemObj.Title.

Normally, if a DocuShare property of the MENU type is referenced, ItemObj.Prop or ItemObj.CustomProp

returns the integer ordinal of a menu item selection. If it needs a text label assigned to the item, an
application can set PropName to the name of the menu property prefixed with a # sign.

If PropName does not contain a string and does not begin with any of the above prefix characters, ! , @ or
#, PropName is translated into a DSAXES_PROPID property ID. If the ID translation is successful, Prop
returns the value currently assigned to the property ID. If not, Prop checks for a custom property name,
PropName. If no custom property name, PropName exists, Prop tries ClientProp. If PropName is still not
resolved, Prop scans formatted display properties a second time. This time Prop does not look for the
starting special characters.

PropIds

VB PropIds as Long

C++ long GetPropIds();

void SetPropIds( long );

Access Read/Write

PropIds contains DSAXES_PROPID property IDs of server-side properties that are specific to the item
type.

Parameters
WantAllIds—optional; if set to True, causes PropIds to return a set of all property IDs that can be queried
for the item type. The set of IDs specific to type File is defined as DSAXES_PROPID_FILE_GETTABLE.
Separate ID sets are pre-defined for other base types. If WantAllIds is set to False, CorePropIds return a
set of property IDs that are editable. For example, the set of IDs for File is defined as
DSAXES_PROPID_FILE_SETTABLE.

Remarks
PropIds exclude IDs that are contained in ExcludedPropIds.

5–96 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

ReferrerItemObject

VB ReferrerItemObject as Object ItemObj

C++ IDispatch* GetReferrerItemObject();

void SetReferrerItemObject( IDispatch* );

Access Read/Write

ReferrerItemObject contains an ItemObj object of type DSXITEMTYPE_DOCUMENT (file),

DSXITEMTYPE_RENDITION (rendition), or DSXITEMTYPE_CONTELEM (content element) that is linked
to this ItemObj instance.

RequiredPropsAreSet

VB RequiredPropsAreSet as Boolean

C++ BOOL GetRequiredPropsAreSet();

Access Read only

RequiredPropsAreSet determines if required properties are all set for an item.

Remarks
ItemObj.Server must contain a global server map, such as a server mapped in Windows Explorer, so that
ItemObj can locate a correct cached schemata.

RequiredPropsAreSet runs an internal check on property values held by the ItemObj according to server
schemata and checks if the ItemObj contain values for all of the item's required properties.

DocuShare Windows Client SDK 5–97

Objects DSItemEnumLib Library

Server

VB Server as Object DSServerMap.Server

C++ IDispatch* GetServer();

void SetServer( IDispatch* );

Access Read/Write

Server contains a Server object that represents a DocuShare server containing the item represented by
ItemObj.

Remarks
Server supersedes DSServerMapId.

SortOrder

VB SortOrder As String

C++ CString GetSortOrder();

void SetSortOrder(LPCTSTR lpszNewValue);

Access Read/Write

The SortOrder property sets the sort order for a collection object.

Summary

VB Summary As String

C++ CString GetSummary();

void SetSummary(LPCTSTR lpszNewValue);

Access Read/Write

The Summary property accesses the summary information for an ItemObj.

5–98 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

TaskStatus

VB TaskStatus as Long

C++ long GetTaskStatus();

Access Read only

TaskStatus contains a status code from an asynchronous task in progress. Possible status codes.

Status Codes Description

DSAXES_E_CANCEL The task was canceled.

DSAXES_E_HTTP An HTTP error occurred.

DSAXES_E_WINSOCK A Windows socket error occurred.

DSAXES_INPROG The task is still in progress.

DSAXES_SUCCESS The task has completed successfully.

The following script starts a file upload asynchronously and watches TaskStatus until it is set to a code
different from DSAXES_INPROG.

set fileObj = collObj.CreateObject("File")

fileObj.Name = "c:\doc\proposal.doc"
fileObj.DSGatewayMode = fileObj.DSGatewayMode or DSAXES_MODE_ASYNCHRONOUS
status = fileObj.DSUpload
if status = DSAXES_INPROG then
while fileObj.TaskStatus = DSAXES_INPROG
'
' Do something useful here while the upload completes.
'
wend
status = fileObj.TaskStatus
end if

DocuShare Windows Client SDK 5–99

Objects DSItemEnumLib Library

Thumbnail

VB Thumbnail As StdPicture

C++ LPDISPATCH GetThumbnail();

void SetThumbnail(LPDISPATCH newValue);

Access Read/Write

The Thumbnail property retrieves the current ItemObj DocuShare server generated thumbnail
representation. The dispatch interfaces to a IPictureDisp interface. This interface is a standard VB object
interface.

Remarks
Set property Reload to True reloads the thumbnail picture when the Thumbnail property is referenced.

Thumbnail support is available for DocuShare server version 2.1 or higher. The behavior of the Thumbnail
property is undefined if the property is used in conjunction with an older version of DocuShare.

TimeAccessed

VB TimeAccessed As Date

C++ DATE GetTimeAccessed();

void SetTimeAccessed(DATE newValue);

Access Read/Write

The TimeAccessed property returns the last time the ItemObj was accessed.

Remarks
This property is not currently used.

TimeCreated

VB TimeCreated As Date

C++ DATE GetTimeCreated();

void SetTimeCreated(DATE newValue);

Access Read/Write

The TimeCreated property accesses the creation time of the current ItemObj.

5–100 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

TimeModified

VB TimeModified As Date

C++ DATE GetTimeModified();

void SetTimeModified(DATE newValue);

Access Read/Write

The TimeModified property returns the time the current ItemObj was modified.

Title

VB Title As String

C++ CString GetTitle();

void SetTitle(LPCTSTR lpszNewValue);

Access Read/Write

The Title property is the string text that is displayed for an ItemObj.

Remarks
The Title property refers to the display name of an item stored in DocuShare.

For a User object, use custom properties first_name and last_name to obtain the username which is the
user object's display name. The related property Name refers to the account name for a user object.

Type

VB Type As String

C++ CString GetType();

Access Read only

The Type property contains a language-specific descriptive name for the object type of an ItemObj object.
For example, property Type for an ItemObj object, BulletinBoard, yields Bulletin Board for English.
BulletinBoard is a language-neutral type identifier. Bulletin Board is an English-specific description of the
type BulletinBoard.

DocuShare Windows Client SDK 5–101

Objects DSItemEnumLib Library

TypeId

VB TypeId as String

C++ CString GetTypeId();

void SetTypeId( LPCTSTR )

Access Read/Write

TypeId contains a type identifier that determines the class of the DocuShare object associated with this
ItemObj object.

TypeIndex

VB TypeIndex(asOpenForm As Boolean) As Long

C++ long GetTypeIndex(BOOL asOpenForm);

Access Read only

TypeIndex is tied to the Icon property and contains the value of an index to the Opened or Closed item
icon.

Parameters
asOpenForm—TRUE to obtain the index number of the Opened item icon. FALSE to obtain the index to
the Closed item icon.

Remarks
TypeIndex can be used to build an index table for caching item icons.

The True value in this instance is for C/C++. The values correspond to TRUE = 1, and FALSE = 0. In Visual
Basic True = -1 and False = 0. Only the C/C++ Boolean definitions are valid for this interface.

5–102 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

TypeNum

VB TypeNum As Long

C++ long GetTypeNum();

void SetTypeNum(long nNewValue);

Access Read/Write

The TypeNum property sets or retrieves the type of object for the current ItemObj.

URL

VB URL As String

C++ CString GetUrl();

void SetUrl(LPCTSTR lpszNewValue);

Access Read/Write

The URL property accesses the http URL for the current ItemObj.

User

VB User As String

C++ CString GetUser();

void SetUser(LPCTSTR lpszNewValue);

Access Read/Write

The User property accesses the last user to modify the current ItemObj.

UserNum

VB UserNum As Long

C++ long GetUserNum();

void SetUserNum(long nNewValue);

Access Read/Write

The UserNum property accesses the numeric ID of the last user to modify the current ItemObj.

DocuShare Windows Client SDK 5–103

Objects DSItemEnumLib Library

ValidatedFileHandle

VB ValidatedFileHandle As String

C++ CString GetValidatedFileName();

Access Read only

The ValidatedFileName property returns a string, which consists of Windows file system legal characters,
for the local path to the current ItemObj.

Remarks
DocuShare does not impose any restrictions to the alphanumeric characters used in a filename. A file
uploaded from a non-Windows system may be a filename that is not valid for use in Windows.

Use ValidatedFileName to obtain a descriptive filename that is also validated for use in Windows. A
descriptive filename is generated by combining the display name of the Title property and the file extension
part of the Name property and replacing any illegal character with an underscore.

If the filename stored in the server does not contain a file extension, the MIME type of the file is used to
generate one if possible. If the generated filename is longer than the allowed name length that the work
folder of the DocuShare Client can accept, the filename is truncated. The maximum length roughly equals
256 minus the character length for the pathname of the DocuShare Client base work folder minus 50. This
amounts to approximately 150 characters for a typical Client installation.

If the work folder that an SDK application uses has a pathname longer than that of the DocuShare Client,
the application must ensure that the name generated by ValidatedFileName does not exceed the
maximum length allowed by the Windows file system.

For example, a file with a filename busdraft1-4.doc and a display name Business proposal draft - section 1/
4, was uploaded to DocuShare. With an ItemObj object representing this file, its ValidatedFileName
property yields a file name of Business proposal draft - section 1_4.doc. If the Name property contains the
fully qualified pathname of a file in the client machine, property ValidatedFileName returns the file title and
extension portion of the pathname.

dim file
set file = server.CreateObject("File")
file.Name = "c:\My Documents\busdraft.doc"
MsgBox(file.ValidatedFileName)
The last statement of the above script displays busdraft.doc which is the file title portion of the pathname
assigned to the Name property.

5–104 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

VersionNum

VB VersionNum As Long

C++ long GetVersionNum();

void SetVersionNum(long nNewValue);

Access Read/Write

The VersionNum property accesses the version number for the current ItemObj.

Remarks
VersionNum can be used in conjunction with DSDownload to copy a specific version of a DocuShare file to
a client machine.

VersionNum is automatically set when IServer.CreateObject is used to create a version object. The
following VB script creates a version object for version 4 of a DocuShare file whose handle is File-123 and
displays the represented version number:

dim fileVer
set fileVer = server.CreateObject("File-123/4")
MsgBox("Represented file version is " + CStr(fileVer.VersionNum))
VersionNum is only applicable to a version object. A file object cannot be used to set VersionNum.

DocuShare Windows Client SDK 5–105

Objects DSItemEnumLib Library

5.2.2 EnumObj
List of EnumObj methods and properties

Methods Properties

Attach Flags

Attach2 Length

Clear NextItem

CopyTo NextPos

GetLengthOf

GetNode

Load

NewItem

RemoveItem

Reset

Sort

5.2.2.1 EnumObj methods

This section contains the EnumObjects method definitions.

Attach

VB Attach(pEnumDisp as Object) As Long

C++ long Attach(LPDISPATCH pEnumDisp);

The Attach method attaches a list of child items.

Parameters
pEnumDisp—an ItemEnum object. The ItemEnum object needs to be valid.

Return value

Value Description

NO_ERROR The method was successful.

ERROR_OUTOFMEMORY The system has insufficient memory resources.

ERROR_INVALID_PARAMETER An invalid ItemEnum object was passed to the

method.

5–106 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

Attach2

VB Attach2(Item as ItemObj, Flags as optional Variant) as ItemObj

C++ IDispatch* Attach2( IDispatch* Item, VARIANT* Flags );

Attach2 attaches an ItemObj to an enumerator object.

Parameters

Parameter Description

Item An ItemObj object to attach to the enumerator.

Flags Optional, the following flags may be specified.

Flag Description

ENUMOBJ_ATTACH2_DONTCOPY Do not attach a copy of Item. Attach Item directly

to the enumerator.

ENUMOBJ_ATTACH2_INSERTATCURPOS Insert Item at the current enumeration position.

In addition, ITEMOBJ_COPYTOFLAG flags may be specified as long as the flags are within the bitfield
range given by ENUMOBJ_ATTACH2_COPYMASK (=0x0000FFFF).

Return value
An ItemObj object if the Attach operation was successful. If the ENUMOBJ_ATTACH2_DONTCOPY option
was used, the returned object is the same input Item object. Otherwise, the returned object is a copy of
Item, which was actually added to the enumerator. If an error occurs, a NULL object is returned.

Remarks
If the ENUMOBJ_ATTACH2_DONTCOPY flag is used, make sure Item does not belong to another
enumerator object. If it has obtained Item from another enumerator, an application must call
EnumObj.RemoveItem against the old enumerator and remove Item from the old enumerator before it can
attach Item to a new enumerator.

Attach2 differs from the Attach method in that the latter always makes a copy of the input ItemObj and
attaches it to the enumerator, while the former can optionally attach the original ItemObj instead of a copy
of the original. Also, Attach2 can attach an ItemObj at the current enumeration position while Attach always
adds an ItemObj to the tail position.

DocuShare Windows Client SDK 5–107

Objects DSItemEnumLib Library

Clear

VB Clear() as Long

C++ long Clear();

Clear removes all items from an enumerator object.

Parameters
None

Return value
DSAXES_SUCCESS—the object cleared successfully.

CopyTo

VB CopyTo(pEnumObj as ItemEnum) as Long

C++ long CopyTo(LPDISPATCH pEnumObj);

The CopyTo method copies the item list of the current ItemEnum object to another ItemEnum object.

Parameters
pEnumObj—the target ItemEnum object.

Return value

Value Description

NO_ERROR The method was successful.

ERROR_OUTOFMEMORY The system has insufficient memory resources.

ERROR_INVALID_PARAMETER An invalid ItemEnum was passed to the method.

5–108 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

GetLengthOf

VB GetLengthOf(pItemObj as ItemObj, subItemType As Long) As Long

C++ long GetLengthOf(LPDISPATCH pItemObj, long subItemType);

The GetLengthOf method count sub-items belonging to the specified item.

Parameters

Parameter Description

pItemObj A valid ItemObj to be counted.

subItemType Select the item types to be counted.

ENUMOBJ_GLOTYPE_ALL Count all the items in this ItemEnum object.

ENUMOBJ_GLOTYPE_COLL Count only collection items in this ItemEnum

object.

ENUMOBJ_GLOTYPE_FILE Count only file items in this ItemEnum object.

Return value
The quantity of numbered sub-items belonging to the ItemObj passed to the function.

GetNode

VB GetNode(nCollHandle as Long) as ItemObj

C++ LPDISPATCH GetNode(long nCollHandle);

The GetNode method returns an ItemObj that is the root to the passed collection.

Parameters
nCollHandle—the collection handle to find the root node.

Return value
ItemObj—an ItemObj that is connected to the found root node.

DocuShare Windows Client SDK 5–109

Objects DSItemEnumLib Library

Load

VB Load(dwFlags As Long, bsPathName as String) As Long

C++ long Load(long dwFlags, LPCTSTR bsPathName);

The Load method loads a DocuShare item list file.

Parameters

Parameter Description

bsPathName Pathname for a file containing a DSGateway

generated item list.

pRes Address of a variable for receiving the result code.

dwFlags—zero or a combination of the following bit flags.

NOTE: If dwFlags is zero, it is replaced with DSCONTF_ALL.

Flags Description

DSCONTF_PARENT Load the parent information from the source file.

DSCONTF_FOLDERS Load the collection information from the source

file.

DSCONTF_DOCUMENTS Load the document information from the source

file.

DSCONTF_NONDOCUMENTS Load the non-document item information from the

source file.

DSCONTF_VERSIONS Load the version information from the source file.

DSCONTF_IDENTITY Load the property information from the source file.

DSCONTF_DESCENDANTS Load the descendant collection tree from the

source file.

DSCONTF_ASCENDANTS Load the ascendent collection tree that leads to

this object from the source file.

DSCONTF_ASCEND_ROOTFIRST Load the collection tree, beginning with the root

object, from the source file.

DSCONTF_CHILDREN Load all the children items from the source file.

DSCONTF_ALL Load all the items from the source file.

5–110 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

Return value

Value Description

NO_ERROR The method was successful.

ERROR_NOT_ENOUGH_MEMORY The system has insufficient memory resources.

ERROR_OUTOFMEMORY An invalid ItemEnum object was passed to the

method.

E_FAIL An unknown general failure occurred.

Remarks
pRes contains NO_ERROR upon successful loading of the list. pRes may contain
ERROR_NOT_ENOUGH_MEMORY or ERROR_OUTOFMEMORY if a space allocation error is
encountered. If the file cannot be opened, pRes contains the error code reported by the operating system.

NewItem

VB NewItem() as ItemObj

C++ LPDISPATCH NewItem();

The NewItem method creates a blank item and adds it to the list.

DocuShare Windows Client SDK 5–111

Objects DSItemEnumLib Library

RemoveItem

VB RemoveItem(pItemObj As ItemObj) As Long

C++ long RemoveItem(LPDISPATCH pItemObj);

The RemoveItem method removes an item from the list.

Parameters
pItem—the pItemObj to be deleted.

Return value

Value Description

S_OK The method was successful.

S_FALSE The method failed.

Reset

VB Reset() As Long

C++ long Reset();

The Reset method resets the enumeration position.

Parameters
None

Return value

Value Description

NO_ERROR The method was successful.

ERROR_NO_MORE_ITEMS There are no items in the current ItemEnum

object.

Remarks
Always call this method before calling Next.

5–112 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

Sort

VB Sort(SortKeyFlags as long, SortOrderFlags as long) as Long

C++ long Sort(long SortKeyFlags, long SortOrderFlags);

Sorts the items contained in an enumerator object based on a sort key and sort order.

Parameters
SortKeyFlags—must be set to 0 or one of the ITEMOBJ_COMPARE_xxx flags.

Flags Description

ITEMOBJ_COMPARE_TYPE Sort by item type.

ITEMOBJ_COMPARE_HANDLE Sort by item handle.

ITEMOBJ_COMPARE_PARENT Sort by parent handle.

ITEMOBJ_COMPARE_LENGTH Sort by length (number of items or file size).

ITEMOBJ_COMPARE_OWNER Sort by owner.

ITEMOBJ_COMPARE_USER Sort by user (last user who modified or locked the

object).

ITEMOBJ_COMPARE_OWNERNAME Sort by username.

ITEMOBJ_COMPARE_TITLE Sort by title.

ITEMOBJ_COMPARE_SUMMARY Sort by summary.

ITEMOBJ_COMPARE_FILENAME Sort by filename.

ITEMOBJ_COMPARE_MIMETYPE Sort by MIME type (content type).

ITEMOBJ_COMPARE_CREATETIME Sort by creation date/time.

ITEMOBJ_COMPARE_MODIFYTIME Sort by last modification date/time.

SortOrderFlags—the following flags can be specified.

Flags Description

ENUMOBJ_SORT_ASCEND Use ascending order.

ENUMOBJ_SORT_DESCEND Use descending order.

ENUMOBJ_SORT_REVERSE Reverse the order.

DocuShare Windows Client SDK 5–113

Objects DSItemEnumLib Library

Return value

Value Description

DSAXES_SUCCESS The items in the enumerator were successfully

sorted.

ERROR_INVALID_PARAMETER SortKeyFlags contains an invalid flag.

Remarks
This script retrieves a collection and uses the Sort method to sort the item list and print the sorted list.

set collObj = server.CreateObject("Collection-10")

collObj.DSLoadChildren
set enumObj = collObj.EnumObjects(0)
enumObj.Sort(0, ENUMOBJ_SORT_ASCEND)
enumObj.Reset
while enumObj.NextPos <> 0
set itemObj = enumObj.NextItem
Print itemObj.Title, itemObj.Handle
wend

5–114 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

5.2.2.2 EnumObj properties

This section contains the property definitions of the EnumObj object.

Flags

VB Flags as Long

C++ long GetFlags();

Access Read/Write, Hidden

Contains flags for controlling the loading of enumeration data from a stream source.

Remarks
This property is hidden from scripting applications. It is used by C++ applications that need to load
enumeration data into an IEnumObj object through the latter object's IPersistStream interface.

The script below obtains a stream on enumeration data and load it into an IEnumObj object. The Flags
property is used to pass the DSCONTF_CHILDREN flag. The IPersistStream::Load method is then called
to collect children items from the stream.

IStream* pstrm;
... // Create a stream on item listing data.
IEnumObj* peo;
CoCreateInstance(CLSID_ItemEnum, ..., IID_IEnumObj, (LPVOID*)&peo);
IPersistStream* pps;
peo->QueryInterface(IID_IPersistStream, (LPVOID*)&pps);
peo->put_Flags(DSCONTF_CHILDREN);
pps->Load(pstrm);
pps->Release();
pstrm->Release();
... // do something with the IEnumObj.
peo->Release();

Length

VB Length As Long

C++ long GetLength();

Access Read only

The Length property returns the number for the ItemObj object held by the current ItemEnum object.

DocuShare Windows Client SDK 5–115

Objects DSItemEnumLib Library

NextItem

VB NextItem as ItemObj

C++ LPDISPATCH GetNextItem();

Access Read only

The NextItem property returns the next item in the enumerator.

NextPos

VB NextPos As Long

C++ long GetNextPos();

Access Read only

The NextPos property obtains and returns the position of the next item.

Remarks
NextPos returns -1 if there are no more items.

5–116 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

5.2.3 EnumSchema
List of EnumSchema methods and properties

EnumSchema Methods and Properties

Length NewItem

Load Reset

NextItem RemoveItem

NextPos

5.2.3.1 EnumSchema methods

This section contains the EnumSchema method definitions.

NewItem

VB NewItem() as Object ItemSchema

C++ IDispatch* NewItem();

Creates a blank item and adds it to the list.

Reset

VB Reset() as Long

C++ long Reset();

Resets the enumeration position.

RemoveItem

VB RemoveItem(pItemSchema as Object ItemSchema) as Long

C++ long RemoveItem( IDispatch* pItemSchema );

Removes an item from the list.

Load

VB Load(SchemaData as Object, Class as optional Variant, Server as optional

Variant ) as Long

C++ long Load( IDispatch* SchemaData, VARIANT* Class, VARIANT* Server );

Loads schemata from a ServerResponse or EnumObj object.

DocuShare Windows Client SDK 5–117

Objects DSItemEnumLib Library

5.2.3.2 EnumSchema properties

This section contains the EnumSchema property definitions.

Length

VB Length as Long

C++ long GetLength();

Access Read only

Contains the number of items held by the enumerator.

NextItem

VB NextItem as Object ItemSchema

C++ IDispatch* GetNextItem();

Access Read only

Contains the next item.

NextPos

VB NextPos as Long

C++ long GetNextPos();

Access Read only

Contains the position for the next item (0, if there are no more items).

5–118 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

5.2.4 ItemSchema
List of ItemSchema methods and properties

Methods Properties

ResetMenu Name

NewMenuItem Label

RemoveMenuItem TypeNum

ClearMenu HelpText

CopyTo IsSystem

IsRequired

IsReadOnly

DefaultValue

MinimumValue

MaximumValue

MenuLength

NextMenuItem

NextMenuPos

TypeStr

PropsEnumerator

IsMultivalued

Server

ItemObject

ItemTypeNum

DocuShare Windows Client SDK 5–119

Objects DSItemEnumLib Library

5.2.4.1 ItemSchema methods

This section contains the ItemSchema method definitions.

ResetMenu

VB ResetMenu() as Long

C++ long ResetMenu();

Resets the menu position.

NewMenuItem

VB NewMenuItem( bsItem as String ) as Long

C++ long NewMenuItem( LPCTSTR bsItem );

Creates a blank menu item and adds it to the menu.

RemoveMenuItem

VB RemoveMenuItem( bsItem as String) as Long

C++ long RemoveMenuItem( LPCTSTR bsItem );

Removes a menu item from the menu.

ClearMenu

VB ClearMenu as Long

C++ long ClearMenu();

Makes the destination object into an identical copy of the source object.

CopyTo

VB CopyTo( pItemSchema as Object ItemSchema) as Long

C++ long CopyTo( IDispatch* pItemSchema );

Makes the destination object into an identical copy of the source object.

5–120 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

5.2.4.2 ItemSchema properties

This section contains the ItemSchema property definitions.

Name

VB Name as String

C++ CString GetName();

void SetName( LPCTSTR );

Access Read/Write

Label

VB Label as String

C++ CString GetLabel();

void SetLabel( LPCTSTR );

Access Read/Write

TypeNum

VB TypeNum as Long

C++ long GetTypeNum();

void SetTypeNum( long );

Access Read/Write

HelpText

VB HelpText as String

C++ CString GetHelpText();

void SetHelpText( LPCTSTR );

Access Read/Write

DocuShare Windows Client SDK 5–121

Objects DSItemEnumLib Library

IsSystem

VB IsSystem as Boolean

C++ BOOL GetIsSystem();

void SetIsSystem( BOOL );

Access Read/Write

IsRequired

VB IsRequired as Boolean

C++ BOOL GetIsRequired();

void SetIsRequired( BOOL );

Access Read/Write

IsReadOnly

VB IsReadOnly as Boolean

C++ BOOL GetIsReadOnly();

void SetIsReadOnly( BOOL );

Access Read/Write

DefaultValue

VB DefaultValue as Variant

C++ VARIANT GetDefaultValue();

void SetDefaultValue( VARIANT* );

Access Read/Write

5–122 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

MinimumValue

VB MinimumValue as Variant

C++ VARIANT GetMinimumValue();

void SetMinimumValue( VARIANT* );

Access Read/Write

MaximumValue

VB MaximumValue as Variant

C++ VARIANT GetMaximumValue();

void SetMaximumValue( VARIANT* );

Access Read/Write

MenuLength

VB MenuLength as Long

C++ long GetMenuLength();

Access Read only

NextMenuItem

VB MenuLength as Long

C++ long GetMenuLength();

Access Read only

DocuShare Windows Client SDK 5–123

Objects DSItemEnumLib Library

NextMenuPos

VB NextMenuPos as Long

C++ long GetNextMenuPos();

Access Read only

Contains the next menu item's position (0 if there is no more item).

TypeStr

VB TypeStr as String

C++ CString GetTypeStr();

void SetTypeStr( LPCTSTR );

Access Read/Write

PropsEnumerator

VB PropsEnumerator as Object EnumSchemaProps

C++ IDispatch* GetPropsEnumerator();

Access Read only

IsMultivalued

VB IsMultivalued as Boolean

C++ BOOL GetIsMultivalued();

void SetIsMultivalued( BOOL );

Access Read/Write

5–124 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

ItemTypeNum

VB ItemTypeNum as Long

C++ long GetItemTypeNum();

void SetItemTypeNum( long );

Access Read/Write

Contains the DocuShare object class associated with this schema.

Server

VB Server as Object DSServerMap.Server

C++ IDispatch* GetServer();

void SetServer( IDispatch* );

Access Read/Write

Contains the DocuShare server associated with this schema.

ItemObject

VB ItemObject as Object ItemObj

C++ IDispatch* GetItemObject();

Access Read only

Contains an ItemObj for the DocuShare object class associated with this schema.

5.2.5 EnumSchemaProps
List of EnumSchemaProps methods and properties.

EnumSchemaProps Methods and Properties

Length NextPos

NextItem Reset

NextItem

5.2.5.1 EnumSchemaProps methods

This section contains the EnumSchemaProps method definitions.

DocuShare Windows Client SDK 5–125

Objects DSItemEnumLib Library

Reset

VB Reset as Long

C++ long Reset();

Resets enumeration position.

Next

VB Next( Status as Long ) as Object SchemaProp

C++ IDispatch* Next( long* Status );

This method is hidden.

5.2.5.2 EnumSchemaProps properties

This section contains the EnumSchemaProps method definitions.

Length

VB Length as Long

C++ long GetLength();

Access Read only

Number of items held by the enumerator.

5–126 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

NextItem

VB NextItem as Object SchemaProp

C++ IDispatch* GetNextItem();

Access Read only

NextPos

VB NextPos as Long

C++ long GetNextPos();

Access Read only

5.2.6 SchemaProp
List of SchemaItemProp properties.

Properties

Name

TypeNum

Value

5.2.6.1 SchemaProp methods

There are no methods defined for this object.

5.2.6.2 SchemaProp properties

This section contains the SchemaProp property definitions.

Name

VB Name as String

C++ CString GetName();

Access Read only

DocuShare Windows Client SDK 5–127

Objects DSItemEnumLib Library

TypeNum

VB TypeNum as Long

C++ long GetTypeNum();

Access Read only

Value

VB Value as Variant

C++ VARIANT GetValue();

Access Read only

5–128 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

5.2.7 EnumItemProps
List of EnumItemProps methods and properties

EnumItemProps Methods and Properties

Clear NextPos

Item NextPos

Length Reset

NextPos RemoveItem

NextItem

5.2.7.1 EnumItemProps methods

This section contains the EnumItemProps method definitions.

Clear

VB Clear() as long

C++ long Clear();

Removes all ItemProp objects from an enumerator.

NewItem

VB NewItem() as ItemProp

C++ IDispatch* NewItem();

NewItem creates a new ItemProp object and attaches it to an enumerator.

Next

VB Next( Status as Long ) as Object ItemProp

C++ IDispatch* Next( long* Status );

This method is hidden.

RemoveItem

VB RemoveItem(Item as ItemProp) as long

C++ long RemoveItem( IDispatch* Item );

Removes an ItemProp object from an enumerator.

DocuShare Windows Client SDK 5–129

Objects DSItemEnumLib Library

Reset

VB Reset() as Long

C++ long Reset();

Reset brings the enumeration position to the head position.

5–130 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

5.2.7.2 EnumItemProps properties

This section contains the EnumItemProps property definitions.

Item

VB Item( Index as Variant ) as Object ItemProp

C++ Dispatch* GetItem( VARIANT* Index );

Access Read only

The property contains an ItemProp object of a specified enumeration index.

Parameters
Index—an integer specifying an enumeration index.

Length

VB Length as Long

C++ long GetLength();

Access Read only

Contains the enumeration length that is the number of ItemProp objects belonging to the enumerator.

NextPos

VB NextPos as Long

C++ long GetNextPos();

Access Read only

Contains the next enumeration position if another ItemProp object is available. If not, NextPos contains a
zero.

NextItem

VB NextItem as Object ItemProp

C++ IDispatch* GetNextItem();

Access Read only

Contains the next ItemProp object if one is available. If not, NextItem contains a NULL object.

DocuShare Windows Client SDK 5–131

Objects DSItemEnumLib Library

Remarks
Checks the value of NextPos before referencing NextItem. NextPos contains a non-zero if NextItem
contains a valid ItemProp object.

set enumProps = itemObj.EnumProps

enumProps.Reset
while enumProps.NextPos <> 0
set propObj = enumProps.NextItem
...
wend

5–132 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

5.2.8 ItemProp
List of ItemProp methods and properties

EnumItemProps Methods and Properties

CreateControl Name

ID Scope

EnumPropValues Type

ID Value

ItemSchema XMLName

Label

5.2.8.1 ItemProp methods

This section contains the ItemProp method definitions.

CreateControl

VB CreateControl(Host as Object, Options as Variant) as Object

C++ IDispatch* CreateControl( IDispatch* Host, VARIANT* Options );

CreateControl creates an instance of the DocuShare PropObj ActiveX control on a client machine. The
PropObj instance renders a DocuShare property that the ItemProp represents in a display field.

CopyTo

VB CopyTo(Target as ItemProp) as long

C++ long CopyTo( IDispatch* Target );

Copies contents of a source ItemProp to a target ItemProp.

EnumValues

VB EnumValues(Flags as long) as EnumPropValues

C++ IDispatch* EnumValues( long Flags );

EnumValues creates a value enumerator object.

Parameters
Flags—optional, not currently used; should be set to zero.

DocuShare Windows Client SDK 5–133

Objects DSItemEnumLib Library

5.2.8.2 ItemProp properties

This section contains the ItemProp property definitions.

ID

VB ID as Long

C++ long GetID();

void SetID( long );

Access Read/Write

ID contains a DSAXES_PROPID if the ItemProp represents a DocuShare property. Otherwise, ID contains

a zero.

ItemSchema

VB ItemSchema

C++

Access Read/Write

ItemSchema contains an ItemSchema object that represents the DocuShare schema for the DocuShare
property represented by ItemProp. If the ItemProp does not represent a DocuShare property, ItemSchema
is empty.

Scope

VB ITEMOBJPROPSCOPE

C++

Access Read/Write

Scope contains one of the ITEMOBJPROPSCOPE flags, and determines whether the property that the
ItemProp represents belong to a DocuShare server, a library, or an application of the DocuShare Client. If
the scope is undefined, the Scope property contains a zero.

• ITEMOBJPROPSCOPE_SERVER
• ITEMOBJPROPSCOPE_CLIENT

5–134 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

Type

VB Type as ITEMOBJPROPTYPE

C++ ITEMOBJPROPTYPE GetType();

void SetType( ITEMOBJPROPTYPE );

Access Read/Write

Type contains one of the ITEMOBJPROPTYPE flags, and determines whether the property that the
ItemProp represents is a core property, custom property, or application-specific property of DocuShare
(only if Scope is ITEMOBJPROPSCOPE_SERVER or ITEMOBJPROPSCOPE_CLIENT).

• ITEMOBJPROPTYPE_CORE
• ITEMOBJPROPTYPE_CUSTOM
• ITEMOBJPROPTYPE_APP

Name

VB Name as String

C++ CString GetName();

void SetName( LPCTSTR );

Access Read/Write

Contains the name of a property.

XMLName

VB XMLName as String

C++ CString GetXMLName();

Access Read only

XMLName contains the XML element name of a DocuShare property. If no XML name is defined for the
property, XMLName is empty.

DocuShare Windows Client SDK 5–135

Objects DSItemEnumLib Library

Label

VB Label as String

C++ CString GetLabel();

void SetLabel( LPCTSTR );

Access Read/Write

Label contains the label of a property.

Value

VB Value as Variant

C++ VARIANT GetValue();

void SetValue( VARIANT* );

Access Read/Write

Contains the value of a property. If the property is multi-valued, the Value property contains the first entry of
the value.

5–136 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

5.2.9 EnumPropValues
List of EnumPropsValue methods and properties.

EnumPropValues Methods and Properties

Clear NextPos

Item NewItem

Length RemoveItem

NextItem Reset

NextItem

5.2.9.1 EnumPropValues methods

This section contains the EnumPropValues method definitions.

Clear

VB Clear() as long

C++ long Clear();

Clear removes all PropValue objects from an enumerator.

Next

VB Next( Status as Long ) as Object

C++ IDispatch* Next( long* Status );

NewItem

VB NewItem() as ItemProp

C++ IDispatch* NewItem();

NewItem creates a new ItemProp object and attaches it to an enumerator.

RemoveItem

VB RemoveItem(Item as ItemProp) as long

C++ long RemoveItem( IDispatch* Item );

Removes a PropValue object from an enumerator.

DocuShare Windows Client SDK 5–137

Objects DSItemEnumLib Library

Reset

VB Reset() as Long

C++ long Reset();

Reset brings the enumeration position to the head position.

5–138 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

5.2.9.2 EnumPropValues properties

This section contains the EnumPropValues property definitions.

Item

VB Item(Index as Variant) as Object PropValue

C++ IDispatch* GetItem( VARIANT* Index );

Access Read only

Contains a PropValue object of a specified enumeration index.

Parameters
Index—an integer specifying an enumeration index.

Length

VB Length as Long

C++ long GetLength();

Access Read only

Length contains the enumeration length that is the number of PropValue objects belonging to the
enumerator.

NextItem

VB NextItem as Object PropValue

C++ IDispatch* GetNextItem();

Access Read only

NextItem contains the next PropValue object if one is available. If not, NextItem contains a NULL object.

Remarks
Applications should check the value of NextPos before de-referencing NextItem. NextPos contains a
non-zero value if NextItem contains a valid PropValue object.

set enumVals = itemProp.EnumValues

enumVals.Reset
while enumVals.NextPos <> 0
set propVal = enumVals.NextItem
...
wend

DocuShare Windows Client SDK 5–139

Objects DSItemEnumLib Library

NextPos

VB NextPos as Long

C++ long GetNextPos();

Access Read only

NextPos contains the next enumeration position if another PropValue object is available. If not, NextPos
contains a zero.

5–140 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

5.2.10 PropValue
List of PropValue methods and properties

Methods and Properties

Index

Value

XMLValue

5.2.10.1 PropValue methods

There are no methods defined for this object.

5.2.10.2 PropValue properties

This section contains the PropValue property definitions.

Index

VB Index as Long

C++ long GetIndex();

Access Read only

Contains a zero-based enumeration index. An index is generated and assigned to the PropValue when an
EnumPropValues enumerator, to which the PropValue belongs, is generated.
EnumPropValues.Item(Index) can be used to retrieve the PropValue object.

Value

VB Value as Variant

C++ VARIANT GetValue();

void SetValue( VARIANT * );

Access Read/Write

Contains a value entry of a DocuShare or DocuShare Client property.

DocuShare Windows Client SDK 5–141

Objects DSItemEnumLib Library

XMLValue

VB XMLValue as String

C++ CString GetXMLValue();

void SetXMLValue( LPCTSTR );

Access Read/Write

Contains a value entry in XML.

5–142 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

5.2.11 ErrorReportObj
List of ErrorReportObj methods and properties

ErrorReportObj Methods and Properties

AttemptedCommand Init

ClientRequest LogFile

DSAccessData Report

ErrorCode ServerResponse

ErrorDescription SetErrorInfo

ErrorDisplayType ShowDialog

ErrorPhrase Silent

GatewaySettings StatusCode

5.2.11.1 ErrorReportObj methods

This section contains the ErrorReportObj method definitions.

Init

VB Init(ClientRequest as object, ServerResponse as object, GatewaySettings as

object, DSAccessData as object)

C++ void Init(IDispatch* ClientRequest, IDispatch* ServerResponse, IDispatch*

GatewaySettings, IDispatch* DSAccessData);

Initializes the ErrorReportObj with gateway objects. The method keeps copies of the objects.

Return value
None.

Report

VB Report()

C++ void Report();

Runs a simple dialog to display error information if the property, Silent, is set to False.

DocuShare Windows Client SDK 5–143

Objects DSItemEnumLib Library

SetErrorInfo

VB SetErrorInfo (AttemptedCommand as string, ErrorType as string, ErrorPhrase

as string, LogFile as string)

C++ void SetErrorInfo (LPCTSTR AttemptedCommand, LPCTSTR ErrorType,

LPCTSTR ErrorPhrase, LPCTSTR LogFile);

SetErrorInfo sets AttemptedCommand, ErrorType, ErrorPhrase, and LogFile to specified values.

ShowDialog

VB ShowDialog (ShowDetails as optional Variant)

C++ void ShowDialog (VARIANT* ShowDetails);

Parameters
ShowDetails can be set to one of the following:

• ERRDISP_SIMPLE—shows error code and phrase.

• ERRDISP_DETAIL—shows detailed error info. If this parameter is not specified, ERRDISP_SIMPLE
will be used.

5–144 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

5.2.11.2 ErrorReportObj properties

This section contains the ErrorReportObj property definitions.

AttemptedCommand

VB AttemptedCommand as String

C++ CString GetAttemptedCommand();

void SetAttemptedCommand( LPCTSTR );

Access Read/Write

AttemptedCommand contains a failed command for which an error was raised.

ClientRequest

VB ClientRequest as Object ClientRequest

C++ IDispatch* GetClientRequest();

Access Read only

ClientRequest contains a client request object that was in use when an error was encountered.

DSAccessData

VB DSAccessData as Object DSAccessData

C++ IDispatch* GetDSAccessData();

Access Read only

DSAccessData contains a client access data object that was in use when an error was encountered.

ErrorCode

VB ErrorCode as Long

C++ long GetErrorCode();

void SetErrorCode( long );

Access Read/Write

ErrorCode contains an error code.

DocuShare Windows Client SDK 5–145

Objects DSItemEnumLib Library

ErrorDescription

VB ErrorDescription as String

C++ CString GetErrorDescription();

void SetErrorDescription( LPCTSTR );

Access Read/Write

ErrorDescription contains a string that details an error.

ErrorDisplayType

VB ErrorDisplayType as DSX_ERRDISP

C++ DSX_ERRDISP GetErrorDisplayType();

Access Read only

Contains one of the following DSX_ERRDISP flags.

Flag Description

ERRDISP_CUSTOM Ran a custom error dialog.

ERRDISP_DETAIL Ran a detailed error dialog.

ERRDISP_MSGBOX Ran a message box dialog.

ERRDISP_NONE Did not displayed any dialog box.

ERRDISP_SIMPLE Ran a simple error dialog.

ErrorPhrase

VB ErrorPhrase as String

C++ CString GetErrorPhrase();

void SetErrorPhrase( LPCTSTR );

Access Read/Write

ErrorPhrase contains a short string that summarizes an error.

5–146 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

GatewaySettings

VB GatewaySettings as Object (interface IGatewaySettings)

C++ IDispatch* GetGatewaySettings();

Access Read only

GatewaySettings contains a gateway settings object that was in use when an error was encountered.

LogFile

VB LogFile as String

C++ CString GetLogFile();

void SetLogFile( LPCTSTR );

Access Read/Write

LogFile contains the pathname of a log file. A log file records network activities up to the point an error is
encountered.

DocuShare Windows Client SDK 5–147

Objects DSItemEnumLib Library

ServerResponse

VB ServerResponse as Object ServerResponse

C++ IDispatch* GetServerResponse();

Access Read only

ServerResponse contains a server response object that was in use when an error was encountered.

Silent

VB Silent as Boolean

C++ BOOL GetSilent();

void SetSilent( BOOL );

Access Read/Write

Silent determines if the Report method should run an error dialog or not. If Silent is set to True, a dialog is
not run. By default, Silent is set to True.

StatusCode

VB StatusCode as Long

C++ long GetStatusCode();

void SetStatusCode( long );

Access Read/Write

StatusCode contains a DSAXES_SUCCESS or DSAXES_E status code from a DocuShare command that
has failed.

5–148 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

5.2.12 NameConflictResolver
List of NameConflictResolver methods and properties

Methods and Properties

AutoComment ReplacedItemHandle

CollectionObject ResolveLocalName

ErrorDisplayType ResolveRemoteName

FixedComment ResolveRemoteName2

ForceRename RunCommentDialog

ForceReplace VersionComment

Rename

5.2.12.1 NameConflictResolver methods

This section contains the NameConflictResolver method definitions.

Rename

VB Rename(Item as ItemObj, StatusUI as variant) as DSX_NAMECONFRES

C++ DSX_NAMECONFRES Rename(IDispatch* Item, VARIANT* StatusUI);

Renames an item programmatically or by running a rename dialog for manual editing.

Parameters

Parameter Description

Item Contains an ItemObj to be renamed. The method

modifies the value for Item.Title by having a user
manually edit the title string or by
programmatically prepending a set phrase to the
existing title.

StatusUI Optional HWND of a window that owns a rename

dialog window. If this parameter is not specified, a
rename dialog is not run.

DocuShare Windows Client SDK 5–149

Objects DSItemEnumLib Library

Return value

Value Description

NAMECONFRES_CANCEL A user canceled the rename dialog.

NAMECONFRES_NONE No action was taken. Item has not been renamed

or canceled by the user.

NAMECONFRES_RENAME Item was successfully renamed. The new name is

stored in Item.Title.

Remarks
If StatusUI is specified, the method internally runs RenameUI to run a rename dialog.

If StatusUI is omitted or empty, the method does not run a dialog to obtain a new name (title) for the item.
Instead, the method generates a new name programmatically by adding a Copy of prefix to the existing
title and returns the result code NAMECONFRES_RENAME.

5–150 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

ResolveLocalName

VB ResolveLocalName(LocalPath as string, RemoteSize as long,

RemoteModifiedTime as date, IsLastItem as boolean, CanShowError as
boolean, CanAskUser as boolean, CanCheckModified as boolean) as
DSX_NAMECONFRES

C++ DSX_NAMECONFRES ResolveLocalName(LPCTSTR LocalPath, long

RemoteSize, DATE RemoteModifiedTime, BOOL IsLastItem, BOOL
CanShowError, BOOL CanAskUser, BOOL CanCheckModified);

ResolveLocalName tests by name if a DocuShare file or collection conflicts with a file or subdirectory in the
same directory on a client machine. If there is a conflict, ResolveLocalName runs a UI to resolve the
conflict.

Parameters

Parameter Description

CanAskUser Specifies if a UI should be produced for interactive

resolution with a user.

CanCheckModified Specifies if the file size and modification time

should be compared. If the size is different from
the size of the latest version in DocuShare, the
local version needs to be replaced.

CanShowError Specifies if an encountered error during

processing should be displayed.

IsLastItem The file or folder specified in LocaPath is the last

item to be tested.

LocalPath Destination path for a download of the DocuShare

file or collection to be tested for a name conflict.

RemoteModifiedTime The last time the DocuShare file or collection was

modified.

RemoteSize The byte size of the DocuShare file or collection.

Return value
One of the DSX_NAMECONFRES codes.

Value Description

NAMECONFRES_ALWAYSREPLACE The tested item should replace the name in the

same directory, and the caller should assume that
all subsequent items, if any, replace existing
names.

NAMECONFRES_CANCEL The resolution was canceled by a user.

DocuShare Windows Client SDK 5–151

Objects DSItemEnumLib Library

Value Description

NAMECONFRES_FILELOCKED The method detected that there is a file at the

destination path, the file is locked, and an attempt
to open it caused the OS to raise a sharing
violation.

NAMECONFRES_FILEOPENERROR The method detected that there is a file at the

destination path, and an attempt to open it caused
the OS to raise an unrecoverable error.

NAMECONFRES_RENAME The tested item should be renamed. If

Item.HandleNum is not zero, Item's handle
conflicts with an item in CollectionObject. Item
should be uploaded as a new file to preserve the
existing item.

NAMECONFRES_REPLACE The tested item should replace the name in the

same directory.

NAMECONFRES_SKIP Two cases are possible. 1) A file is already at the

specified path, and a user chooses to skip the file
in a resolution dialog. 2) A file is already at the
specified path with the same file size and last
modification date. It is assumed that the local file
is identical to the remote file in DocuShare. The
file does not need to be downloaded.

5–152 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

ResolveRemoteName

VB ResolveRemoteName(LocalPath as string, nItemType as long, RemoteItemList

as EnumObj, IsLastItem as booleaen, CanShowError as boolean, CanAskUser
as boolean, CanAlwaysReplace as boolean) as DSX_NAMECONFRES

C++ DSX_NAMECONFRES ResolveRemoteName(LPCTSTR LocalPath, long

nItemType, IDispatch* RemoteItemList, BOOL IsLastItem, BOOL
CanShowError, BOOL CanAskUser, BOOL CanAlwaysReplace);

ResolveRemoteName tests, by name or handle, for conflicts with existing items in a specified collection
and runs a UI to resolve the conflict.

Parameters

Parameter Description

CanAlwaysReplace Specifies if a button can replace, with a test item, a

name item that conflicts with an existing item.

CanAskUser Specifies if a UI should be produced for interactive

resolution with a user.

CanShowError Specifies if an error encountered during

processing should be displayed.

IsLastItem The file or folder specified in LocaPath is the last

item to be tested.

LocalPath Pathname of a file or folder to be tested for a

name conflict.

nItemType Item type of the tested file or folder.

RemoteItemList An enumerator containing a collection of items.

The filename portion of LocalPath is checked for a
conflict amongst these items.

Return value
One of the DSX_NAMECONFRES conflict resolution codes below.

Value Description

NAMECONFRES_ALWAYSREPLACE The tested item should replace the same name in

RemoteItemList, and the caller should assume
that all subsequent items, if any, replace existing
names.

NAMECONFRES_CANCEL The resolution was canceled by a user.

NAMECONFRES_FILELOCKED The method detected that a file specified in

LocalPath is locked and caused the OS to raise a
sharing violation.

DocuShare Windows Client SDK 5–153

Objects DSItemEnumLib Library

Value Description

NAMECONFRES_FILEOPENERROR The method encountered an error in opening a file

specified in LocalPath.

NAMECONFRES_NONE No action was taken.

NAMECONFRES_RENAME The tested item should be renamed.

NAMECONFRES_REPLACE The tested item should replace the same name in

RemoteItemList.

NAMECONFRES_SKIP The tested item should be skipped.

Remarks
If CanAskUser is True, a dialog is run to resolve a name conflict. If a replace action is taken, the method
runs CommentUI and obtains a version comment from a user. The obtained comment string is stored in
VersionComment. If the dialog is canceled, NAMECONFRES_CANCEL is returned. If the user chooses to
skip the item, NAMECONFRES_SKIP is returned.

If CanAskUser is False, CanAlwaysReplace is True, and a name conflict is encountered, a dialog is not
run. VersionComment is cleared and a result code of NAMECONFRES_ALWAYSREPLACE is returned.

The DocuShare handle of a replaced item is stored in ReplacedItemHandle.

5–154 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

ResolveRemoteName2

VB ResolveRemoteName2(ObjToTest as ItemObj, lFlags as long, StatusUI as

optional variant) as DSX_NAMECONFRES

C++ DSX_NAMECONFRES ResolveRemoteName2(IDispatch* ObjToTest, long

lFlags, VARIANT* StatusUI);

ResolveRemoteName2 tests, by name or handle, for conflicts with existing items in a collection specified
by CollectionObject and runs a UI to resolve the conflict.

Parameters

Parameter Description

ObjToTest Contains an ItemObj that represents an item to be

tested for name conflicts against the items
contained in an enumerator of property
CollectionObject.

StatusUI Optional HWND of a window that should own a

name resolution UI. If StatusUI is omitted, the
Win32 API function GetActiveWindow is used to
obtain the handle of a currently active window.

lFlags—contains one or both of the following flags:

• NAMECONFRES_RESOLVE_BYHANDLE—resolve a handle conflict.
• NAMECONFRES_RESOLVE_BYNAME—resolve a name conflict.

Return value
One of the DSX_NAMECONFRES codes.

Value Description

NAMECONFRES_ALWAYSREPLACE The tested item should replace the name in

CollectionObject, and the caller should assume
that all subsequent items, if any, replace existing
names.

NAMECONFRES_CANCEL The resolution was canceled by a user.

NAMECONFRES_FILELOCKED The method detected that a file specified in

ObjToTest is locked and caused the OS to raise a
sharing violation.

NAMECONFRES_FILEOPENERROR The method encountered an error in opening a file

specified in ObjToTest.

NAMECONFRES_NONE No action was taken.

DocuShare Windows Client SDK 5–155

Objects DSItemEnumLib Library

Value Description

NAMECONFRES_RENAME The tested item should be renamed. If

Item.HandleNum is not zero, Item's handle
conflicts with an item in CollectionObject. Item
should be uploaded as a new file to preserve the
existing item.

NAMECONFRES_REPLACE The tested item should replace the name in

CollectionObject.

NAMECONFRES_SKIP The tested item should be skipped.

Remarks
If NAMECONFRES_RESOLVE_BYNAME is specified, there is a name match, ForceReplace is False, and
ForceRename is False, a dialog runs to let a user decide what to do. If
NAMECONFRES_RESOLVE_BYHANDLE is also specified, the dialog runs to resolve a handle conflict.
NAMECONFRES_RENAME, NAMECONFRES_NONE, NAMECONFRES_SKIP and
NAMECONFRES_CANCEL are possible result codes.

If NAMECONFRES_RESOLVE_BYHANDLE is not specified, the dialog runs to resolve a name conflict. If

a user chooses a replace action, ObjToTest.HandleNum is set to HandleNum of a conflicting item in
CollectionObject. A resolution code, NAMECONFRES_REPLACE or
NAMECONFRES_ALWAYSREPLACE, is returned. If the action is NAMECONFRES_ALWAYSREPLACE,
ForceReplace is set to True internally, the next time the method is called, a test item's handle automatically
sets to a conflicting item's handle without raising a dialog.

If NAMECONFRES_RESOLVE_BYNAME is specified, there is a name match, and ForceReplace is True,

ObjToTest.HandleNum is set to HandleNum of a conflicting item in CollectionObject. A resolution code,
NAMECONFRES_REPLACE, is returned.

If NAMECONFRES_RESOLVE_BYNAME is specified, there is a name match, and ForceRename is True,

NAMECONFRES_RENAME is returned. ObjToTest is not modified in any way. The caller must perform
renaming after regaining control.

Unlike ResolveRemoteName, ResolveRemoteName2 does not store the DocuShare handle of a replaced
item in ReplacedItemHandle. Instead, the replaced item's handle is stored in ObjToTest.Handle.
ResolveRemoteName2 does not use VersionComment.

5–156 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

RunCommentDialog

VB RunCommentDialog(Item as ItemObj, StatusUI as variant) as

DSX_NAMECONFRES

C++ DSX_NAMECONFRES RunCommentDialog(IDispatch* Item, VARIANT*

StatusUI);

RunCommentDialog runs a comment input dialog.

Parameters

Parameter Description

Item Contains an ItemObj object. Item.Comment is set

to a comment string that a user enters in the
dialog.

StatusUI Optional HWND of a window that owns the input

dialog window. If StatusUI is omitted, the Win32
API function GetActiveWindow is used to obtain
the active window handle.

Return value
One of the DSX_NAMECONFRES codes.

Remarks
If AutoComment is True, a dialog is not run. If FixedComment is not empty, ItemObj.Comment is set to it.

The method internally runs CommentUI to run an input dialog.

DocuShare Windows Client SDK 5–157

Objects DSItemEnumLib Library

5.2.12.2 NameConflictResolver properties

This section contains the NameConflictResolver property definitions.

AutoComment

VB AutoComment as Boolean

C++ BOOL GetAutoComment();

void SetAutoComment( BOOL );

Access Read/Write

AutoComment determines if RunCommentDialog should set ItemObj.Comment to FixedComment without

running an input UI.

CollectionObject

VB CollectionObject as Object EnumObj

C++ IDispatch* GetCollectionObject();

void SetCollectionObject( IDispatch* );

Access Read/Write

CollectionObject contains an EnumObj object that enumerates items in a DocuShare collection.

ResolveRemoteName2 uses CollectionObject as the items to test an input ItemObj object for a name or
handle conflict.

ErrorDisplayType

VB ErrorDisplayType as DSX_ERRDISP

C++ DSX_ERRDISP GetErrorDisplayType();

Access Read only

ErrorDisplayType contains a DSX_ERRDISP error display type identifier. A possible value is

ERRDISP_MSGBOX, signifying that an error message box was displayed by methods
ResolveRemoteName and ResolveLocalName with the parameter CanShowError set to True.

5–158 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

FixedComment

VB FixedComment as String

C++ CString GetFixedComment();

void SetFixedComment( LPCTSTR );

Access Read/Write

FixedComment contains a version comment string. If AutoComment is True, RunCommentDialog sets

ItemObj.Comment to the FixedComment string without running an input UI.

ForceRename

VB ForceRename as Variant

C++ VARIANT GetForceRename();

void SetForceRename( VARIANT* );

Access Read/Write

ForceRename determines if a rename action should be taken automatically by ResolveRemoteName2.

ForceReplace

VB ForceReplace as Variant

C++ VARIANT GetForceReplace();

void SetForceReplace( VARIANT* );

Access Read/Write

ForceReplace determines if a replace action should be taken automatically by ResolveRemoteName2.

DocuShare Windows Client SDK 5–159

Objects DSItemEnumLib Library

ReplacedItemHandle

VB ReplacedItemHandle as String

C++ CString GetReplacedItemHandle();

Access Read only

ReplacedItemHandle contains the DocuShare object handle of an item subject to a replace action by
ResolveRemoteName.

VersionComment

VB VersionComment as String

C++ CString GetVersionComment();

Access Read only

VersionComment contains a comment string edited by a user during a call to ResolveRemoteName.

5–160 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

5.2.13 StatusObj
List of StatusObj methods and properties

Methods and Properties

CanCancel ShowDialog

CancelCode ShowProgress

CanReportNetworkProgress SubLowerLimit

CanReportNetworkStatus Subscribe

CanShowStatusAsBalloonTip SubText

CreateThread SubUpperLimit

GatewayEventWindow Text

HideDialog Title

HideProgress TopMostDialog

IconPath UpperLimit

LowerLimit Visible

ParentWindow WindowHandle

Progress

5.2.13.1 StatusObj methods

This section contains the StatusObj method definitions.

HideDialog

VB HideDialog()

C++ void HideDialog();

HideDialog hides the status dialog box.

HideProgress

VB HideProgress()

C++ void HideProgress();

HideProgress hides the progress bar from the status dialog box.

DocuShare Windows Client SDK 5–161

Objects DSItemEnumLib Library

ShowDialog

VB ShowDialog()

C++ void ShowDialog();

ShowDialog shows a status dialog box.

ShowProgress

VB ShowProgress()

C++ void ShowProgress();

ShowProgress shows a progress bar on the status dialog box.

5–162 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

Subscribe

VB Subscribe(ListnerClass as Variant, Param as Variant)

C++ void Subscribe(VARIANT* ListnerClass, VARIANT* Param);

Subscribes to notification from the system tray for the associated icon.

Parameters

Parameter Description

ListnerClass ProgID of a system tray event handler for

subscribing to the notification service. See
Remarks below for implementing an event
handler.

Param Optional; set Param to an application-defined

integer value. When a system tray notification is
forwarded to the application, the integer value is
passed to the application as lParam in the above
handler functions

Return value
None

Remarks
An application must implement the following event handling functions:

// left button click on system tray icon

HRESULT OnSystemTrayLeftButtonDown(HWND hwndStatusDlg, long lParam,
VARIANT_BOOL* pbHandled);
// right button click on system tray icon
HRESULT OnSystemTrayRightButtonDown(HWND hwndStatusDlg, long lParam,
VARIANT_BOOL* pbHandled);
// left button double-click on system tray icon
HRESULT OnSystemTrayLeftButtonDoubleClick(HWND hwndStatusDlg, long lParam,
VARIANT_BOOL* pbHandled);
// right button double-click on system tray icon
HRESULT OnSystemTrayRightButtonDoubleClick(HWND hwndStatusDlg, long lParam,
VARIANT_BOOL* pbHandled);

DocuShare Windows Client SDK 5–163

Objects DSItemEnumLib Library

The meaning of the parameters:

• hwndStatusDlg—HWND of the status dialog window.

• lParam—Value of Param passed to the Subscribe method.
• pbHandled—Set this to VARIANT_TRUE if the application has handled the event.
The DocuShare Client library that manages the system tray notification takes the following steps to forward
an event to a subscribing application.

1. Convert the ListnerClass progID of the application's event handler to a CLSID.

2. Create an instance of the handler class by calling CoCreateInstance with the CLSID from step 1
and obtain a pointer to the IDispatch interface.
3. Call IDispatch::GetIDsOfNames with the name array containing an entry to obtain a DISPID for the
event handling function via the IDispatch::Invoke method. The entry is set to the name of a event
handling function, such as OnSystemTrayLeftButtonDown.
4. Call IDispatch::Invoke for the obtained DISPID passing the above parameters.

5–164 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

5.2.13.2 StatusObj properties

This section contains the StatusObjects property definitions.

CanCancel

VB CanCancel as Boolean

C++ BOOL GetCanCancel();

void SetCanCancel( BOOL );

Access Read/Write

CanCancel determines if the Cancel button is activated or not.

CancelCode

VB CancelCode as Long

C++ long GetCancelCode();

void SetCancelCode( long );

Access Read/Write

CancelCode contains a cancel code used by the gateway notification window.

CanReportNetworkProgress

VB Boolean

C++

Access Read/Write

CanReportNetworkProgress determines if the DocuShare Client Gateway can show and update a
progress bar for a network call in progress.

DocuShare Windows Client SDK 5–165

Objects DSItemEnumLib Library

CanReportNetworkStatus

VB CanReportNetworkStatus as Boolean

C++ BOOL GetCanReportNetworkStatus();

void SetCanReportNetworkStatus( BOOL );

Access Read/Write

CanReportNetworkStatus determines if the DocuShare Client Gateway can show and update the status of
a network call in progress.

CanShowStatusAsBalloonTip

VB CanShowStatusAsBalloonTip as Boolean

C++ BOOL GetCanShowStatusAsBalloonTip();

void SetCanShowStatusAsBalloonTip( BOOL );

Access Read/Write

CanShowStatusAsBalloonTip determines if an info tip is shown in a balloon over the icon on the system
tray.

CreateThread

VB CreateThread as Boolean

C++ BOOL GetCreateThread();

void SetCreateThread( BOOL );

Access Read/Write

CreateThread determines if the dialog box should run on a separate thread.

5–166 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

GatewayEventWindow

VB GatewayEventWindow as OLE_HANDLE

C++ HWND GetGatewayEventWindow();

void SetGatewayEventWindow( HWND );

Access Read/Write, hidden

GatewayEventWindow contains the window handle of a hidden notification window managed by a

DocuShare Client gateway.

IconPath

VB IconPath as String

C++ CString GetIconPath();

void SetIconPath( LPCTSTR );

Access Read/Write

IconPath contains the pathname of a file on a client machine that contains icon data. The icon data is used
to render an icon in the system tray area.

LowerLimit

VB LowerLimit as Long

C++ long GetLowerLimit();

void SetLowerLimit( long );

Access Read/Write

LowerLimit sets the primary lower limit of the progress bar.

DocuShare Windows Client SDK 5–167

Objects DSItemEnumLib Library

ParentWindow

VB ParentWindow as OLE_HANDLE

C++ HWND GetParentWindow();

void SetParentWindow( HWND );

Access Read/Write, hidden

ParentWindow contains the window handle for a parent window.

Progress

VB Progress as Long

C++ long GetProgress();

void SetProgress( long );

Access Read/Write

Progress sets the current position for the progress bar.

SubLowerLimit

VB SubLowerLimit as Long

C++ long GetSubLowerLimit(();

void SetSubLowerLimit( long );

Access Read/Write

SubLowerLimit sets the secondary lower limit for the progress bar.

5–168 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

SubText

VB SubText as String

C++ CString GetSubText();

void SetSubText( LPCTSTR );

Access Read/Write

SubText contains subordinate message text to be shown on the dialog box.

SubUpperLimit

VB SubUpperLimit as Long

C++ long GetSubUpperLimit();

void SetSubUpperLimit( long );

Access Read/Write

SubUpperLimit sets the secondary upper limit for the progress bar.

Text

VB Text as String

C++ CString GetText();

void SetText( LPCTSTR );

Access Read/Write

Text contains main message text to be shown on the dialog box.

Title

VB Title as String

C++ CString GetTitle();

void SetTitle( LPCTSTR );

Access Read/Write

Title contains a title to be shown on the caption bar of the dialog box.

DocuShare Windows Client SDK 5–169

Objects DSItemEnumLib Library

TopMostDialog

VB TopMostDialog as Boolean

C++ BOOL GetTopMostDialog();

void SetTopMostDialog( BOOL );

Access Read/Write

TopMostDialog determines if the dialog box is a top-most window.

UpperLimit

VB UpperLimit as Long

C++ long GetUpperLimit();

void SetUpperLimit( long );

Access Read/Write

UpperLimit sets the primary upper limit for the progress bar.

Visible

VB Visible as Boolean

C++ BOOL GetVisible();

void SetVisible( BOOL );

Access Read/Write

Visible determines if the icon on the system tray is visible or not.

WindowHandle

VB WindowHandle as OLE_HANDLE

C++ HWND GetWindowHandle();

Access Read only, Hidden

WindowHandle contains a window handle for the dialog box.

5–170 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

5.2.14 CommentUI
5.2.14.1 CommentUI methods
This section contains the CommentUI method definitions.

RunDialog

VB RunDialog(ItemObj as object) as DSX_NAMECONFRES

C++ DSX_NAMECONFRES RunDialog(IDispatch* ItemObj);

RunDialog displays a user interface for manually editing a comment string.

Parameters
ItemObj—contains the Comment property of an ItemObj object that is displayed and editable by a user.

Remarks
None

5.2.14.2 CommentUI Properties

This section contains the CommentUI property definitions.

WindowHandle

VB WindowHandle as OLE_HANDLE

C++ HWND GetWindowHandle();

void SetWindowHandle( HWND );

Access Read/Write

WindowHandle contains the window handle for the window that owns the input dialog window.

DocuShare Windows Client SDK 5–171

Objects DSItemEnumLib Library

5.2.15 RenameUI
5.2.15.1 Rename methods
This section contains the RenameUI method definitions.

RunDialog

VB RunDialog(ItemObj as object) as DSX_NAMECONFRES

C++ DSX_NAMECONFRES RunDialog(IDispatch* ItemObj);

RunDialog displays a user interface for manually editing a name string.

Parameters
ItemObj—contains the Title property of an ItemObj object that is displayed and editable by a user.

Remarks
NameConflictResolver.Rename uses RenameUI to run a rename dialog. It essentially performs the
following:

• set dlg = CreateObject("DSUtilityLib.RenameUI")

• dlg.WindowHandle = StatusUI
• result = dlg.RenameUI(Item)
Where StatusUI and Item are the input parameters of NameConflictResolver and contains, respectively, an
owner window handle and an ItemObj object whose Title property is editable by a user.

5.2.15.2 Rename properties

This section contains the RenameUI property definitions.

WindowHandle

VB WindowHandle as OLE_HANDLE

C++ HWND GetWindowHandle();

void SetWindowHandle( HWND );

Access Read/Write

WindowHandle contains the window handle for the window that owns the rename dialog window.

5–172 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

5.2.16 EnumPresets
A DocuShare preset is a set of default property values that is intended for pre-populating properties,
possibly saving users from manually entering the same data repeatedly. In DocuShare 5.0, presets exist
for the sole purpose of pre-populating Records Management classification properties. Presets are a
general concept that, in future DocuShare releases of DocuShare, may support pre-populating DocuShare
properties as well. Because of this generality, the interfaces for accessing presets were placed in the
DSItemEnumLib library.

EnumPresets is an enumerator object that enumerates the presets that have been assigned to a given
DocuShare user. The presets are loaded into the enumerator when either EnumPresets::AddItemObject or
IItemObj::EnumPresets is called. The presets are obtained for the authenticated DocuShare user who is
associated with the IItemObj object. A preset is placed into the enumerator, if it was assigned specifically
to that DocuShare user (a personal preset), or to a group which the user is a member, either directly or
indirectly (a group preset).

One of the presets assigned to a DocuShare user can be designated as the default preset. The scope of
this designation is Client only. The server has no notion of a default preset. The IClassificationEditorUI
dialog loads the default preset if one is not explicitly set.

A default value can be designated for the usePersonalPreset setting. When pre-populating properties from
a group preset, this setting controls whether the property values are sourced from the group preset only, or
merged with the values from a corresponding personal preset. The personal preset that corresponds to a
group preset is the one that has the same record type as the group preset. Values from the group preset
have precedence over values from the corresponding personal preset. The IClassificationEditorUI dialog
uses the default usePersonalPreset value if one is not explicitly set.

5.2.16.1 EnumPresets methods

This section contains the EnumPresets method definitions.

AddItemObject

VB Sub AddItemObject(pItemObj As Object)

C++ void AddItemObject(LPDISPATCH pItemObj)

Loads the enumerator. The presets are obtained for the authenticated DocuShare user associated with the
IItemObj parameter.

Function Next

VB Function Next( pRes As Long ) As IPreset

C++ LPDISPATCH Next( long* pRes );

Function Reset

VB Function Reset() As Long

C++ long Reset();

DocuShare Windows Client SDK 5–173

Objects DSItemEnumLib Library

Property Length

VB Property Length As Long

C++ long GetLength();

Property nextItem

VB Property nextItem As IPreset

C++ LPDISPATCH GetNextItem();

Property NextPos

VB Property NextPos As Long

C++ long GetNextPos();

5.2.16.2 EnumPresets properties

DefaultPreset

VB DefaultPreset As IPreset

C++ LPDISPATCH GetDefaultPreset();

void SetDefaultPreset(LPDISPATCH newValue);

Access Read/Write

DefaultPreset is an IPreset object that specifies the default preset.

UsePersonalPreset

VB UsePersonalPreset As Boolean

C++ BOOL GetUsePersonalPreset();

void SetUsePersonalPreset(BOOL bNewValue);

Access Read/Write

UsePersonalPreset specifies the default value of the use personal preset setting described above.

5–174 DocuShare Windows Client SDK

DSItemEnumLib Library Objects

5.2.17 IPreset
The IPreset interface describes a preset. A preset has a name, display name, record type, and an owner
handle that indicates whether it is a group preset or a personal preset. Presets are DocuShare entities, but
they are not DocuShare objects; they do not have a DocuShare handle. The DocuShare Client SDK does
not support creating or deleting presets. These functions are expected to be performed by DocuShare
users via the DocuShare Web UI.

5.2.17.1 IPreset properties

This section contains the IPreset property definitions.

DisplayName

VB Property DisplayName As String

C++ CString GetDisplayName();

Access Read only

DSOwnerHandle

VB Property DSOwnerHandle As String

C++ CString GetDSOwnerHandle();

Access Read only

Property Name
VB Property Name As String

C++ CString GetName();

Access Read only

RecordType

VB Property RecordType As Long

C++ long GetRecordType();

Access Read only

DocuShare Windows Client SDK 5–175

Compound document support DSItemEnumLib Library

5.3 Compound document support

5.3.1 Constituent File Layout of Compound Document in PC
Folder "abc123"

+--- Primary rendition file "abc123.htm"

+--- Optional folder "image"
| +--- Optional folder "gif"
| | +--- File of content element 1 "pic1.gif"
| +--- Optional folder "jpeg"
| +--- File of content element 2 "pic2.jpg"
| +--- File of content element 3 "pic3.jpg"
+--- Optional folder "application"
| +--- Optional folder "pdf"
| +--- File of content element 4 "pamph.pdf"
| +--- Optional folder "msword"
| +--- File of content element 5 "greetings.doc"
+--- Optional folder "_Properties"
| +--- Data file "abc123.xml"
+--- Optional folder "_AltRenditions"
+--- Alternate rendition file "abc123.msg"

5.3.2 Alternate Layout—IE-style Connected File

Primary rendition file "abc123.htm"

+--- Folder "abc123_files"

+--- File of content element 1 "pic1.gif"
+--- File of content element 2 "pic2.jpg"
+--- File of content element 3 "pic3.jpg"
+--- File of content element 4 "pamph.pdf"
+--- File of content element 5 "greetings.doc"
|
+--- Optional folder "_Properties"
| +--- Data file "abc123.xml"
|
+--- Optional folder "_AltRenditions"
+--- Alternate rendition file "abc123.msg"

5–176 DocuShare Windows Client SDK

DSItemEnumLib Library Compound document support

fileObj.Name = "abc123.htm"
fileObj.CompoundContainer.Name = "c:\doc\abc123"
fileObj.Options = fileObj.Options or ITEMOBJ_OPTION_UPDATELINKS
fileObj.DSUpload

5.3.3 Downloading Compound Document

GET <-compound> [file handle] [destination path]
set fileObj = server.CreateObject("File-123")
fileObj.Name = "c:\doc\abc123\abc123.htm"
' fileObj.CompoundContainer.Name = "c:\doc\abc123"
fileObj.DSDownload
MsgBox fileObj.CompoundContainer.Name ' This prints "c:\doc\abc123"

5.3.4 Finding Out Content Elements

set fileObj = server.CreateObject("File-123")
fileObj.DSLoadProps
set renditions = fileObj.EnumObjects(DSCONTF_RENDITIONS)
renditions.Reset
while renditions.NextPos <> 0
set item = renditions.NextItem
MsgBox "Rendition: " + item.Name + " (" + item.Handle + ")"
wend
set attachments = fileObj.EnumObjects(DSCONTF_ATTACHMENTS)
attachments.Reset
while attachments.NextPos <> 0
set item = attachments.NextItem
MsgBox "Attachment: " + item.Name + " (" + item.Handle + ")"
wend

DocuShare Windows Client SDK 5–177

Compound document support DSItemEnumLib Library

5–178 DocuShare Windows Client SDK

 Properties and Permission Controls
Properties and Permissions Controls are visual ActiveX controls that provide intuitive user
interfaces for viewing and editing DocuShare object properties and permissions. This chapter
contains the following:

• PropObj. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6–2
• DsPropsObj. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6–4
• PermObj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6–7

DocuShare Windows Client SDK 6–1

PropObj Properties and Permission Controls

6.1 PropObj
PropObj is a visual ActiveX control that provides a user interface for viewing and editing a single
DocuShare property. It provides SDK programmers with an easy-to-use component for rendering a
DocuShare property in a consistent, user-friendly representation. The property can be a standard
DocuShare property or a custom DocuShare property. The control supports the following DocuShare
property types:

• Boolean
• Date
• Email
• Float
• Integer
• Menu
• String
• Text
• URL.
Salient features of this control:

• All visual aspects of the property are obtained from the DocuShare server's schemata. The property
attributes from the schema that visually affect the control are: Label, Required, Read Only, Default
Value, Multi-valued, Help Text, Choices, Minimum, Maximum, and Length. When a DocuShare
administrator changes a property's schema, these changes are realized in the control.
• The control provides an inherent help system by attaching a tooltip to each DocuShare property.
The tooltip contains the help text from each property's schema.
• The control is language-neutral since all visual aspects are obtained from the server.
• The visual representation is based on the property's type. For example, the editor for a Date-typed
property is the Windows date/time picker control. The editor for an Integer-typed property is a
numeric-only edit control, paired with a spin control.

6.1.1 IPropCtrl Method

SetMode (long mask, long mode)—The SetMode method provides an easy way to selectively set or unset
mode bits without affecting the other bits. Use the mask argument to identify the bits that you wish to
modify by setting the bit to 1. Bits, where the mask is 0, are unaffected. Set the mode argument to the
desired state.

6–2 DocuShare Windows Client SDK

Properties and Permission Controls PropObj

6.1.2 IPropCtrl properties

Property Description

BackColor (OLE_COLOR) Indicates the control's background color.

DSServerMapId (long) Identifies the DocuShare server associated with

the itemSchema property. The control may need
to contact the server if it needs information beyond
what is in the schemata.

Enable (BOOL) Renders the property in an enabled or disabled

state.

ItemSchema (LPDISPATCH) The ItemSchema property identifies the

DocuShare property that the control is rendering.

MinimumHeight (long) The MinimumHeight property indicates the

minimum height, in pixels, that is required to show
the entire control.

Mode (long) The Mode property allows an SDK programmer to

change the control's behavior. The following flags
are supported:
• PROPCTRL_SHOWLABEL—Indicates that the
property's label should be visible.
• PROPCTRL_SHOWVALUE—Indicates that the
property's value should be visible.
• PROPCTRL_SHOWTOOLTIP—Indicates that
the property's help text should be visible in a
tooltip.

PropertyModified (BOOL) Indicates whether the property's value was

modified.

PropValue (VARIANT) Indicates the property's current value. If the

property's current value is multi-valued, its
representation is an IEnumPropValues object.

ReadOnly (BOOL) Renders the property's value as non-editable.

This is typically used to override a property that is
normally writable as specified in the property's
schema.

6.1.3 IPropCtrlEvents Event

PropertyModified()—The PropertyModified event is raised when a user modifies the property's value.
SDK programmers typically use this indication to enable an Apply button.

DocuShare Windows Client SDK 6–3

DsPropsObj Properties and Permission Controls

6.2 DsPropsObj
DsPropsObj is a visual ActiveX control that provides an intuitive user interface for viewing and editing the
properties of a DocuShare object. The user interface is similar to the one that Microsoft Office presents for
viewing and editing the properties of an Office document.

The DsPropsObj control graphically portrays DocuShare properties in a two column layout. The first
column, labeled Property, contains a Windows tree-view control that list the names of the properties. An
SDK programmer can specify which properties to include in this view. An SDK programmer can also
request that related properties be grouped into tree-view folders for easier navigation. The second column,
labeled Value, renders the values of the properties that appear in the tree-view. The second column is also
where in-place editing of the property values takes place.

The DsPropsObj control supports the following DocuShare objects, along with the derived custom objects:
Bulletin, BulletinBoard, Calendar, Collection, Document, Event, Group, Saved Query, Subscription, URL,
User.

Salient features of this control are:

• All visual aspects of a DocuShare property are obtained from the DocuShare server's schemata. The
property attributes from the schema that visually affect the control are: Label, Required, Read Only,
Default Value, Multi-valued, Help Text, Choices, Minimum, Maximum, and Length. When a
DocuShare administrator changes a property's schema, these changes are realized in the control.
• The control provides an inherent help system by attaching a tooltip to each DocuShare property. The
tooltip contains the help text from each property's schema.
• Properties are rendered language-neutral since all visual aspects of a DocuShare property are
obtained from the server.
• The control offers in-place editing of property values. This provides users with a more modern,
streamlined, and intuitive user interface.
• The control selects an in-place editor based on the property's type. For example, the editor for a
Date-typed property is the Windows date/time picker control. The editor for an Integer-typed property
is a numeric-only edit control, paired with a spin control.
• The control supports viewing and editing the DocuShare properties of multiple DocuShare objects,
even if the objects are of different classes. If a property has distinct values amongst multiple objects,
its value is rendered with the text, multiple values.

6–4 DocuShare Windows Client SDK

Properties and Permission Controls
6.2.1 IDsPropsCtrl Methods
Method
AddItemObject (LPDISPATCH pItemObj)
Apply()
SetMode (long mask, long mode)
DocuShare Windows Client SDK
DsPropsObj
Description
Call the AddItemObject method to enter a
DocuShare object. The combined properties of all
entered DocuShare objects are shown in the
control's view.
The Apply method apply the property value edits
to all of the entered DocuShare objects.
The SetMode method provides an easy way to
selectively set or unset mode bits without affecting
the other bits. Use the mask argument to identify
the bits that you wish to modify by setting the bit to
1. Bits, where the mask is 0, are unaffected. Set
the mode argument to the desired state.
6–5
DsPropsObj Properties and Permission Controls

6.2.2 IDsPropsCtrl Properties

Property Description

Mode (long) The Mode property allows an SDK programmer to

change the control's behavior. The following flags
are supported:
• DSPROPS_GROUP_BY_OBJTYPE—Indicates
that item-specific properties should be grouped
into item-specific folders. For example,
max_versions is a property that is specific to
Document objects. This flag is primarily useful if
the DsPropsObj control is used to show the
properties of DocuShare objects of different
classes.
• DSPROPS_REQUIREDPROPS—Indicates that
required properties should be included in the
control's view.
• DSPROPS_OPTIONALPROPS—Indicates that
non-required properties should be included in
the control's view.
• DSPROPS_GROUP_BY_REQD—Indicates
that required properties should be grouped into
a Required folder, and non-required properties
should be grouped into an Optional folder.
• DSPROPS_STANDARDPROPS—Indicates
that standard properties should be included in
the control's view.
• DSPROPS_CUSTOMPROPS—Indicates that
custom properties should be included in the
control's view.
• DSPROPS_PROVIDE_DEFAULTS—Indicates
that if a user chooses to edit a property value
that is empty-valued, the editor is initialized with
the property's default value as specified in the
server schemata.

ReadOnly (BOOL) If the ReadOnly property is FALSE, the control will

disable the editing of DocuShare properties.

Server (IDispatch*) The Server property identifies the server on which

the DocuShare objects reside.

6.2.3 IDsPropsCtrlEvents Event

PropertyModified()—The PropertyModified event is raised when a user modifies any property value. SDK
programmers typically use this indication to enable an Apply button.

6–6 DocuShare Windows Client SDK

Properties and Permission Controls PermObj

6.3 PermObj
PermObj is a visual ActiveX control that provides a user interface for viewing and editing the permissions
of a DocuShare object. The permissions specify who has Reader, Writer, and Manager access to an
object. Permissions also specify whether an object is hidden from a user if it matches a search. The control
also provides unification functionality so that objects in a container can be given a unified access control
list.

Salient features of this control:

• The ability to view a merged Access Control List consisting of the Access Control Lists of multiple
DocuShare objects. This allows a user to easily recognize permissions that are common amongst
multiple objects.
• The ability to apply specific modifications to multiple DocuShare objects. For example, providing
access to a specific individual to multiple DocuShare objects, even though each object may have a
different Access Control List.
• The final permissions of each object are displayed to the user for review when the edited
permissions are applied to multiple objects. The user can approve or cancel each change.
• The PermObj control allows the user to manage the DocuShare namespace. Users typically have a
need to do this while editing Access Control Lists. The control offers the ability to create users and
groups, examine user and group properties, and examine and modify group memberships.

6.3.1 IPermCtrl Methods

Method Description

AddItemObject(LPDISPATCH pItemObj) Call the AddItemObject method to enter a

DocuShare object. The combined permissions of
all entered DocuShare objects are shown in the
control's view.

Apply() The Apply method applies the permission edits to

all of the entered DocuShare objects.

6.3.2 IPermCtrl Properties

Property Description

BackColor (OLE_COLOR) Indicates the control's background color.

ReadOnly (BOOL) If the ReadOnly property is FALSE, the control

disables the editing of DocuShare permissions.

Server (IDispatch*) The Server property identifies the server on which

the DocuShare objects reside.

6.3.3 _IPermCtrlEvents Events

PropertyModified()—The PropertyModified event is raised when a user modifies a permission. SDK
programmers typically use this indication to enable an Apply button.

DocuShare Windows Client SDK 6–7

PermObj Properties and Permission Controls

6–8 DocuShare Windows Client SDK

 DSAxess Console
The DSAxess console allows the end-user to login and interact with a DocuShare server either
interactively or by creating scripts. This chapter contains the following:

• Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–2
• Script Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–4
• DSAxess console enhancements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–5
• Script Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–8
• Console commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–14

DocuShare Windows Client SDK 7–1

Overview DSAxess Console

7.1 Overview
DSAxess Scripts allow the developer or administrator a simple means of creating routine tasks and chores
within the DocuShare server environment. DSAxess Scripts can be invoked via command line or by
opening the script from the DSAxess menu.

The DSAxess Console application is located at: Start|Programs|DSClientSDK|DSAxess.

7.1.1 Console variables and program flow control

The console interface provides limited support for temporary variable storage and conditional execution of
a command.

The script interpreter maintains the following console variables:

• %DSType%—integer transaction type generated by a DocuShare command

• %DSHandle%—integer transaction handle generated by a DocuShare command
• %DSStatus%—integer status code from a DocuShare command
• %DSError%—integer error code generated by a DocuShare command
• %DSCommand%—name of the DocuShare console command that last updated the above console
variables
The values of the console variables are updated whenever a DocuShare command, such as Put, is
executed.

These variables can be used to pass a result from one command to another command. For example, after
uploading a file to DocuShare, you can obtain file statistics from DocuShare by using this script:

Put "c:\temp\test.txt"
GetProps File-%DSHandle%
The following commands update the console variable:

Copy GetProps Mkdir Replicate

Createuser History Move Search

Delete Lineage Newversion SetProps

Disown Lock Put Tree

Get Login Rename Unlock

Depending on the command, the exact meaning of %DSHandle% may differ. Refer to the description of
each command on how %DSHandle% should be interpreted.

The interpreter also support script variables. For using a script variable, refer to Let on page 7–41.

The console variables and script variables are case sensitive. Also the console variables are automatically
updated and overwritten after the next DocuShare command is executed. To keep the result of a particular
command, use the command Let to save the results, such as %DSHandle%, in a script variable.

7–2 DocuShare Windows Client SDK

DSAxess Console Overview

The DSAxess console also supports using a Windows system environment variable. You can use a system
variable to pass an external argument to a running script. For example, if you want to upload a file in the
system-defined temporary folder, you can use a pathname argument such as:

Put "%temp%\test.txt"
A system variable is not case sensitive, therefore, %temp% and %TEMP% refer to the same variable. The
DOS Set command can be utilized to define a custom environment variable. Refer to Microsoft Windows
documentation.

Flow control may be achieved using If..Then and Goto statements combined with console variables. For
example, to upload a file and verify the results, obtain the uploaded file statistics by using one of the
following sample scripts.

Sample script 1:

Statuscheck Off
Put "%temp%\test.txt"
If %DSStatus% = 0 Then
GetProps %DSHandle%
Sample script 2:

Statuscheck Off
Put "%temp%\test.txt"
If %DSStatus% <> 0 Then
Goto end
GetProps %DSHandle%
...
:End
Exit

NOTE: The Statuscheck command is executed prior to the Put command to turn off the status check.
If enabled, the status check option can stop the script without executing the If..Then statement
if the Put command encounters an error.

To implement an iterative structure, create a loop counter variable and increment the counter value using
Let statements, and use a forward jump with the Goto statement. For example, to upload three files,
file1.txt, file2.txt, and file3.txt, use this script.

Let UploadCount=1
:StartUpload
Put "c:\temp\file%UploadCount%.txt"
Let Uploadcount=UploadCount+1
If UploadCount <= 3 Then
Goto StartUpload
Echo All done
For examples and information on utilizing DSAxess Scripts, refer to Script Basics on page 7–4.

DocuShare Windows Client SDK 7–3

Script Basics DSAxess Console

7.2 Script Basics

A DSAxess Script is an ASCII text file that can be composed in any ASCII Editor, such as Microsoft
Notepad. The file does not need to have any specific file extension. All commands in the script are
delimited by a return character; every command in the script must be on its own line.

Scripts can be invoked either through the command line or by opening the script in the File|Open menu
selection within DSAxess. If you wish to launch scripts from the desktop, you can create shortcuts to the
DSAxess executable. You can modify the shortcuts by adding the path and filename to the script you wish
to have DSAxess execute.

Some script basics are:

• Adding comments—inserting a pound (#) sign at the beginning of the line comments out a line in a
DSAxess script.
• Clearing the output window—the CLS command clears the output window of text.
• Echoing a command—the Echo command can be toggled on or off to echo script commands as
DSAxess parses them in the command window.
• Writing a script to file—the Writelog command writes the script to a file.
• Closing a script automatically—the Exit command closes a script automatically.

NOTE: See Script Examples on page 7–8.

7–4 DocuShare Windows Client SDK

DSAxess Console DSAxess console enhancements

7.3 DSAxess console enhancements

7.3.1 Custom property support
Custom properties may be specified for the commands Put, Mkdir, SetProps, and GetProps. The syntax for
each command is:

Put [path name of file] <[name1=value1] [name2=value2] ...>

Mkdir [name of collection] <[name1=value1] [name2=value2] ...>
SetProps [object handle] <[name1=value1] [name2=value2] ...>
GetProps [object handle] <[name1] [name2] ...>
Make sure that double quotation marks enclose the name and value pair if the value contains white space.
To set the custom property value for a file named Author_Signature to This is just a test, the following
SETPROPS command can be used.

SetProps File-123 "Author_Signature=This is just a test"

NOTE: The name-value pair is in double quotes.

7.3.1.1 Replicate command

The Replicate command also supports custom properties. If a source object has one or more custom
properties defined, the command copies them onto the target object. If the target server does not define
some or all of the source object's custom properties, the target object does not inherit those properties.
The standard properties except ownership are always inherited. The owner of the target object is the user
who performs the Replicate command regardless of the ownership of the source object.

7.3.1.2 GetProps command

Where a schema lookup is possible, GetProps does not need explicit custom property specifications to
retrieve the property's value. GetProps can obtain the available custom properties from a schema cache
that the SDK library maintains in the client machine. Refer to section Custom property support on page 7–
5 and commands Mapserver on page 7–46 and Updateschema on page 7–67 for more information.

7.3.1.3 Login context switching

The new DSAxess can store login contexts, which allows a user to switch between multiple servers. This is
useful when using a command like Replicate, which requires user credentials for another server. For a
user login that uses the command Login, DSAxess caches the credentials from the new server. DSAxess
can store credentials for up to eight servers. Issuing the command Logout removes the credentials for the
server from the cache. To switch from one server to another, a user issues the Switchto command. The
credentials for the selected server are copied from the cache. A subsequent gateway command uses
these credentials.

The syntax for Switchto is: Switchto [server name] <user name>

For example, after logging into docushare-nt6, a user wants to switch from docushare.usa to qatest-nt6,
issues the command:

Switchto qatest-nt6

DocuShare Windows Client SDK 7–5

DSAxess console enhancements DSAxess Console

The entry switches the user to the earlier login context without going through a formal login dialog.

The server name supplied to Switchto can be the server's fully qualified URL, or the first part of the host
name that appears in the server's home URL. For instance, if the URL supplied in the login dialog was
http://docushare.usa.xerox.com/, the name for Switchto can be docushare or docushare.usa. DSAxess
finds the first server entry in the cache that completely or partially matches the supplied name.

To use the context switch in Replicate, follow these steps:

1. Log into a target server (such as docushare.domain.com) where the source object will be copied.
2. Log into the source server (such as docushare-nt6.domain.com) where the source object exists.
3. Issue Replicate from the source server context using this syntax:
Replicate File-123 Collection-10 docushare-nt6
The Replicate command replicates File-123 (file contents and all standard and custom properties) into
Collection-10 in server docushare-nt6.

Previous versions of DSAxess required a user to explicitly specify the URL, authentication token, and
proxy address within the Replicate command line. With the server context information stored, DSAxess
now can pull these parameters from cache, based on a shorter server name.

Before Replicate can successfully copy custom properties, a user must map the server using the
Mapserver command or Windows Explorer if the Windows Client is installed. The user must then run
DSAxess and log into the server by specifying the same fully qualified URL that was used to create the
server map. Also, the Updateschema command must be executed so that Replicate has access to the
latest schema from the server.

7.3.2 Custom Object Support

Version 3.1 of DSAxess fully supports custom objects. Use Put with the type parameter set to the custom
object type when uploading a file as a custom document object. Specify a custom object handle in a Get
command in order to download a custom document object.

Put c:\doc\myproposal.doc "type=myDocument" "summary=My proposal"

Get myDocument-123 c:\doc
You must map the DocuShare server with the Mapserver command for the custom object support to work
properly. Mapserver is not necessary if you have the Windows Client installed, and the server was mapped
in Windows Explorer.

After a command is executed, the DSType and DSHandle parameters, respectively, contain the object type
number and object handle number of the object which the command operates. A type number assigned to
a custom object type is specific to the client machine and when the server map was created. A type
number valid for one client machine may not be valid on a different client machine.

7–6 DocuShare Windows Client SDK

DSAxess Console DSAxess console enhancements

7.3.3 Object specification by title

A target object, that a DSAxess command operates, is specified with an explicit DocuShare object handle.
For example, to download a file whose handle is File-123, the following command line can be executed:

Get File-123 c:\temp

The new version of DSAxess allows a target object to be specified by the object's title, provided that the
object belongs to the current collection. If you know the exact title of a file, you can use the file title instead
of the file handle to issue a Get command. For example, if the title of File-123 is Business proposal, the
following command can be used to download the file:

Get "Business proposal" c:\temp

The following commands accept a title specification:

• CD
• Copy
• Delete
• Edit
• Get
• GetProps
• History
• Lock
• Move
• Open
• Rename
• Replicate
• SetProps

DocuShare Windows Client SDK 7–7

Script Examples DSAxess Console

7.4 Script Examples

These examples can be copied and pasted onto an ASCII text editor to be implemented. These examples
are grouped by the most common tasks.

• Login on page 7–8

• Navigation and Properties on page 7–9
• Uploading Documents on page 7–11
• Downloading Documents on page 7–13

7.4.1 Login
The following examples demonstrate the methods and properties that can be utilized to set or select a
server for login.

Example 1: Simple login

# Example1 - A Simple Login

# The script will echo commands
echo on
# A login dialog is invoked to enter server, user name, and password
login
# List the root directory
dir
Example 2: Setting a server and proxy login

# Example2 - Setting a Server and Proxy for Login

# The script will echo commands
echo on
# Server and proxy parameters are set prior to invoking login
setparam server http://docushareURL.com:80/
setparam proxy http://proxyURL.com:8000/
setparam Domain Docushare
# Note: You may comment out the proxy parameter set if you
# do not require a proxy server.
login
# The login dialog should only prompt you for user name and password
dir
# Logout of server
logout
Example 3: Auto login

# Example3 - Auto Login

echo on

7–8 DocuShare Windows Client SDK

DSAxess Console Script Examples

# We set server and proxy setting here

setparam server http://docushareURL.com:80/
setparam proxy http://proxyURL.com:8000/
setparam Domain Docushare
# We perform autologin
login username password
# Note replace username and password with actual username and password
# Pretend we do some actual work
dir
# Work done, we logout, write log, and exit
logout
writelog "c:\logdir\output.txt"
exit

7.4.2 Navigation and Properties

The following examples demonstrate the methods and properties that can be utilized to navigate to a
server, collection, or document. There are also examples for properties that can be accessed for individual
server items.

Example 1: Simple Navigation

# Example1 - Simple Navigation

# The script will not echo commands
echo off
login
# Clear the screen
cls
# Move to a collection and list the directory
cd 10
dir
# List the a children tree for the collection
tree
# List the parent tree for a collection
lineage
Example 2: Working with Server Parameters

# Example2 - Working with Server Properties

echo on
login
# Clear the screen before getting server gateway parameters
cls

DocuShare Windows Client SDK 7–9

Script Examples DSAxess Console

# List out the parameters

getparam server
getparam version
getparam capability
getparam proxy
getparam userid
getparam username
getparam auth
getparam txpacket
getparam txtimeout
getparam ipaddr
getparam hostname
getparam port
getparam handle
getparam status
getparam error
getparam xml
getparam serverreadonly
getparam downloadclashprompt
getparam uploadclashprompt
getparam uploadasnewdoc
getparam cacheexpireminutes
# We write the logoutput
writelog "c:\temp\output.txt"
Example 3: Working with Item Properties

# Example3 - Working with Item Properties

echo on
login
# Clear the screen before getting collection and file properites
cls
# List out collection properties
getprops collection-10
# List out file properties
getprops file-20
writelog "c:\temp\output.txt"

7–10 DocuShare Windows Client SDK

DSAxess Console Script Examples

7.4.3 Uploading Documents

The following examples demostrate the methods and properties that can be utilized to upload and update
documents to a DocuShare server.

Example 1: Simple Upload

# Example1 - Simple Upload

echo on
login
cd 10
# We create a sample file
getprops collection-10
writelog c:\temp\output1.txt
# Now we upload sample file to current collection
put c:\temp\output1.txt
# We can also set properites on the command line
writelog c:\temp\output2.txt
put c:\temp\output2.txt "summary=Output text two"
Example 2: Simple Update

# Example2 - Simple Update

echo on
login
cd 10
dir
# Create a new output file. Assumes a previous version already stored
# in Docushare Server
writelog c:\temp\output1.txt
newversion "c:\temp\output1.txt" File-22 "summary=Updated Output"
getprops File-22
Example 3: Batch Uploading

# Example3 - Batch Uploading

echo on
login
cd 10
# Delete current *.txt files in current collection
prompt off
delete name=*.txt
# Upload a batch of txt
Example 4: Name Clash Handling

DocuShare Windows Client SDK 7–11

Script Examples DSAxess Console

# Example4 - Name Clash Handling

# Upload a new files
cd 10
put c:\temp\*.txt
# Upload file again, with clash prompt enabled
setparam uploadclashprompt 1
put c:\temp\*.txt
# Prompt should appear to inform user of name clash
# Upload file again, with clash prompt disabled
setparam uploadclashprompt 0
put c:\temp\*.txt
# No prompt informing user of clash should appear
Example 5 : New Document Flag
# Example5 - New Document Flag
# Upload a new file
cd 10
put c:\temp\testfile.txt
# Upload file again, with new doc paramater disabled
setparam uploadasnewdoc 0
put c:\temp\testfile.txt
dir
# There should be only one testfile.txt in the collection
# Upload file again, with new doc parameter enabled
setparam uploadasnewdoc 1
put c:\temp\testfile.txt
dir
# There should be two testfile.txt in the collection
Example 6: Disable Refetch

# Example6 - Disable Refetch

# By default cacheexpireminutes=5
# Extend cache experation time to allow
# for faster uploading of documents.
setparam cacheexpireminutes 60
prompt off
put c:\temp\*.*
# Reset cache experation time
setparam cacheexpireminutes 5

7–12 DocuShare Windows Client SDK

DSAxess Console Script Examples

7.4.4 Downloading Documents

The following examples demostrate the methods and properties that can be utilized to download
documents to a DocuShare server.

Example 1: Simple File Download

# Example1 - Simple File Download

echo on
login
cd 10
# Download the file
get file-22 c:\temp\tempfile.txt
# Download the file and lock it
get file-23 -lock c:\temp\templock.txt
Example 2: Collection Download

# Example2 - Collection Download

echo on
login
cd 10
# Download the collection's files and subcollections
get collection-10 c:\temp\Dir10
Example 3: Version Download

# Example3 - Version Download

echo on
login
cd 10
# Get a listing of the file version history
history file-22
# Download a particular version of a file
get file-22/2 c:\temp\ver2.txt

DocuShare Windows Client SDK 7–13

Console commands DSAxess Console

7.5 Console commands

CD Get Login ResumeOnError

Clearcache GetHandle Logout Search

CLS GetParam Lopen Setparam

Copy GetProps Mapserver SetProps

Createuser GetSchema Mkdir StatusCheck

Delete Goto Move Switchto

DeleteUser Help Newversion Tree

Dir History Open Unlock

Disown If Then Progress Unmapserver

Echo LCD Prompt Updateschema

Edit Let Put WebLogin

Errordlg Lineage RemoveProps Writelog

Eventlog ListRenditions Rename

Exit Lock Replicate

Command notations
FilePath—specifies the pathname of a file in the local machine.

DirPath—specifies the pathname of a directory in the local machine.

CollHandle—specifies a collection handle. Valid specifications are Collection-123 and c123.

FileHandle—specifies a file handle. Valid specifications are File-123 and f123.

VersionHandle—specifies a file handle with a version specifier. Valid specifications are File-123/4 and
f123/4 which specifies Version 4 of File-123.

NOTE: A parameter enclosed in < > is required. A parameter in [ ] is optional.

7–14 DocuShare Windows Client SDK

DSAxess Console Console commands

CD
CD [CollHandle]

Changes the current directory (collection) to the collection specified by CollHandle in DocuShare.

Valid parameters formats are:

• cd collection-10
• cd c10
• cd 10

Clearcache
DSAxess console contains a buffer of collections that has been traversed. To force DSAxess to update the
cache, perform a Clearcache command.

The cache has a default setting of 5 minutes. To get the current cache expiration time, invoke the
command:

getparam cacheexpireminutes
To change the cache expiration time in 1 minute increments invoke the command:

setparam cacheexpireminutes <integer minute>

NOTE: Enter an interger value for <integer minute>.

DocuShare Windows Client SDK 7–15

Console commands DSAxess Console

CLS
The CLS command clears the DSAxess console screen.

Copy
Copy <ObjectHandle> <CollHandle>

The Copy command copies a DocuShare object (ObjectHandle) to a specified collection (CollHandle).

Copy supports the following DocuShare object types:

BulletinBoard Collection SavedQuery

Calendar File URL

Copy sets DSHandle to the handle number of the destination collection.

Valid command samples are:

• copy file-13 collection-10

• copy f13 c10
• copy collection-15 c10
Copy adds a parent, but does not replicate the contents. If a file or collection deletion occurs to any
directory to which the file or collection was copied, the deletion occurs for all collections containing the
deleted source.

If you wish to replicate the contents of a file or collection to another collection, refer to the command
Replicate on page 7–55.

If you wish to move a file or a collection and remove any references to the file or collection from the souce
collection, use the command Move on page 7–47.

If you wish to remove a file or collection from a collection without deleting it from all parent collections, refer
to the command Disown on page 7–23.

7–16 DocuShare Windows Client SDK

DSAxess Console Console commands

Createuser
Createuser <UserName> <Password> ["first_name=First name of user"] ["last_name=Last name of
user"] ["email=Email address of user"] ["mailstop=Mail stop of user"] ["phone=Phone number of
user"] ["homepage=Home page URL of user"] ["use_upload_helper=Usage option"]

The Createuser command creates a user account. The created user account assumes the display name
for UserName. The parameters UserName, Password, first_name and last_name are required. Set the
address for the server where the account is created by using Setparam with the parameter identifier server.

Upon successful conclusion, the command sets DSHandle to the handle number for the created user
account.

Here is an example script that creates a user account in a DocuShare server.

Setparam server "http://docushare.xyz.com/"

Createuser joecool 12345 first_name=Joe lastname=Cool
email=jcool@mail.xyz.com
GetProps User-%DSHandle%
Here is another example that uses Createuser. It automates the tasks for:

• creating a user account in DocuShare

• creating a user specific sub-collection in a top-level collection
• uploading an orientation document
@Echo OFF
Let UserFirstName="Joe"
Let UserLastName="Cool"
Let UserName="%UserFirstName%_%UserLastName%"
Let UserPassword="%UserName%"
Let WelcomeFile="c:\temp\welcome.htm"
CLS
GetParam pctime
Echo Start %DSParam%
Login
Echo Creating account %UserName%
Createuser %UserName% %UserPassword% first_name=%UserFirstName%
last_name=%UserLastName%
Echo User handle: User-%DSHandle%
CD Collection-10
Echo Creating user's collection: %UserName%
Mkdir %UserName%
Echo Collection handle: Collection-%DSHandle%
CD Collection-%DSHandle%
Echo Copying welcome.txt to user's collection

DocuShare Windows Client SDK 7–17

Console commands DSAxess Console

Put %WelcomeFile% title="Welcome %UserFirstName%. Read me first!"

Echo File handle: File-%DSHandle%
GetParam pctime
Echo Stop %DSParam%
Writelog c:\temp\%UserName%.txt
All other user variables are derived from the UserFirstName and UserLastName variables. Observe that
the example uses:

• GetParam with the pctime parameter to set DSParam to the current time
• Echo statements to record essential results
• Writelog to save the results in a log file on the client machine

7–18 DocuShare Windows Client SDK

DSAxess Console Console commands

Delete
Delete <ObjectHandle/name=FileName/name=FileMask>

The Delete command deletes a DocuShare ObjHandle object.

Delete supports the following DocuShare object types:

BulletinBoard Collection SavedQuery

Calendar File URL

Delete sets DSHandle to the handle number for the deleted object.

To delete a collection by the collection handle number, add the Collection prefix; for example, on a
directory search that returns:

COLL10: Directory 1
COLL20: Directory 2
To delete Directory 1, enter:

Delete Collection-10 or Delete c10

To delete a file by the file handle, add the File prefix; for example, on a directory search that returns:

FILE1: Document1
FILE2: Document2
To delete Document1, enter:

Delete File-1 or Delete f1

You can specify a complete filename followed with a name=specifier to cause a deletion by name.You can
also specify a file mask using a wildcard, such as name=*.txt, to delete from the current collection all files
which are found by the mask.

For mask deletions, you are prompted for confirmation. To disable prompting, execute prompt off
beforehand. Only an asterisk (*) is a valid wildcard; you cannot use the question mark (?). You must use
the format, *.[ext], where [ext] is the file extension for files that you want to delete. By specifying name=*.*,
you are deleting all files (excluding sub-collections) that are in the current collection. Files are deleted by
filename, not by title. The command records the transaction result to the system registry. The registry key
is [DSAxess\Console] and is located in [HKCU\Software\Xerox\DocuShare Client]. The transacted handle
is stored as Handle. The output handle is the handle for the last deleted item.

If you delete a file or collection, it will be deleted from all collections that may be parents to the file or
collection you wish to delete. To remove a file or collection from a single parent collection, not all parent
collections, refer to the command Disown on page 7–23.

Enhancement to Delete
Previously, Delete was only invoked by typing the complete Delete keyword. This behavior was modified to
allow use of the cryptic DEL keyword as well. Also, two switches were added: -quiet and -mine.

To delete all items that belong to you, enter:

del *.* -mine

DocuShare Windows Client SDK 7–19

Console commands DSAxess Console

To delete them without being prompted, enter:

del *.* -mine -quiet

NOTE: -m and -q may be used as well.

Valid wild cards are:

• *.*—deletes all
• *.xxx—deletes files with extension name xxx
• xxx*—deletes objects of all types with names starting with xxx
The conventional methods of specifying a target object are preserved. So, these examples are still valid:

• del File-123
• del f123
• del Collection-456
• del c456
• del name=*.htm
• del name=test123.doc

7–20 DocuShare Windows Client SDK

DSAxess Console Console commands

DeleteUser
DeleteUser <User-n>; or DeleteUser <username>

Deletes a user account from a domain.

Example
The following commands logs an administrator into the default DocuShare domain and deletes a user
account, named joecool. The quiet switch (-q or -quiet) may be included to silence a delete confirmation.

DeleteUser [-q] "username=jcool"

or

DeleteUser [-q] "first_name=joe" "last_name=cool"

The quiet switch is used to suppress a confirmation prompt.

LOGON admin
DELETEUSER -q joecool

DocuShare Windows Client SDK 7–21

Console commands DSAxess Console

Dir
Dir <-long> <"SearchText">

The Dir command prints the current directory. If SearchText is specified, items that contain the specified
text is printed. By default, title, filename, size, and lock status are printed. To get more information,
including the summary, use the –long switch.

If SearchText contains a file extension wild card, Dir will output items whose filenames match the specified
file extension.

Dir does not update the DSHandle console variable.

Dir updates the DSItem and DSItemCount script variables. To obtain the handle of an item, use variable
%DSItem-*%, where asterisk (*) is the index number of the item within the obtained directory. The following
example obtains the directory of Collection-10 and downloads all files in the directory to the temporary
folder given by system variable %temp%.

@Echo Off
Login
CD Collection-10
Dir
Echo Found items=%DSItemCount%
Echo Non-collection items follow:
Let ItemNum=1
:StartLoop
IF %ItemNum% > %DSItemCount% THEN
Goto EndLoop
If %DSItem-%ItemNum%% doesnotcontain File Then
Goto BumpIndex
GetProps %DSItem-%ItemNum%%
Get %handle% %temp%\%document%
:BumpIndex
Let ItemNum=ItemNum+1
Goto StartLoop
:EndLoop
The example used a nested variable %DSItem-%ItemNum%% to enumerate the handles of all items. The
example also used variables set by GetProps, %handle% and %document% to supply the file handle, and
filename to the command Get. Refer to GetProps on page 7–34 for more information on the property
variables updated by this command.

7–22 DocuShare Windows Client SDK

DSAxess Console Console commands

Disown
Disown [ObjectHandle]

The Disown command removes a DocuShare object of ObjectHandle from a parent collection.

Disown supports the following DocuShare object types:

BulletinBoard Collection SavedQuery

Calendar File URL

Disown sets DSHandle to the handle number of one of the remaining parents (collections).

To disown a collection by the collection handle number you must add the collection–prefix. For example,
on a directory search that returns:

COLL10: Directory 1
COLL20: Directory 2
To disown Directory 1, enter:

disown collection-10
or

disown c10
To disown a file by the file handle you must add the file– prefix; for example, on a directory search that
returns:

FILE1: Document1
FILE2: Document2
To disown Document1, enter:

Disown file-1
or

Disown f1
If you Disown a file or collection, it only removes it from the collection in which the Disown command was
executed. The document can still be accessed from other collections that are parents of the disowned file
or collection. To delete a file or collection from all parent collections, refer to the command Delete on page
7–19.

DocuShare Windows Client SDK 7–23

Console commands DSAxess Console

Echo
<@>Echo [on/off]

Echoes script commands (on or off) during script execution. Echo without an argument prints the current
Echo setting.

If the supplied argument is not on or off, Echo prints the literal text of the argument.

Echo This is a test

The Echo statement prints This is a test in the console window regardless of the current Echo setting. It is
possible to include one or more variables in the output text. Following execution of a Put statement, you
can print the handle of the uploaded file by issuing this command:

Echo File handle is File-%DSHandle%

If the handle number generated by Put was 123, %DSHandle% is expanded to 123, resulting in an output
of the text, File handle is File-123.

To suppress echoing a script command, start a command with an @ character. The character must occur
at the first column of a statement line. The statement, @Echo ON, executes the Echo command but does
not print the command line in the console window. The @echo suppression can be used with any
statement.

Edit
The Edit command loads a DocuShare file into a native editor application for editing purposes. Edit uses
the document management function of the DocuShare Windows Client. If the Windows Client is not
installed, the command raises an error.

Edit [-lock] <file handle>

The optional -lock switch locks the file. The file is automatically unlocked when it is closed. If the file is
modified, a check-in dialog is posted to save the file back into DocuShare.

7–24 DocuShare Windows Client SDK

DSAxess Console Console commands

Errordlg
Errordlg [on/off]

The Errordlg command controls displaying error dialogs that may occur during the execution of script
commands.

The current state of the Errordlg command can be displayed by entering the command.

Eventlog
Eventlog [on/off]

The Eventlog switch allows the user to display extended event information associated with the execution of
a command.

The current state of the Eventlog command can be displayed by entering the command

Exit
The Exit command causes DSAxess to logout and close the current session.

DocuShare Windows Client SDK 7–25

Console commands DSAxess Console

Get
Get <CollHandle/FileHandle/VersionHandle> [-lock] [FilePath]

The Get command downloads a collection, file, or file version to your PC. A new directory or file is created
using the name, FilePath, to receive the item. If you download a collection, all files and sub-collections are
downloaded. The command records the transaction result to DSHandle. The output handle is the handle of
the downloaded file.

When downloading a collection, Get updates the script variables DSResult and DSResultCount. Variable
DSResultCount contains the number of downloaded items. Variable DSResult–* where * range from one to
DSResultCount, holds the handle of a downloaded item.

The -lock option places a lock on a file that is downloaded. Do not use the -lock option when executing a
Get command on collections or file versions.

[FilePath] must be placed in quotes if the path contains spaces.

See Downloading Documents on page 7–13 for examples on downloading documents.

Version option
The -version option have been added to the Get command. When enabled, the option causes the
command to download or copy all versions of files that the command processes.

To download all file versions, the following syntax is used:

Get -versions [file or collection handle] [destination file system path]

The short form, -v may be used instead of -versions.

If the handle parameter specifies a file, Get retrieves the file's properties, creates a subfolder using the
filename, stores the properties in an XML file in the subfolder, and downloads the file versions into the
subfolder. Because the subfolder's name is automatically obtained from DocuShare, the destination path
parameter should only contain the path that specifies an existing folder (see the section below on the
-name option). Get creates the subfolder in the specified parent folder. A downloaded file version receives
a filename prefixed with a file handle and version number form. For example File-123_10, where the file
handle is File-123 and the version number is 10. The filename that follows the prefix is the filename of the
version file in DocuShare. The file properties are stored in an XML file named after the file handle with a
.xml file extension.

The following example downloads the properties and versions of File-123 to the temp file directory:

Get -v File-123 c:\temp

If File-123 had the name, Business proposal.doc, a subfolder called Business proposal.doc is created in
the C:\temp folder, and the XML properties file and all the version files of File-123 are retrieved and stored
in the new subfolder.

If the handle parameter specifies a collection, Get downloads the file versions only. It does not retrieve the
file properties.

7–26 DocuShare Windows Client SDK

DSAxess Console Console commands

The Get command in DSAxess 3.0 and earlier assumed that a download path specified in a Get command
line ended with a filename or folder name. Get assigned this name to the downloaded file or collection.
DSAxess 3.1 no longer makes this assumption. Instead, it regards a specified download path as the path
to the folder into which the file or collection is downloaded. If you need the previous version's behavior,
issue the following command:

Setparam getname 0
If you wish to revert to the 3.1 behavior, set the getname control parameter to 1. Also, if you want to
temporarily switch to the 3.1 behavior, the new -name option can be used as part of a Get command line.
The option instructs DSAxess to retrieve the file or collection name from DocuShare and appends the
name to the path you supplied.

The -lock option cannot be used with the -versions option. If used, the option causes an invalid argument
error.

Compound option
The -compound option was added for downloading a compound document.

To download a Compound Document:

Get -compound <file> <destination>

Where <file> is the DocuShare handle or title of a compound document, and <destination> is the
pathname of a folder into which the components of the compound document should be downloaded. The
downloaded component files are arranged according to the layout scheme described in the PUT section
(refer to Put on page 7–50).

To download all file versions:

Get -versions <file or collection handle> <destination file system path>

The short form -v may be used instead of -versions. The -compound option is ignored if the -versions
option is used. If a document has more than one rendition, the -versions option only downloads the
versions of the preferred rendition.

Enhancements
Example 1: Downloading RDO

Usage: GET -compound <RDO-file-handle> <destination-path>

RDO-file-handle specifies the DocuShare handle of a RDO file. Destination-path is the download directory
path. The content elements of an RDO are downloaded to a subdirectory with an extension of CON. Linked
jobTicket files are downloaded to the same subdirectory.

Example 2: Downloading mail

Use the same Get command to download a MailMessage. The download mail is converted into an Outlook
mail item file with file extension MSG.

This command downloads MailMessage-123 to directory c:\temp. The filename of the downloaded .msg
file is generated based on the subject line of the mail note.

GET MailMessage-123 c:\temp

You must have the Outlook Client installed on your workstation for the MSG conversion to work. If the
Outlook Client is not installed, a MSG file cannot be generated. The MailMessage may be downloaded

DocuShare Windows Client SDK 7–27

Console commands DSAxess Console

only as an XML data file. If the MailMessage has a file attachment, the attachment is downloaded as a
separate file. If the MailMessage contains a NativeMessage object, which itself is a MSG file, then that
MSG file is downloaded.

7–28 DocuShare Windows Client SDK

DSAxess Console Console commands

GetHandle
GetHandle <File-n/[m]>; or GetHandle <title>

The GetHandle command finds a DocuShare object handle (Version-x) from a File version handle
(File-n/m). A Version-x handle can be used to retrieve object properties for a file version or set properties of
a file version.

Example 1: List properties of a file version

GetHandle File-80/1
GetProps %DSObject%
Example 2: Set comment property of a file version

GetHandle File-80/1
SetProps %DSObject% "comment=Very first version"

DocuShare Windows Client SDK 7–29

Console commands DSAxess Console

GetParam
GetParam <name>

The GetParam command retrieves the value of various parameters for a DSAxess console session.

The command updates script variable DSParam with the value of the queried parameter for referencing
within a script. The script below sets DSParam to the server address and prints the address to the console
window.

@Echo OFF
GetParam server
Echo DocuShare URL: %DSParam%
The queried name and found value outputs to the console and also are stored under the DSAxess registry
key for external referencing. The registry key [DSAxess\Console] is located in
[HKCU\Software\Xerox\DocuShare Client]. The name and value are stored as ParamName.

Some of the parameters are writable. For a listing of writable parameters see Setparam on page 7–61.

Access parameters

Parameter Description

server Lists the http connection for the currently logged in

server.

version Returns the DocuShare version of the currently

logged in server.

proxy Displays the proxy server if one is utilized.

User parameters

Parameter Description

userid Returns the user's id number for the logged in

DocuShare server.

username Returns the user's name for the logged in

DocuShare server.

auth Returns the user's authentication token string for

the logged in DocuShare server.

7–30 DocuShare Windows Client SDK

DSAxess Console Console commands

Socket parameters

Parameter Description

txpacket Returns the transmission packet size (measured

in bytes).

txtimeout Returns the transmission timeout (measured in

milliseconds).

ipaddr Returns the IP address for the logged in

DocuShare server.

hostname Returns the hostname for the logged in

DocuShare server.

port Returns the port address of the client that is

communicating with the logged in DocuShare
server.

Transaction parameters

Parameter Description

handle Returns the handle of the last command that

returns a value to the handle. This parameter is
equivalent to the console variable %DSHandle%.
Refer to individual commands that return a handle
value.

handlelist Returns the list of result handles for the items

downloaded or uploaded by a multi-file command.
The first entry in the list is the item count;
subsequent entries are the item handles. The
contents of this parameter are equivalent to script
variables DDSResultCount and DSResult-* that
are automatically updated by the commands Get,
Put, and Replicate when the operated source item
is in regards to a collection.

error Returns the error code for the last error

encountered. This parameter is equivalent to
console variable %DSError%. A zero value is
returned if an error is not encountered in the
current session.

status Returns the status code for the last command.

This parameter is equivalent to console variable
%DSStatus%. A zero value indicates a successful
command execution.

DocuShare Windows Client SDK 7–31

Console commands DSAxess Console

Server information

Server Information Description

xml Returns a value of one, if the current session with

the logged in DocuShare server is XML enabled;
otherwise, a zero is returned.

serverreadonly Returns a value of one, if the current session with

the logged in DocuShare server is a read-only
connection; otherwise, a zero is returned.

capability Read-only integer parameter returns a bit-OR

value containing the following server information:
• Server supports new version comment—bit 0
• Server supports collection upload—bit 1
• Server uses secure HTTP protocol—bit 3
• Server supports XML—bit 4
• Server is in read-only mode—bit 5
• Server uses NTLM challenge/response protocol
for user authentication—bit 6

version Read-only parameter returns the major and minor

version number of a DocuShare server last
contacted.

time Read-only parameter returns the time of the last

server transaction reported by the web server.

localtime Read-only parameter returns the time of the last

server transaction reported by the client machine.

timeoffset Read-only parameter returns the time difference

between time and local time.

pctime Returns the current time reported by the client

machine.

7–32 DocuShare Windows Client SDK

DSAxess Console Console commands

Transfer mode

Transfer Mode Description

downloadclashprompt Returns a value of one, if the Put command

prompts the user when a name clash occurs during
download. A zero value return signifies that a
prompt will not appear if the Put command causes
a name clash.

uploadclashprompt Returns a value of one, if the Get command

prompts the user when a name clash occurs during
uploading of a file or collection. A zero value return
signifies that a prompt will not appear if the Get
command causes a name clash.

uploadasnewdoc Returns a value of zero, if a Get command treats all

uploaded files as new versions in those instances
where a file with the same name already exists in
the target collection. A zero value return signifies
that all uploads are treated as new files.

Directory cache control

cacheexpireminutes—this parameter returns the expiration time in minutes for the current session.

DocuShare Windows Client SDK 7–33

Console commands DSAxess Console

GetProps
GetProps <ObjectHandle>

The GetProps command finds properties for a DocuShare object (ObjectHandle). Only the standard
properties are queried.

GetProps supports the following object types:

BulletinBoard Collection SavedQuery

Calendar File URL

GetProps sets DSHandle to the handle number for the parent (collection) of the queried object.

The following list of properties are associated with a file:

title owner.title parent.title max_versions

summary owner.handle parent.handle locked_by

description create_date document size

keywords modified_date content_type

handle modified_by author

The following list of properties are associated with a collection:

title handle modified_date logo

summary owner.title modified_by bg_image

description owner.handle parent.title sort_order

keywords create_date parent.handle n_items

GetProps saves the values of all queried property script variables. A script variable for a queried property
is constructed by enclosing the property name with % signs. For example, the owner name property can be
obtained by not referencing the variable %owner.title%.

Enhancements
Example 1: Retrieving specified properties

To specify properties to be retrieved, enter the properties after the object handle specification:

GETPROPS <handle> [prop1 prop2 ... propN]

The command retrieves the values of prop1, prop2, ..., propN where prop1, prop2, ..., propN are the
names of valid properties of an object specified by handle.

Example 2: Retrieving all properties

The option instructs the command to retrieve all core, custom and instance properties of a DocuShare
object. The command achieves this by first requesting for <propname> and then issuing a <propfind> for
the retrieved property names.

7–34 DocuShare Windows Client SDK

DSAxess Console Console commands

GETPROPS -all <handle>

Example 3: Retrieving file version properties

The command can be used to retrieve properties of a file version that is specified by a file handle and a
version number.

GETPROPS File-n/m
Where File-n is the file handle and m is the ordinal version number of a file version.

If you know the Version handle of a version object, use the version handle.

GETPROPS Version-n <prop list>

If no property name is given, the command retrieves the following properties:

• MIME type of content data

• owner of object
• creation time
• modification time
• comment text
Example 4: Retrieving link information

GetProps can be used to find out if an object is linked to another. Specify the name of a link specifier
following the object handle. The specifier must conform to the format link:

<link-type>.<linkage-direction>
Where link-type is the name of a link type that is pre-defined in the link schemata of the server, and
linkage-direction is either source or destination.

This command example finds out what object is linked to File-116.

GETPROPS File-116 link.jobTicket.destination

link.jobTicket.destination=abc.xjt (File-119)

DocuShare Windows Client SDK 7–35

Console commands DSAxess Console

GetSchema
GetSchema [option] [class]

The GetSchema command retrieves and prints server schemata. This command can retrieve either class
or link schemata. The command works for DocuShare Release 5 or greater.

The only available option is the -link option. The -link option causes the command to retrieve link
schemata instead of class schemata. A class should not be specified if this option is used.

Example 1: GetSchema output

To display all items in the schemata, enter the command without an argument.

GETSCHEMA
SchemaVersion: 1126592331345
Class-0.Name: File
Class-0.Label: Document
File.Prop-1: abstract
File.abstract.IsRequired: 0
File.Prop-2: add_as_draft
...
File.Prop-30: summary
File.summary.IsRequired: 0
Class-1.Name: SavedQuery
Class-1.Label: SavedQuery
SavedQuery.Prop-1: children
SavedQuery.children.IsRequired: 0
SavedQuery.Prop-2: Class Label
SavedQuery.Class Label.IsRequired: 0
...
Example 2: GetSchema [class] output

To limit the display to the schema data of a particular object class, add the name of the class. To get
schemata for the MailMessage class, enter:

GETSCHEMA MailMessage
SchemaVersion: 1126592331345
Class-0.Name: MailMessage
Class-0.Label: MailMessage
MailMessage.Prop-1: body
MailMessage.body.Label: Message
MailMessage.body.Type: 2
...

7–36 DocuShare Windows Client SDK

DSAxess Console Console commands

Example 3: link option

This is an example to retrieve link schemata; enter:

GETSCHEMA -link

DocuShare Windows Client SDK 7–37

Console commands DSAxess Console

Goto
The Goto command passes control to a subsequent line containing the specified label prefixed with a
colon, ':'.

This example passes control to the line marked by label :NEXTJOB.

Goto NEXTJOB
...
:NEXTJOB
...

Help
Reserved for future use.

History
History <FileHandle>

The History command lists the version of the specified file by FileHandle.

History sets DSHandle to the handle number for the queried file.

7–38 DocuShare Windows Client SDK

DSAxess Console Console commands

If Then
If [condition] Then

The If..Then command executes the statement in the next script line if the specified condition is met. If the
condition is not satisfied, the next line is skipped. A condition is specified by one of the following
comparison statements:

A=B A equals B

A <> B A does not equal B

A<B A is less than B

A>B A is greater than B

A <= B A is less than or equal to B

A => B A is equal to or greater than B

A contains B A contains the string of B

A does not A does not contain the string of B

contain B

NOTE: A, B, or both may contain a variable (console, script or environment variable). No other
comparison formats are supported. Also, the operands and operator must be separated by
white space. For example, specifying A=B generates a syntax error.

A line containing an If..Then statement must not be a compound statement. It must terminate without any
subordinate statement. Therefore, the following statements are valid.

If %DSStatus% <> 0 Then

Goto DOJOB1
The following compound statement is not valid.

If %DSStatus% <> 0 Then Goto DOJOB1

The script interpreter ignores the subordinate Goto statement.

If the condition is satisfied, the If..Then command executes the next occurring command only. Execution
resumes at the following line if the condition is not met. Use an If..Then statement with a Goto statement to
execute a condition dependent, multi-statement block.

DocuShare Windows Client SDK 7–39

Console commands DSAxess Console

An iterative loop may be written by combining statements If..Then, Let, and Goto. The following example
queries Collection-10 through Collection-13 using a loop structure.

Let CollHandle=10
:StartLoop
GetProps Collection-%CollHandle%
If %CollHandle% = 13 Then
Goto EndLoop
Let CollHandle=CollHandle+1
Goto StartLoop
:EndLoop

LCD
LCD <DirPath>

The LCD command changes the current directory to the new directory given by the LocalDirPath in your
system.

7–40 DocuShare Windows Client SDK

DSAxess Console Console commands

Let
Let <Script Variable=Value>

The Let command assigns a number or text value to a script variable. An assigned text value is enclosed
with double quotation marks.

If the right hand side of the assignment describes an arithmetic operation, Let evaluates it and assigns the
numeric result to the variable of the left hand side. Let only supports addition (+), subtraction (-),
multiplication (*), and division (/). Let does not support explictly signed numbers, such as -123, -VariableA,
or +VariableB. Valid example assignments:

Let TextVar1 = "This is a text variable"

Let TextVar2 = "File handle is File-%DSHandle%"
Let NumVar1 = 1
Let NumVar1 = NumVar1 + 1
Let NumVar2 = NumVar1 * 1.5
Let NumVar3 = NumVar1 - NumVar2
Although the interpreter does not raise an error, text and number variables should not be mixed.

A script variable is addressed as %VARIABLE% where VARIABLE is the name of a valid variable. A script
variable can be used in a command argument or as part of a conditional statement in an If...Then
statement. The following statements create script variables and assign a pathname and title to them.

Let FilePath = "c:\my documents\proposal.doc"

Let FileTitle = "Business proposal"
Let FileCollection = "Collection-13"
To upload the above file, this script can be used.

CD %FileCollection%
Put %FilePath% title=%FileTitle%

NOTE: The variable identifier is case sensitive. %FilePath% is valid, while %filepath% is not.

The value assigned to a script variable can contain the following:

• one or more valid script variables

• Windows system environment variables
• DSAxess console variables
Nested variables are not supported. If an invalid variable is referenced in making an assignment, Let raises
a Variable-not-defined error.

DocuShare Windows Client SDK 7–41

Console commands DSAxess Console

The following script variables are pre-defined and automatically updated when certain commands are
executed.

Pre-defined Variables Description

DSHandle Transaction handle number.

DSStatus Command execution Status code.

DSError Command execution Error code.

DSCommand Executed command.

DSParam Parameter value obtained from GetParam.

DSItemCount Item count from Dir, Lineage.

DSItem-* Item handles from Dir, Lineage.

DSSearchHitCount Item count from Search.

DSSearchHit-* Item handles from Search.

DSResultCount Item count from Get, Put, Replicate.

DSResult-* Item handles from Get, Put, Replicate.

NOTE: Asterisk (*) represents a placeholder for a numeric handle number.

While it is generally not possible to use a nested variable, such as %A%B%%, nesting is permitted for the
following pre-defined variables:

• DSItem-*
• DSSearchHit-*
• DSResult-*
The variable, %DSItem-%ItemIndex%% , yields a proper handle provided that %ItemIndex% is a user-
defined integer variable and its value falls within 1 through %DSItemCount%.

7–42 DocuShare Windows Client SDK

DSAxess Console Console commands

Lineage
The Lineage command prints the lineage for the current collection. This allows the user to list the path
back to the root collection.

Lineage sets DSHandle to the handle number for the current collection.

Lineage updates script variables DSItemCount and DSItem-* and are used to iterate the ancestor
collections in a script.

DocuShare Windows Client SDK 7–43

Console commands DSAxess Console

ListRenditions
ListRenditions <Version-x>; or ListRenditions <File-n/[m]>

The command lists renditions that belong to a file version.

If file version number m is not specified, DSAxess uses the latest version of the file.

If no version number is given, the command retrieves the latest version number from DocuShare and
retrieves rendition information for that version.

Example 1

LISTRENDITIONS File-2501
Lastest version number: 13
Retrieving Version handle for File-2501/13...
Renditions of Version-2551
Rendition-2508 foobar.doc
MIME type: application/msword
Owner: Joe Cool (User-123)
Created: 2/27/2006 23:47:48 PM
Modified: 2/27/2006 23:47:48 PM
Rendition-2509 foobar.html
MIME type: text/html
Owner: Joe Cool (User-123)
Created: 2/27/2006 23:49:46 PM
Modified: 2/27/2006 23:49:46 PM
Example 2

This lists the renditions of a specific version.

LISTRENDITIONS File-2501/13
If you already know the Version handle, use that as the handle argument.

LISTRENDITIONS Version-2551
The two commands in Example 2 generate the same list of renditions, as in Example 1, without a version
number argument.

This command works for DocuShare Release 3.1 and higher. However, the command may not work
against DocuShare Release 4.x if a Version handle is passed as the handle parameter. Use either the File
handle or File handle plus version number method. DocuShare 4.x does not recognize object property
<parents> for a Version object, and causes a Version handle-based query to fail. DocuShare Release 5/
CPX Release 5 fixes the problem.

7–44 DocuShare Windows Client SDK

DSAxess Console Console commands

Lock
Lock <FileHandle>

The Lock command locks a file. The command records the transaction result to the system registry. The
registry key [DSAxess\Console] is located in [HKCU\Software\Xerox\DocuShare Client]. The transacted
handle is stored as DSHandle.

Lock sets DSHandle to the locked file.

Login
Login <username> <password>

The Login command logs into a DocuShare session. Username must be specified first. If either credential
parameter is not specified, a dialog runs to let you specify them. The command records the transaction
result to the system registry. The [DSAxess\Console] registry key is located in
[HKCU\Software\Xerox\DocuShare Client]. The transacted handle is stored as DSHandle.

Login sets DSHandle to the handle number for the authenticated user.

See Login on page 7–8 for login examples.

Logout
The Logout command logs out from the current server session and clears the internally cached password.

DocuShare Windows Client SDK 7–45

Console commands DSAxess Console

Lopen
The Lopen command opens a file system object in the client machine.

Lopen <path>
The command can be used to open a file downloaded from DocuShare.

Mapserver
The Mapserver command creates a logical map that associates a server name with a physical DocuShare
server and stores it in the Windows system registry. DSAxess can use a map to locate a DocuShare server
based on a server name entered by a user without requiring the user to enter explicit access information.

The command has the following command line syntax:

Mapserver [name] [WIP]

<name> is an optional parameter and names the server map just created. If the name parameter is not
supplied, DSAxess uses a beginning part of the hostname that is in the URL as the name of the server
map. <WIP> is the name of a work-in-progress folder that the SDK library and SDK application uses to
store work files. <WIP> is an optional parameter and must be preceded by the <name> parameter. If
<WIP> is not given, DSAxess uses the value of <name> as the WIP folder name. DSAxess itself does not
use the WIP folder.

Mapserver defines the -list option. This option lists all currently mapped DocuShare servers. Use this
option without any argument as shown below.

Mapserver -list
The access information stored by this command is shared by the DocuShare Windows Client and
DocuShare Outlook Client. The name of a created map appears in Windows Explorer or Outlook Client as
a server folder. Use the Refresh command if the name of a new server does not appear.

7–46 DocuShare Windows Client SDK

DSAxess Console Console commands

Mkdir
Mkdir <"TitleText"> ["summary=CommentText"]

The Mkdir command makes a new directory (collection). The name of the new directory is TitleText. You
can specify summary text as CommentText. The command records the transaction result to the system
registry. The [DSAxess\Console] registry key is located in [HKCU\Software\Xerox\DocuShare Client]. The
transacted handle is stored as DSHandle. The output handle is the handle for the created collection.

Mkdir sets script variable DSHandle to the handle number for the created collection.

Move
Move <ObjectHandle> <CollHandle>

The Move command moves a DocuShare object (ObjectHandle) to another collection (CollHandle). If the
item to be moved is not located in the current collection, the Move command fails with an error code 400
(bad source). The command records the transaction result to the system registry. The [DSAxess\Console]
registry key is located in [HKCU\Software\Xerox\DocuShare Client]. The transacted handle is stored as
DSHandle.

Move supports the following DocuShare object types:

BulletinBoard Collection SavedQuery

Calendar File URL

Move sets script variable DSHandle to the handle number of the destination collection.

DocuShare Windows Client SDK 7–47

Console commands DSAxess Console

Newversion
Newversion <FilePath> <FileHandle> ["summary=CommentText"]

The Newversion command uploads a local file given by FilePath as a new version of the DocuShare file
specified by FileHandle. You can add version comments by giving a summary option. The command
records the transaction result to the system registry. The [DSAxess\Console] registry key is located in
[HKCU\Software\Xerox\DocuShare Client]. The transacted handle is stored as DSHandle.

Newversion sets script variable DSHandle to the file handle of the updated file.

Compound option
The -compound option was added for the task of updating a compound document.

To upload a new version of a compound document, use the -compound option.

Newversion -compound [compound file] [file handle] <"comment=CommentText">

Where [compound file] is the pathname of a folder with one of the compound file layouts described in the
Put command section. Refer to Put on page 7–50.

NOTE: The property identifier summary may be used in place of comment when specifying comment
text.

Enhancements
Example 1: Uploading a version with a rendition and content files

NEWVERSION -attach <rendition> [content1 content2 ...] <file-handle>

[comment]
A new version is created for the file of handle file-handle. Rendition specifies the path of a file that
becomes the only rendition of the new version. Content1, content2 and so on, are the paths of additional
files that are added to the version as content elements.

Example 2: Uploading a new version of RDO

NEWVERSION -compound <RDO-file> <file-handle> [comment]

RDO-file specifies the path of an RDO file. Associated files of the RDO exist in a CON subdirectory of the
same name in the same directory. The RDO file is stored as the new version's rendition. The associated
files, excluding job ticket files, are stored as content elements of the version. The job ticket file(s) are
stored as separate files linked to the RDO file object.

7–48 DocuShare Windows Client SDK

DSAxess Console Console commands

Open
The Open command opens a DocuShare object in an Internet Explorer window.

Open <object handle>

If <object handle> is not specified, the Open command opens the current collection.

Progress
Progress [on/off]

The Progress command displays (toggle on or off) a progress box on net access.

Prompt
Prompt [on/off]

The Prompt command prompts (toggle on or off) for confirmation upon deleting or uploading multiple files.

DocuShare Windows Client SDK 7–49

Console commands DSAxess Console

Put
Put <FilePath> ["prop1=value1" ...]

The Put command uploads to the current DocuShare directory (collection) one or more local files specified
by the file mask LocalFilePath. A wildcard, such as c:\temp\*.txt, can be used to Put more than one file.
Wildcard characters are "*" and "?".

By specifying a local directory, you can copy the directory and its contents in one step. Optional
parameters for setting properties are applicable to a non-wildcard specification. You can use any of these
combinations:

title=(display name) summary= keywords object_type=(MIME type)

name=(filename) description= author=

The Put command records the transaction result to the system registry. The [DSAxess\Console] registry
key is located in [HKCU\Software\Xerox\DocuShare Client]. The transacted handle is stored as DSHandle.
The output handle is the handle of the last uploaded file.

The Put command can be modified with the Uploadasnewdoc and Uploadclashprompt settings. Modifying
these settings only affect the uploading of wild card or directories.

Put sets script variable DSHandle to the file handle for the created file. Put also updates script variables
DSResultCount and DSResult–* if Put uploads a directory.

Command line switches

Two optional command line switches are added to the Put command to support silencing a confirmation
prompt and uploading a compound document.

Disabling Confirmation Prompt

When uploading multiple files, such as files that match a file name pattern, the -quiet option can be used to
disable the confirmation prompt.

Put [-quiet] [file name pattern]

To upload all files that appear in folder "c:\doc" without prompting, the following command can be used:

Put -quiet c:\doc\*.doc

Uploading a compound document

To upload a compound document, use the new -option command:

Put [-compound] [compound folder] <"summary=CommentText" ...>

Where compound folder is the pathname of a folder. The folder contains a rendition file and other optional
constituent files of a compound document. The files must be arranged according to the compound file
layout.

Folder abc123

+--- Primary rendition file "abc123.htm"

+--- Content elements folder "html"
| +--- File of content element 1 "abc123_pic1.gif"

7–50 DocuShare Windows Client SDK

DSAxess Console Console commands

| +--- File of content element 2 "abc123_pic2.jpg"

| +--- File of content element 3 "abc123_pic3.jpg"
| +--- File of content element 4 "abc123_pamph.js"
| +--- File of content element 5 "abc123_greetings.htm"
| +--- File of content element 6 "abc123_greetings_logo.jpg"
| +--- File of content element 7 "abc123_greetings_welcome.jpg"
+--- Alternate renditions folder "_AltRenditions"
| +--- Alternate rendition file "abc123.msg"
+--- Properties metadata folder "_Properties"
+--- Data file "abc123.xml"
The above layout uploads a compound document named abc123 with the HTML content of abc123.htm as
the preferred rendition. The example compound layout contains two renditions:

• an HTML preferred rendition named as abc123.htm

• a native rendition of MS Outlook mail message named as abc123.msg
The preferred rendition contains seven content elements which are placed in a subdirectory called after the
rendition's content type. In this case, since the preferred rendition contains HTML content data, it is html
with the general class identifier, text, that is dropped.

In the above example, the preferred rendition abc123.htm contains a nested content element—an HTML
FRAME element which links it to the fifth content element, abc123_greetings.htm. This content element is
itself an HTML file. It contains links to two JPEG image files—abc123_greetings_logo.jpg and
abc123_greetings_welcome.jpg. The linked image files are stored in the same directory as the HTML
content element that refers to them.

The SRC attributes of the IMG elements in the HTML content element are set to relative URLs
abc123_greetings_logo.jpg and abc123_greetings_welcome.jpg. Notice that the URLs are relative to the
HTML content element. Since the images are stored in the same directory as the referring content
element, the URLs are simply the filenames without any directory specification. Contrast this to the SRC
URLs that the preferred rendition abc123.htm contains. These URLs are relative to the html rendition
directory, and therefore, are of form html/[filename] where [filename] is the name of a content element file
referenced by the HTML rendition.

The -compound option can be used to upload an HTML file and subfiles linked to it (called connected files)
that are saved using the File Save As menu command within Internet Explorer (Version 5 or higher).

To upload an IE file and its connected files as a compound document:

Put [-compound] [compound file]

DocuShare Windows Client SDK 7–51

Console commands DSAxess Console

[compound file] is the pathname of an HTML file. If the file contains an HTML SRC reference to an
external file, the referenced file must appear in a subfolder named as [file title]_files, where [file title] is the
title portion of the HTML filename. For example, to upload an HTML file whose pathname is c:\web\xyz.htm
and contains SRC links to JPEG image files, the image files need to be stored in a subfolder at the path,
c:\web\xyz_files.

As part of the pre-process to the upload operation, the PUT command scans the HTML file for IMG and
other SRC references to files stored in the subdirectory (xyz_files, in the above example). The SRC
references, relative to the HTML file, are replaced with content element URLs of form html/[file name].

Note that a BASE HREF directive is ignored by the pre-process and should not be used in the HTML
rendition file. If this default pre-process is not suitable to your needs, you can override it with a callback
library you supply. The callback needs to conform to the IDsContentPreprocess interface definition. See
Compound document support on page 5–176 for details.

1. To override the HTML content preprocess, enter the following before issuing a PUT command:
Setparam RenditionPreprocessor [ProgID of custom preprocessor]
2. To restore the default preprocess, enter:
Setparam RenditionPreprocessor DEFAULT
3. To skip the preprocess entirely, enter:
Setparam RenditionPreprocessor NONE

Name Clash detection

The DSAxess parameter, uploadclashprompt, is used to control the detection of a pre-existing Document
object that has the same title as the file that is being uploaded. If an object with the same title is found,
DSAxess prompts for a confirmation to replace the object. In versions 3.0 and 2.x of DSAxess, the
detection was limited to bulk upload operations, such as uploading by a wild card and uploading of a
directory. Version 3.1 of DSAxess can use the uploadclashprompt detection in a single upload operation as
well. To enable it, set the new extend_uploadclashpromp parameter to 1 using the Setparam command.
By default, the parameter is set to 0, and the single upload detection mode is off. A file is always uploaded
as a new Document object.

Enhancements
Example 1: Linking a file to another

This command uploads a file (test.xjt) and links it to another file (file handle File-101) with the jobTicket
link type.

PUT -linktype:jobTicket -parent:File-101 "c:\temp\test.xjt"

12:22:55 Uploading item: test.xjt
Result handle: File-120
The uploaded file (File-120) becomes the destination of the link established between File-101 and
File-120. Note that the link destination file does not appear in the collection where the source file appears.
Deleting the source file does not delete the destination file using the DELETE command in DSAxess.

To verfiy the linkage, this command may be issued.

GETPROPS File-101 link.jobTicket.destination

or

7–52 DocuShare Windows Client SDK

DSAxess Console Console commands

GETPROPS File-120 link.jobTicket.source

Example 2: Uploading RDO Package

Usage: PUT -compound [RDO-file]

RDO-file is the path of an RDO file. The pathname must end with an RDO file extension name such as
RDO or RDT. Also, the file must be accompanied by RDO content and job ticket files in a directory whose
name is the concatenation of the file title part of the RDO filename and the extension CON. If the RDO file
is called foobar.rdo, the directory must be named foobar.con.

To see the uploaded file structure, use the Tree command. Use the GetProps command with a prop name
set to link.jobTicket.destination to verify the job ticket linkage.

PUT -compound test.rdo

Result handle: File-2598
TREE File-2598
- test.rdo (File-2598/1)
+-- test.rdo (Rendition-2841)
+-- test.rdo (ContElem-1)
+-- 00000001.tif (ContElem-2)
...
GETPROPS File-2598 link.jobTicket.destination
The command requires a DocuShare server Relesase 5.0 or greater with jobTicket support enabled. If not
enabled, the command appears to be successfully completed, but the job ticket links for the RDO would
not be established.

Example 3: Uploading mail

Usage: PUT -mail [-quiet] <msg-path>

Use the mail switch to save an MS Outlook mail item (a file with the extension, MSG). The mail item is
stored as a MailMessage object on DocuShare (not as a file object). You must have Outlook Client
installed on your workstation for this feature to work.

msg-path is the pathname of a msg file. If msg-path is a filename without a directory specification, the
command locates the file in the current directory.

You can use a wildcard (* or ?) to upload multiple mail items. You are prompted to confirm the uploading of
each item. The confirmation prompt can be turned off using the quiet switch.

This command quitely uploads all mail items with a RE subject line that are in the directory c:\mymail.

lcd c:\mymail
put -mail -quiet RE*.msg

DocuShare Windows Client SDK 7–53

Console commands DSAxess Console

RemoveProps
RemoveProps <Handle> <prop1 prop2 ...>

The RemoveProps command removes one or more instance properties from an object on DocuShare.

NOTE: RemoveProps cannot be used to delete a property defined in the server schemata.

An instance property can be created using the SetProps command.

In the example, an instance property called myFileInstanceProp is created on a File object using the
SetProps command. Then, RemoveProps is used to delete the added property.

SETPROPS File-123 "myFileInstanceProp=test 123"

REMOVEPROPS File-123 myFileInstanceProp

Rename
Rename <ObjectHandle> ["NewTitleText"]

The Rename command renames a DocuShare object (ObjectHandle). The command records the
transaction result to the system registry. The [DSAxess\Console] registry key is located in
[HKCU\Software\Xerox\DocuShare Client]. The transacted handle is stored as DSHandle.

Rename supports the following DocuShare object types:

BulletinBoard Collection SavedQuery

Calendar File URL

Rename sets script variable DSHandle to the handle number for the renamed object.

7–54 DocuShare Windows Client SDK

DSAxess Console Console commands

Replicate
Replicate <CollHandle1/FileHandle> [CollHandle2] [<URL> <Auth> <Proxy>]

The Replicate command replicates a collection or file to another collection (CollHandle2). If CollHandle2 is
not specified, the current collection becomes the destination. If CollHandle2 is in another server, supply the
access information for the second server by specifying the server home URL and user authentication
token (Auth).

NOTE: Optional—access information for a proxy server URL (Proxy).

The Replicate command copies the item contents and standard set of properties. The command records
the transaction result to the system registry. The [DSAxess\Console] registry key is located in
[HKCU\Software\Xerox\DocuShare Client]. The transacted handle is stored as DSHandle.

Replicate sets script variable DSHandle to the handle number for the last item uploaded. Replicate also
updates script variables DSResultCount and DSResult-* and uses them to enumerate the downloaded and
uploaded items in a script.

Version option
Replicate with option -versions copies all file versions and file properties from one file or collection to
another. The permission settings are not copied. Also, the ownership of the copied object belongs to the
user who issues the Replicate command. Use the following syntax to copy file versions.

Replicate -versions [file or collection handle] <destination collection

<destination server name>>
For example, the following command can be used to copy the properties and file versions of File-123 to
Collection-10 in server Polaris.

Replicate -v File-123 Collection-10 polaris

The command assumes that you have successfully logged into the server Polaris and attempted to obtain
necessary credentials and access parameters to Polaris from the login context cache based on the server
named Polaris. See Custom property support on page 7–5 on how context caching works.

A user can supply the target server's URL and authentication token instead of a server name (rather than a
login context name) and still be able to copy version files across servers.

Replicate attempts to retrieve custom properties as well as standard properties, such as display name and
summary. In order to do so, the command looks for custom property definitions in a schema cache that the
DSClient/SDK library maintains in the client machine. If it finds custom property definitions in the cache,
the command retrieves the corresponding values from the server. This means that if the command cannot
find either the schema cache or locate any custom property definition in the cache, no custom properties
(which are defined in the server) are retrieved. Refer to Custom property support on page 7–5 and the
command Updateschema on page 7–67 for enabling schema caching.

DocuShare Windows Client SDK 7–55

Console commands DSAxess Console

ResumeOnError
ResumeOnError [on/off]

ResumeOnError controls resumption of the script execution after DsAxess detects an error condition.

The statuscheck switch should be off. Otherwise, if a non-zero status code is generated, the script will quit
without executing the rest of the script. Even with the statuscheck off, DsAxess aborts executing a script if
it encounters any of the following status codes:

DSAXES_E_BADSCRCMD // Invalid script command

DSAXES_E_CANCEL // User canceled

DSAXES_E_APPSELECT // Terminate console

DSAXES_E_SYSRES // Memory or resource alloc error

DSAXES_E_MODNOTFOUND // Library not found

DSAXES_E_LIBOPEN // Library not registered

DSAXES_E_BADPARAM // Invalid parameter to DS command

DSAXES_E_VARNOTFOUND // undefined variable

DSAXES_E_BADLINK // OLE interface error

You can prevent a script from quiting despite these status codes. To do so, add a ResumeOnError
statement to the script. Set it to on before a statement, that performs a docushare operation, is executed
and raises one of the above error codes. In the event of an error, DSAxess resumes the script execution at
the next script statement that follows the erred statement.

The following script uploads a file to Collection-11 and copies it to Collection-10. In case the upload or copy
operation fails, the ResumeOnError on statement at the beginning of the script prevents the script from
terminating and takes control to recover the code.

ResumeOnError on
cd Collection-11
put "c:\temp\foobar.doc"
if %DSStatus% <> 0 then
goto HANDLEERRORPUT
copy %DSHandle% Collection-10
goto HANDLEERRORCOPY
...
goto DONE
:HANDLEERRORPUT
echo Upload failed: StatusCode %DSStatus%
...
goto DONE
:HANDLEERRORCOPY

7–56 DocuShare Windows Client SDK

DSAxess Console Console commands

echo Copy failed: StatusCode %DSStatus%

...
:DONE
exit

DocuShare Windows Client SDK 7–57

Console commands DSAxess Console

Search
Search <"term1=value1" ...> [output=FilePath]

The Search command searches DocuShare objects that meet the criteria given by a combination of the
following terms:

• max_hits= (defaults to 100)

• scope= (any collection handle or all; defaults to current collection)
• entity= File (see file; defaults to all)
• contains= not (to negate criteria)
• created_from= 10, created_to=0 (find items created since 10 minutes ago)
• modified_from=60, modified_to=30 (find items modified 30 to 60 min ago)
• title= (title of item)
• file= (filename)
• object_type= (MIME type)
• owner= (owner of item)
• summary=, description=, keywords=, author=, modified_by= (only one of these can be specified)
The entity, term, can be set to one of the following object types: Collection, File, Calendar, BulletinBoard,
User, or Group.

The property identifier, title, can be omitted for a search by title. Thus, to search items whose titles include
proposal, you can issue the command:

Search proposal
The command records the transaction result to the system registry. The [DSAxess\Console] registry key is
located in [HKCU\Software\Xerox\DocuShare Client]. The transacted handle is stored as Handle. The
output handle value is the number of found items.

Search sets script variable DSHandle to the number of found items. Search also updates script variables
DSSearchHitCount and DSSearchHit-*. Variable DSSearchHitCount contains the number of found items.
Variable DSSearchHit-* contains the handles for the found objects and uses them to enumerate the found
items in a script.

The following script uses the Search command to find MS Word documents whose titles contain the
phrase proposal, and archives them in the PC folder specified by system variable %temp%.

@echo off
let SearchTitle="test"
login
cd Collection-10
search title=%SearchTitle% entity=File
echo %DSSearchHitCount%
let ItemIndex=0
:StartLoop
if %ItemIndex% >= %DSSearchHitCount% then

7–58 DocuShare Windows Client SDK

DSAxess Console Console commands

goto EndLoop
let %ItemHandle% ="%DSSearchHit-%ItemIndex%%"
echo %%ItemHandle%%
getprops %%ItemHandle%%
#delete %%ItemHandle%%
:BumpIndex
let ItemIndex=ItemIndex+1
goto StartLoop
:EndLoop

Enhancements
Example 1: Support for paged search

SEARCH [page=n:m] [sortby=key:order] <request-args>

Where n is the page offset, m is the page size, key is the sort key and order is the sort order. Page size
regards the maximum number of results that the paged search should return. Page offset is the offset into
the list of all results, of the first result actually returned to the client.

The example commands below repeats three times, a search for titles that contain foo bar and retrieves
10 hits at a time. They also sort the hits by the last modification date in descending order.

SEARCH page=1:10 sortby=getlastmodified:descending "foo bar"

...
SEARCH page=11:10 sortby=getlastmodified:descending "foo bar"
...
SEARCH page=21:10 sortby=getlastmodified:descending "foo bar"
...
To specify multiple pairs of sort key and sort order, use commas to separate the pairs as shown below
when specifying the sortby parameter. No spaces should appear in the list.

sortby=key-order1,key-order2,key-order3,...

Example 2: Support for XDB-based search

SEARCH -xdb <scope=p> <depth=n> <syntax=x> <xsl=s> <output=o> [context=c1]

[content=c2]
The -xdb switch tells SEARCH to use the XDB search mode.

• p—Specifies the search scoope; it is set to a collection handle. If no scope assignment is made, the
command uses the current collection as the scope.
• n—Specifies the search depth. If omitted, its value defaults to 10000.
• x—Can be set to an optional value of xml.
• s—Can be set to an optional url where an xsl transformation is located.
• o—Can be set to an optional file system path where the queried results should be saved. Since
results are in XML, the path should end with a .xml filename.

DocuShare Windows Client SDK 7–59

Console commands DSAxess Console

• c1—The value of an XDB context keyword.

• c2—The value of an XDB content keyword.
The examples below perform an XDB search for a context value of AR in Collection-42.

CD Collection-42
SEARCH -xdb context=AR
To save the XML query results in a file, enter:

SEARCH -xdb context=AR "output=c:\temp\xdb query results.xml"

7–60 DocuShare Windows Client SDK

DSAxess Console Console commands

Setparam
Setparam <name> <value>

The Setparam command assigns a new value to the named parameter. The modified names and their
valid values are:

• server=(URL), proxy=(URL), auth=(cookie)

• xml=(0/1), txpacket=(128..0x10000), txtimeout=(1..300)
• downloadclashprompt=(0/1), uploadclashprompt=(0/1), uploadasnewdoc=(0/1)
• cacheexpireminutes=(0 for disabling directory cache)
The table lists parameters for GetParam/Setparam, their descriptions, and the units of measurement used
by numeric parameters.

Parameter Units/Type Description

txpacket bytes Transmission buffer size

txtimeout milliseconds Transmission timeout

cacheexpireminutes minutes Gateway cache expiration time

server – Current DocuShare server home URL

proxy – Current proxy server URL

auth – DocuShare session handle

ipaddr – Web server IP

hostname – Web server hostname

port – Web server port number

xml boolean Server supports XML API

serverreadonly boolean Server in maintenance mode

DocuShare Windows Client SDK 7–61

Console commands DSAxess Console

SetProps
SetProps <ObjectHandle> ["prop1=value1" ...]

The SetProps command modifies the specified properties of a DocuShare object (ObjectHandle). To
change the summary text to Meeting agenda, specify summary=Meeting agenda. Refer to GetProps on
page 7–34 for the list of available properties.

SetProps set script variable DSHandle to the handle number for the modified object.

Enhancements
Example 1: Creating and updating instance properties

SetProps can be used to create and update one or more instance properties—properties defined per
object instance and not defined in the server's class schemata.

The usual syntax applies to instance properties. No optional switch is used to specify that a property, you
update, is an instance property. The DocuShare server regards it as an instance property if the property
name is not found in the class schemata.

This creates a file instance property call mySpecialProp and assigns the value test 456.

SETPROPS File-123 "mySpecialProp=test 456"

An instance property created by SetProps receives the data type of text. SetProps does not support
creation of a non-text property.

Example 2: File version properties

The SetProps command can be used to modify properties of a file version that is specified by a file handle
and a version number.

SETPROPS File-n/m <prop1=value1 ...>

Where File-n is the file handle, and m is the ordinal version number of a file version.

If you know the Version handle of a version object, use the version handle.

SETPROPS Version-n <prop-value list>

Use the property name, comment, to update the comment text of a version.

Example 3: Creating and updating an object link

Documentation not yet available.

7–62 DocuShare Windows Client SDK

DSAxess Console Console commands

StatusCheck
StatusCheck [on/off]

The StatusCheck command starts or stops checking all DSAXES status or result codes generated by
commands executed by a script. With StatusCheck switched on, any non-zero status code terminates the
executing script. If StatusCheck is switched off and ResumeOnError is off, the script is terminated only if
one of the following status codes is encountered.

Status Description

DSAXES_E_BADSCRCMD Invalid script command

DSAXES_E_CANCEL User canceled

DSAXES_E_APPSELECT Terminate console

DSAXES_E_SYSRES Memory or resource allocation error

DSAXES_E_BADPARAM Invalid parameter to DS command

DSAXES_E_BADLINK OLE interface error

The statuscheck option is automatically enabled when a console session starts.

DocuShare Windows Client SDK 7–63

Console commands DSAxess Console

Switchto
Switchto <server name> [username]

For example, having logged into qatest-nt6, a user can switch from docushare.usa to qatest-nt6. The user
can issue the command, Switchto qatest-nt6, to switch to the earlier login context without using a formal
login dialog.

The server name supplied to Switchto can be the server's fully qualified URL or the first part of the host
name that appears in the server's home URL. For example, if the URL supplied in the login dialog was
http://docushare.usa.xerox.com/, the name for Switchto can be docushare or docushare.usa.
DSAxess utilizes the first server entry it finds in the cache that completely or partially matches the supplied
name.

To use the context switch in Replicate, follow these steps:

1. Log into a target server where the source object is to be copied, such as
docushare.usa.xerox.com.
2. Log into a server where a source object exists, such as qatest-nt6.adoc.xerox.com.
3. Issue Replicate from the source server context using this syntax:
Replicate File-123 Collection-10 qatest-nt6
The above command replicates File-123, file contents and all standard and custom properties, into
Collection-10 in server qatest-nt6.

Previous versions of DSAxess required a user to explicitly specify the URL, authentication token, and
proxy address within the Replicate command line. With the server context information stored, DSAxess
can now pull these parameters out of the cache based on a short server name.

Before Replicate can successfully copy custom properties, the user must:

• Map the server using the Mapserver command (or use Windows Explorer, if the Windows Client is
installed).
• Run DSAxess and log into the server specifying the same fully qualified URL used to create the
server map.
• Execute the Updateschema command so that Replicate has access to the latest schema from the
server.

7–64 DocuShare Windows Client SDK

DSAxess Console Console commands

Tree
Tree [-all] [-flat] [depth=n] [output=FilePath]

The Tree command prints the current directory, including all subdirectories.

If -flat is specified, the output displays the hierarchical structure. If -all is specified, only collections are
displayed. The depth level is infinite, unless explicitly specified. If FilePath is specified, Tree outputs the
directory information to the specified file.

Tree sets script variable DSHandle to the handle number for the current collection.

Optional line switches

The Tree command has additional optional command line switches that can be used.

• Optional switch -flat—Displays the names of found objects flush to the left edge of the display
window. Do not perform the indenting based on an object's nest level.
• Optional switch -all—List objects of all types including Document and other non-Collection types. If
the switch is not specified, the Tree command lists Collection objects only.

NOTE: The -all option does not support DocuShare workspaces.

The -all option directs the Tree command to use the DocuShare HTTP/XML PROPFIND command
to generate a query request to DocuShare. This allows objects of all types to be reported. If the
option is not used, the Tree command uses the DocuShare HTTP/XML SEARCH command, and
queries only for objects of the Collection type that appear in and under the current Collection. The
SEARCH-based Collection query can, by default, display up to 1,000 items. To increase the display
limit, use the max_hits property. For example, the command, Tree max_hits=4000, lists up to 4,000
Collection names.

The display limitation of 1,000 items per query does not apply if the -all option is used. Since the
display buffer used by DSAxess is limited to a maximum display of approximately 2,000 lines, all
queried items may not be printed in practice. You may want to use the -output option to direct a
large list to a file.

• Optional switch -depth=n—Limits the Tree query to the nth nest level. The switch works only when
-all is specified.
• Optional switch -output=filename—Use this option to save the queried tree in a file. The filename
can be a fully qualified pathname or a filename relative to the current directory previously set by the
LCD command (refer to LCD on page 7–40).

Enhancements
The enhancement enables listing of the versions and content elements of a docushare document object or
enables listing of file attachments linked to a DocuShare mail message object.

The added functionality relies on the <document_tree> and <mail_message_tree> properties supported
by DocuShare Release 4 and greater.

NOTE: The Tree command using <object handle> does not support Wikis and Weblogs.

DocuShare Windows Client SDK 7–65

Console commands DSAxess Console

To list the versions and content elements of a document, enter:

TREE <File-n>
To list the attachments of a mail message, enter:

TREE <MailMessage-n>
To print the versions and content elements of a file in a tree format, enter:

Collection-13>TREE File-31
Document Tree of File-31
- A4Pptest.rdo (File-31/1)
+-- A4Pptest.rdo (Rendition-46)
+-- A4Pptest.rdo (ContElem-1)
+-- 00000001.tif (ContElem-2)
+-- 00000002.!#! (ContElem-3)
+-- LOCK (ContElem-4)
+-- totalsz (ContElem-5)
In the example, the file has one version with one rendition and five content elements.

This command lists the files attached to a mail message.

Collection-247>tree MailMessage-225
Mail Message Tree of MailMessage-225
- AR8900_Test_Case_2.msg (Handle=File-2357, Type=NativeMessage)
- Attach-
1_New_Document_added_to_DS_4.0.1_Locales_Update_on_DocuShare_(_http___docush
are.usa.xerox.com__).msg (Handle=File-2359, Type=File)
- Attach-
2_New_Document_added_to_DS_4.0.1_Locales_Update_on_DocuShare_(_http___docush
are.usa.xerox.com__).msg (Handle=File-2358, Type=File)
- Attach-
3_New_Document_added_to_DS_4.0.1_Locales_Update_on_DocuShare_(_http___docush
are.usa.xerox.com__).msg (Handle=File-2360, Type=File)
The mail message above has three file attachments and one native-message attachment.

7–66 DocuShare Windows Client SDK

DSAxess Console Console commands

Unlock
Unlock <FileHandle>

The Unlock command unlocks a file. The command records the transaction result to the system registry.
The[DSAxess\Console] registry key is located in [HKCU\Software\Xerox\DocuShare Client]. The
transacted handle is stored as DSHandle.

Unlock sets DSHandle to the unlocked file.

Unmapserver
Unmapserver <name> <account>

The Unmapserver command removes a server map from the server map storage maintained by the SDK
library.

NOTE: The access information stored by this command is shared by the DocuShare Windows Client
and DocuShare Outlook Client. Use the Refresh command if the name of the server continues
to appear.

Updateschema
The Updateschema command retrieves the schema from a DocuShare server and caches it for later use
by GetProps and Replicate. To invoke the command:

1. Log into a server containing the schema to be updated.

2. Enter the name of the Updateschema command without any argument (no optional switches
defined).

DocuShare Windows Client SDK 7–67

Console commands DSAxess Console

WebLogin
WebLogin [-method=m] [webuser] [webpswd] [dsuser] [dspswd]

The WebLogin command sends user ID and password to a web server for HTTP access authorization.

Where m is basic or siteminder. Webuser and webpswd are username and password strings for a web
server-initiated authentication challenge. Dsuser and dspswd are login credentials for a DocuShare server.
The command will prompt you if you do not supply all parameters. Use the SETPARAM SERVER
command to specify a DocuShare server. Use the SETPARAM PROXY command to specify a proxy
server if your network uses a proxy.

The supported types of web server authentication are as follows:

• Basic authentication: refer to RFC 2617

• Siteminder authentication: HTTP POST-based proprietry user authentication protocol of ...
The login example, below, uses SETPARAM to specify a server and proxy, and WEBLOGIN to log into the
siteminder-protected server. This example assumes that the DocuShare server enables the auto login
feature which instructs DocuShare to honor the web server credential, and grant access to the web server-
authenticated user without requiring its own authentication.

SETPARAM server https://www.docushare.xerox.com

SETPARAM proxy http://www.wb.xerox.com
WEBLOGIN -method=siteminder joecool mypass joecool [null]
The web server account is joecool. The DocuShare user account is also named joecool. The web server
password is mypass. However, the DocuShare password is set to [null]. The special [null] value clears
the password field so that the WEBLOGIN command passes an empty password to the auto login-enabed
DocuShare server for its login processing. An auto login-enabled DocuShare does not accept a password
as it already receives credential information from the web server. However, if the web server account and
DocuShare user account uses different names, a separate and valid password must be specified for the
DocuShare user account.

For a web server protected by basic authentication, this command may be used. Again, the DocuShare
server enables auto login.

WEBLOGIN -method=basic joecool mypass joecool [null]

Writelog
Writelog <FilePath>

The Writelog command writes console text to a local file given by FilePath.

The directory for the file path must be created; if the directory does not exist, DSAxess will terminate with a
notice or warning.

If the directory contains spaces, then the file path must be in quotes.

7–68 DocuShare Windows Client SDK