Beruflich Dokumente
Kultur Dokumente
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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.
• 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
2.1 Overview
The Windows SDK supplies four ActiveX libraries:
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 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.
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.
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.
Table 2–1 shows the applicability of the IItemObj interface properties with respect to the supported item
types.
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
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
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
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
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
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.
Description
Collection
Calendar
Version
Method
Server
Group
User
URL
File
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
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
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.
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.
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.
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.
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: In real code the [...] placeholders are replaced with other property bit-masks.
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:
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.
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.
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 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.
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.
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
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.
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
...
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
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
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.
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.
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)
dim file
set file = server.CreateObject("File-123")
file.AttachParents(parentList)
The AttachParents call, internalizes the new parents list in the file object.
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
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
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
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
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
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:
• 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"
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
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
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.
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.
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
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
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.
• Data
• Reload
• AutoDelete
• DSGatewayMode
• DSErrorCode
• DSServerMapId
Some of these properties have been described; those that have not been are described below.
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.
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:
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")
• 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.
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.
...
myProp.vt = VT_I4;
myProp.lVal = 123;
SetCustomProp(L"MyCustomName", DSAXES_PROPTYPE_INTEGER, &myProp);
...
In Visual Basic, use this entry.
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.
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.
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:
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.
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.
lstDisplay.AddItem strTitle
Wend
End Sub
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
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.
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
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.
File DSSRCH_TYPE_FILE
Collection DSSRCH_TYPE_COLLECTION
Calendar DSSRCH_TYPE_CALNDR
User DSSRCH_TYPE_USER
Group DSSRCH_TYPE_GROUP
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
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.
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).
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.
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 )
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.
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>
</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.
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 )
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.
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.
status = store.Load
status = store.DoSelectDialog( 0,
"Select Servers",
"Servers you select will be opened",
"",
0,
0 )
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.
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.
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
The following classes are available from the Type library files:
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.
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.
Here is an example application that logs into a server and uploads a file.
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.
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.
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.
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.
In your application, such as in the OnCreate for your main window, you need to instantiate an event
handler object.
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 ->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.
GatewayHandler
GatewayClient
GatewayClient
GatewaySettings
GatewaySettings
ErrorReportObject
ErrorReportObj
NameConflictResolver
NameConflictResolver
StatusObject
(StatusObj)
QueriedProperties
PropertyIDs
PropertyID
PropertyID
DSAccessData
DSAccessData
Server
DSServerMap.Server
ClientRequest
ClientRequest
ContentData
ContentData
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
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
Methods Properties
InitiateHistory
InitiateLock
InitiateMove
InitiatePost
InitiateRename
InitiateSchema
InitiateUserAuth
OpenCollection
OpenContainer
RegisterClient
Search
SetItemProplds
SetMode
SetProps
SetShellNotification
Submit
Upload
Wait
AwaitCompletion
VB AwaitCompletion() as Long
The AwaitCompletion method waits until the on-going network call completes.
Return value
Value Description
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.
Cancel
VB Cancel() as Long
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.
ClearCollectionCache
The ClearCollectionCache method clears the item listing cache of one collection or all collections.
Parameters
Parameter Description
Return value
Value Description
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.
DoLoginDialog
VB DoLoginDialog() as Long
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
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.
Download
Parameters
Parameters Description
Return value
Value Description
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
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.
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.
GetAuthToken
The GetAuthToken retrieves user credentials generated by a DocuShare server in response to a call to
InitiateUserAuth or DoLoginDialog.
Parameters
Parameter Description
Return value
Value Description
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 )
{
CString strAuthToken( bsAuthToken );
printf( "AuthToken: %s\n", (LPCTSTR)strAuthToken );
printf( "User ID: %u\n", lUserId );
SysFreeString( bsAuthToken );
}
GetItemProplds
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
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.
GetLastError
VB GetLastError() as Long
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.
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
500 HTTP_INTERNALSERVERERROR
501 HTTP_NOT_IMPLEMENTED
502 HTTP_BADGATEWAY
503 HTTP_MAXCONNECTS
504 HTTP_GATEWAYTIMEOUT
WSAEINTR
WSAEBADF
WSAEACCES
WSAEFAULT
WSAEINVAL
WSAEMFILE
WSAEWOULDBLOCK
WSAEINPROGRESS
WSAEALREADY
WSAENOTSOCK
WSAEDESTADDRREQ
WSAEMSGSIZE
WSAEPROTOTYPE
WSAENOPROTOOPT
WSAEPROTONOSUPPORT
WSAESOCKTNOSUPPORT
WSAEOPNOTSUPP
WSAEPFNOSUPPORT
WSAEAFNOSUPPORT
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
WSANO_RECOVERY
WSANO_DATA
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
GetMode
VB GetMode() as Long
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.
GetProps
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
Return value
Value Description
Remarks
Existing properties is preserved in the source, IItemObj, unless they are replaced by the retrieved
properties.
GetStatus
VB GetStatus() as Long
The GetStatus method retrieves the gateway status. The status is returned as a success or failure code.
Parameters
None
Return value
Value Description
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.
GetTransferInfo
Parameters
Parameter Description
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.
GoOffline
Parameters
Parameter Description
Return value
Value Description
Remarks
Valid offline control flags are:
• DSXDIALUP_DISCONNECT_NEVER
• DSXDIALUP_DISCONNECT_ASK
GoOnline
Parameters
Parameter Description
Return value
Value Description
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
• 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
InitiateBulkDownload
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
Return value
Value Description
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:
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.
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.
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
InitiateBulkReplicate
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
Return value
Value Description
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
InitiateBulkUpload
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
Return value
Value Description
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.
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.
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.
InitiateCollectionCreate
Parameters
Parameter Description
Return value
Value Description
Remarks
If pszServerUrl, pszAuthToken, and pszProxyServer are empty, the values from the previous command are
used.
InitiateCollectionOpen
The InitiateCollectionOpen method opens a collection in a DocuShare server and queries its contents.
Parameters
Parameter Description
Return value
Value Description
Remarks
InitiateCollectionOpen is an asynchronous method. Control returns after a socket is opened. Use the
OpenCollection method for synchronous opening of a collection.
If pszServerUrl, pszAuthToken, and pszProxyServer are empty, the values from the previous command are
used.
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.
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() );
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.
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
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 ) );
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 );
}
}
}
InitiateContainerOpen
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
Parameter Description
Return value
Value Description
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.
The example below uses InitiateContainerOpen to asynchronously retrieve a Calendar's directory from a
DocuShare server.
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
InitiateCopy
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
Return value
Value Description
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
InitiateCreateObject creates an object on a DocuShare server using the DocuShare HTTP/XML MKRES
command.
Parameters
Parameter Description
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.
InitiateDelete
Parameters
Parameter Description
Return value
Value Description
Remarks
If pszServerUrl, pszAuthToken, and pszProxyServer are empty, the values from the previous command are
used.
InitiateDisown
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
Return value
Value Description
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.
InitiateDownload
Parameters
Parameter Description
Parameter Description
Return value
Value Description
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.
InitiateGet
Parameters
Parameter Description
Return value
Value Description
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.
InitiateHistory
Parameters
Parameter Description
Return value
Value Description
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, "", "", "" ) )
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 );
}
InitiateLock
Parameters
Parameter Description
Return value
Value Description
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.
InitiateMove
Parameters
Parameter Description
Return value
Value Description
Remarks
If pszServerUrl, pszAuthToken, and pszProxyServer are empty, the values from the previous command are
used.
InitiatePost
The InitiatePost methods submits an urlencoded form or an XML message using HTTP POST.
Parameters
Parameter Description
Parameter Description
Return value
Value Description
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.
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.
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
InitiateRename
Parameters
Parameter Description
Return value
Value Description
Remarks
If pszServerUrl, pszAuthToken, and pszProxyServer are empty , the values from the previous command
are used.
InitiateSchema
Parameters
Parameter Description
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.
InitiateUserAuth
The InitiateUserAuth method submits a user authentication request to a DocuShare server. Control returns
immmediately.
Parameters
Parameter Description
Return value
Value Description
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.
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.
OpenContainer
Parameters
ContHandle—the DocuShare handle of a container object for which directory information is retrieved.
Return value
Value Description
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.
OpenCollection
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
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.
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() )
{
RegisterClient
Parameters
Parameter Description
Return value
Value Description
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" );
Search
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
Return value
Value Description
Remarks
Refer to Performing basic searches on page 2–64 on how to utilize the Search method.
SetItemProplds
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
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.
DSAXES_PROPID_FILE_MIMETYPE MimeType
DSAXES_PROPID_FILE_MAXVERSION MaxVersions *
DSAXES_PRODID_FILE_SIZE Length *
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.
DSAXES_PROPID_FILE_MIMETYPE MimeType
DSAXES_PROPID_FILE_AUTHOR Author
DSAXES_PROPID_FILE_MAXVERSION MaxVersions *
DSAXES_PRODID_FILE_SIZE Length *
DSAXES_PROPID_FILE_ABSTRACT Abstract *
DSAXES_PROPID_COLL_SIZE Length *
NOTE: Properties marked with asterisks are read-only properties; therefore, applicable to GetProps
only.
SetMode
Parameters
Parameter Description
Parameter Description
Parameter Description
Parameter Description
Parameter Description
Parameter Description
Return value
The previous states of all of the mode flags.
SetProps
The SetProps method set properties for a DocuShare file or collection. This method is also used to set
server access parameters.
Parameters
Parameter Description
Return value
Value Description
Remarks
If a propId flag is set and a corresponding value is absent from the IItemObj, the method fails.
SetShellNotification
The SetShellNotification method instructs DSAXESS to notify the system shell (DocuShare in Explorer) of
an event whenever the gateway process terminates.
Parameters
Parameter Description
Return values
Value Description
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.
Submit
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
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.
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.
Upload
The Upload method uploads a file with custom properties or a folder without custom properties to a
DocuShare server.
Parameters
Parameter Description
Return value
Value Description
Value Description
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.
Wait
Parameters
Parameter Description
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.
DSCollHandle
VB DSCollHandle As Long
Access Read/Write
The DSCollHandle property designates the collection to be opened or its contents searched.
DSContainerHandle
VB DSContainerHandle as String
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.
DSContent
VB DSContent As String
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
Access Read/Write
The DSCreatedTimeFrom property sets the begin creation time for performing a search.
DSCreatedTimeTo
VB DSCreatedTimeTo As Date
Access Read/Write
The DSCreatedTimeTo property sets the end creation time for performing a search.
DSDisplayName
VB DSDisplayName As String
Access Read/Write
The DSDisplayName property sets the display name value for performing a search.
DSFileHandle
VB DSFileHandle As Long
Access Read/Write
DSFileName
VB DSFileName As String
Access Read/Write
The DSFileName property sets the filename value for performing a search.
DSFileType
VB DSFileType As String
Access Read/Write
The DSFileType property sets the MIME type when performing a search.
DSHandle
VB DSHandle As 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.
InitiateBulkDownload n/ab
InitiateBulkReplicate n/ab
InitiateBulkUpload n/ab
DSHandleList
VB DSHandleList As String
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.
DSItemListFile
VB DSItemListFile As String
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.
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.
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.
DSItemProp
VB DSItemProp As String
Access Read/Write
The DSItemProp property enters the name and values for custom properties in a search.
DSKeywords
VB DSKeywords As String
Access Read/Write
The DSKeywords property enters the keyword values when performing a search.
DSMaxItems
VB DSMaxItems As Long
Access Read/Write
The DSMaxItems property limits the number of items to be returned from a search request.
DSModifiedTimeFrom
VB DSModifiedTimeFrom As Date
Access Read/Write
The DSModifiedTimeFrom property sets the beginning of the modified time for performing a search.
DSModifiedTimeTo
VB DSModifiedTimeTo As Date
Access Read/Write
The DSModifiedTimeTo method sets the end of the modified time for performing a search.
DSObjectHandle
VB DSObjectHandle as String
Access Read/Write
DS ObjectHandle contains the handle of a DocuShare object that one of the listed methods uses.
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.
DSObjectTypeNum
VB DSObjectTypeNum as 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
Access Read/Write
DSTime
VB DSTime As 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
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.
LocalTime
VB LocalTime As Date
Access Read/Write
• 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
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.
Proplds
VB PropIds As Long
Access Read/Write
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.
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_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.
GatewayClient
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.
GatewaySettings
The following example shows use of GatewaySettings to upload data silently and quit the operation if the
server does not respond within 30 seconds.
DSAccessData
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.
ClientRequest
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.
• 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.
"<prop>" & _
"<displayname/>" & _
"<summary/>" & _
"</prop>" & _
"</propfind>"
status = gateway.Submit(request)
ServerResponse
• 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.
request.RequestURI = "PROPFIND/File-1234"
if gateway.Submit(request) = 0 then
MsgBox gateway.ServerResponse.MessageHeader, , "MessageHeader"
MsgBox gateway.ServerResponse.ContentData.Text, , "ContentData"
end if
The VB code below illustrate how the event-driven inspection of a response message can be achieved
using GatewayHandlerEvents and ServerResponse.
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.
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.
Example 2
This example retrieves and lists DocuShare properties of a file.
NOTE: The examples above do not check the return values from Submit and Parsing functions.
3.2.2 GatewayClient
List of GatewayClient methods and properties.
CancelCode
CancelWindow
ID
IPAddress
Name
Port
WindowHandle
CancelCode
VB CancelCode as Long
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;
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
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
Access Read/Write
Remarks
GatewayHandler.RegisterClient updates this property.
IPAddress
VB IPAddress as String
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
Access Read/Write
Remarks
GatewayHandler.RegisterClient updates this property.
Port
VB Port as Long
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
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.2.3 GatewaySettings
List of 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
AddDSCGI
VB AddDSCGI as boolean
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
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.
AutoSetWWWAuth
VB AutoSetWWWAuth as boolean
Access Read/Write
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:????????
CacheExpireMinutes
VB CacheExpireMinutes as 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:????????
CanKeepAlive
VB CanKeepAlive as boolean
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
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.
CompressResponseData
VB CompressResponseData as boolean
Access Read/Write
Remarks
Up to and including version 3.1, DocuShare does not support gzip compression.
CopyAllVersions
VB CopyAllVersions as boolean
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.
DefNewFileMaxVersions
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:
DefNewFileMaxVersions=dword:
EnableCache
VB EnableCache as boolean
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.
ErrorDisplayStatus
VB ErrorDisplayStatus as DSX_ERRDISP
Access Read/Write
Flag Description
ErrorReportObject
Access Read/Write
File
VB File as String
Access Read/Write
File contains the pathname of a file that the gateway uses to store a response from a DocuShare server.
FileFilter
VB FileFilter as string
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.
HttpRequestTimeout
VB HttpRequestTimeout as 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:
IgnoreFileTypeOnCompress
VB IgnoreFileTypeOnCompress as boolean
Access Read/Write
Remarks
DocuShare 3.1 or lower does not support compressed file upload.
• 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
IgnoreMIMEType
VB IgnoreMIMEType as boolean
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:
InitiateUpload pszMimeType
ItemDescriptorArrayFile
VB ItemDescriptorArrayFile as String
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.
ItemDescriptorArrayStorage
VB ItemDescriptorArrayStorage as 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
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.
LoadablePropIds
VB LoadablePropIds as long
Access Read/Write
Remarks
See LoadDefaultProps on how LoadablePropIds is used to perform the loading of property values.
LoadablePropIdsCore
VB LoadablePropIdsCore as long
Access Read/Write
Remarks
See LoadDefaultProps on how LoadablePropIdsCore is used to perform the loading of property values.
LoadablePropsStore
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.
LoadDefaultProps
VB LoadDefaultProps as boolean
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.
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.
Method HTTP/XML
Upload ApplyUpload
InitiateBulkUpload ApplyUpload
InitiateBulkReplicate ApplyUpload
NameConflictResolver
VB NameConflictResolver as NameConflictResolver
Access Read/Write
NoErrorDialog
VB NoErrorDialog as boolean
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
Access Read/Write
Remarks
This property corresponds to the GatewayHandler mode flag
DSAXES_MODE_NOSERVERSTATUSQUERY
PromptOnDownloadNameClash
VB PromptOnDownloadNameClash as boolean
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.
PromptOnUploadNameClash
VB PromptOnUploadNameClash as boolean
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.
PropertyAttributeIDs
VB PropertyAttributeIDs as 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.
Flag Description
QueriedProperties
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.
QueriedPropertyIDs
Access Read/Write
Parameters
ItemType contains the base type identifier of a DocuShare item. Valid base type identifiers are listed in the
table.
Bulletin DSXITEMTYPE_BULLETIN 0
Core 0 DSAXES_PROPID_CORE_DEFAULT_QUERY
Event DSXITEMTYPE_EVENT 0
Group DSXITEMTYPE_GROUP 0
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.
ReceptionTimeOut
VB ReceptionTimeOut as 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
Access Read/Write
Remarks
The property applies to a bulk replication started by a call to GatewayHandler.InitiateBulkReplicate.
Silent
VB Silent as boolean
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
Access Read/Write
StorageMedium
VB StorageMedium as 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.
TransmissionBufferSize
VB TransmissionBufferSize as long
Access Read/Write
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
C++
Access Read/Write
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:
TransmissionTimeOut
C++
Access
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
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.
3.2.4 DSAccessData
List of DSAccessData methods and properties
AuthToken Password
BrokerMap Port
CapabilityFlags Protocol
DocuShareAddress ProxyAddress
Domain ServerMap
DSVersionNumber SupportDS1x
GatewaySettings UseProxy
HostName UserHandle
IPAddress UserName
IsUserLoggedIn VirtualRoot
AuthToken
VB AuthToken as string
Access Read/Write
BrokerMap
VB BrokerMap as Variant
Access Read/Write
BrokerMap contains a server map for a peer workstation associated with the DSAccessData instance.
CapabilityFlags
VB CapabilityFlags as long
Access Read/Write
CapabilityFlags contain DSCAPFLAG flags that determine the DocuShare HTTP/XML Interface capability
of a DocuShare server.
Remarks
CapabilityFlags is set upon successful completion of a DocuShare call, such as DoLoginDialog and
OpenCollection.
DocuShareAddress
VB DocuShareAddress as string
Access Read/Write
Domain
VB Domain as string
Access Read/Write
Domain contains the domain of a DocuShare server in which a user login has been performed.
DSVersionNumber
VB DSVersionNumber as long
Access Read/Write
Remarks
The high word indicates the major version number. The low word indicates the minor version number.
GatewaySettings
GatewaySettings contains a reference to the GatewaySettings object associated with the DSAccessData
instance.
HostName
VB HostName as string
Access Read/Write
IPAddress
VB IPAddress as string
Access Read/Write
IsUserLoggedIn
VB IsUserLoggedIn as boolean
Remarks
The determination is made by testing the following items:
Password
VB Password as string
Access Read/Write
Port
VB Port as long
Access Read/Write
Protocol
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
C++
Access Read/Write
ServerMap
VB ServerMap as 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
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.
UseProxy
VB UseProxy as boolean
Access Read/Write
UserHandle
VB UserHandle as Variant
Access Read/Write
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.
UserName
VB UserName as string
Access Read/Write
Remarks
UserName is set after a call to one of the following GatewayHandler methods successfully completes.
VirtualRoot
VB VirtualRoot as string
Access Read/Write
3.2.5 ClientRequest
List of ClientRequest methods and properties.
Action Header
ActionId HTTPVersionMajor
Broker HTTPVersionMinor
Clear MessageHeader
ContentData Method
ContentType Parameters
Cookie RequestURI
DispatchedTime URL
Clear
VB Clear()
Action
VB Action as String
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.
ActionId
VB ActionId as DSX_CMDID
ActionId contains an ordinal number that identifies a DocuShare command or a generic HTTP method that
is being or has been processed.
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_HISTORY CMDID_MKDIR
CMDID_HTTP_DELETE CMDID_MOVE
CMDID_HTTP_GET CMDID_SEARCH
CMDID_HTTP_HEAD CMDID_SETPROPS
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++
ContentData
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.
ContentType
VB ContentType as String
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
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.
DispatchedTime
C++
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
C++
Access Read/Write
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.
HTTPVersionMajor
VB HTTPVersionMajor as 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
Access Read/Write
HTTPVersionMinor contains a minor version number of the HTTP protocol that the gateway supports.
MessageHeader
VB MessageHeader as String
Access Read/Write
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.
Method
VB Method as String
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
Parameters
VB Parameters as String
Parameters contains a display string consisting of parameters used to initiate a DocuShare command or
an HTTP method.
RequestURI
VB RequestURI as String
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.
URL
VB URL as String
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:
• 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.
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:
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;
...
}
3.2.6 ServerResponse
List of ServerResponse methods and properties
Clear ErrorCode
ContentData ErrorDescription
ContentEncoding HasTextualContent
ContentLength Header
ContentType HTTPResultCode
Cookie MessageHeader
DSError ReceivedTime
DSHandle RemoteTime
DSUser StatusCode
DSVersion StatusLine
Clear
VB Clear()
ContentData
Contains a ContentData object that encapsulates the content data of a response message.
ContentEncoding
VB ContentEncoding as string
ContentEncoding contains the value of the header field Content-Encoding if the field appears in the
response message.
ContentLength
VB ContentLength as long
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.
ContentType
VB ContentType as string
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
Cookie contains the value of the header field Set-Cookie if the field appears in the response message.
DSError
VB DSError as string
DSError contains the value of the header field DocuShare-Error if the field appears in the response
message.
DSHandle
VB DSHandle as string
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.
DSUser
VB DSUser as string
DSUser contains the value of the header field DocuShare-User if the field appears in the response
message.
DSVersion
VB DSVersion as string
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
Access Read/Write
ErrorDescription
VB ErrorDescription as string
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
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
Header contains the value of a specified header field if the field appears in the response message.
Parameters
Name—a header field name.
HTTPResultCode
VB HTTPResultCode as long
Access Read/Write
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.
Refer to RFC 2616, Hypertext Transfer Protocol -- HTTP/1.1, for definition of a result code.
MessageHeader
VB MessageHeader as string
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.
ReceivedTime
VB ReceivedTime as date
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
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.
StatusCode
VB StatusCode as 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.
DSAXES_E_BUSY Busy
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
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.2.7 ContentData
List of 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
Add
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.
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.
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.
DeclareXML
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
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.
ParseDirectory
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.
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.
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.
ParseProperties
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.
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.
ParsePropertiesAsDsxInfo
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.
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.
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.
ParseSchema
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.
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.
ParseVersionHistory
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
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.
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.
ParseUploadResult
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.
"--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+_
"--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.
fileObj.Name = "test1.htm"
fileObj.MaxVersions = 2
attach1.Name = "c:\doc\test1\a1.js"
attach2.Name = "c:\doc\test1\a2.gif"
status = gateway.Upload(_
DSAXES_PROPID_TITLE, _
DSAXES_PROPID_FILENAME or DSAXES_PROPID_MAXVERSIONS, _
fileObj, "c:\doc\test1.htm")
if status = 0 then
DSCONTF_IDENTITY or DSCONTF_DESCENDANTS )
enumObj.Reset
wend
end if
Verify
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
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.
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.
InitiateCopy CMDID_MOVE
InitiateMove CMDID_MOVE
InitiateDelete CMDID_DELETE
GetProps CMDID_GETPROPS
SetProps CMDID_SETPROPS
CleanText
VB CleanText() as String
CleanText contains plain text content data. If the content type is text/html, HTML tags are removed.
DataCompression
VB DataCompression as Boolean
• 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
Delta
VB Delta as Variant
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.
File
VB File as string
Access Read/Write
File contains the pathname for a file that stores content data.
ParsedResultHandle
C++
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.
ParsedResultType
C++
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.
StorageMedium
VB StorageMedium as DSX_STGMEDIUM
StorageMedium determines the type of storage medium that the gateway uses to store content data.
Stream
VB Stream as Variant
Access Read/Write
Stream contains an object of the IStream interface that stores content data.
Text
VB Text as String
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
Access Read/Write
XMLDOM contains an object of the IXMLDOMDocument interface that stores content data if the content
type is text/xml.
ItemDescriptorArray
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.
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.2.8 PropertyIDs
Use property GatewaySettings.QueriedProperties to obtain a PropertyIDs enumerator object.
SearchRequest.QueriedProperties also produces a PropertyIDs object.
Add
Clear
Count
List
PropertyID
Remove
Add
C++
Add creates a PropertyID object of a specified identifier and item type, and add it to the PropertyIDs.
Parameters
Parameter Description
Clear
VB Clear()
C++
Remove
VB Remove(Index as Variant)
C++
Parameters
Index—a 0-based index number. It must be less than the value of Count.
Count
C++
List
C++
List generates a linear list of DocuShare property identifiers enumerated by the PropertyIDs.
Parameters
Parameter Description
Remarks
The following script lists the names of properties currently selected for OpenCollection,
InitiateCollectionOpen, and Search of GatewayHandler:
PropertyID
3.2.9 PropertyID
List of PropertyID methods and properties
ID
ItemType
Text
ID
VB ID as long
Access Read/Write
ID contains a DSAXES_PROPID property identifier for the DocuShare property represented by the
PropertyID.
ItemType
VB ItemType as long
Access Read/Write
ItemType contains a DSXITEMTYPE item type number for the item type defined by the PropertyID.
Text
VB Text as String
Access Read/Write
Text contains a DocuShare property name for the DocuShare property represented by the PropertyID.
3.2.10 ItemProperties
Use ClientRequest.ContentData.ItemProperties or ServerResponse.ContentData.ItemProperties to
retrieve an ItemProperties enumerator object.
Add
Clear
CopyTo
Count
ItemObject
ItemProperty
Remove
Add
Add creates an ItemProperty object of a specified property identifier and property value and adds it to the
ItemProperties.
Parameters
Parameter Description
Clear
VB Clear()
CopyTo
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.
Remove
C++
Parameters
Index—a 0-based index number. It must be less than the value of Count.
Count
VB Count as long
ItemObject
ItemObject contains an ItemObj object that stores the values of DocuShare properties enumerated by the
ItemProperties.
ItemProperty
Parameters
Index—a 0-based index number. It must be less than the value of Count.
3.2.11 ItemProperty
List of ItemProperty methods and properties
DisplayName
ID
Value
DisplayName
VB DisplayName as Variant
Access Read/Write
DisplayName contains a display name for the DocuShare property defined by the ItemProperty.
ID
VB ID as Variant
Access Read/Write
ID contains a DocuShare property name for the DocuShare property represented by the PropertyID.
Value
VB Value as Variant
Access Read/Write
Value contains a value for the DocuShare property that the ItemProperty represents.
3.2.12 ItemDescriptorArray
Use ContenData.ItemDescriptorArray to obtain an ItemDescriptorArray object.
Enumerator
ErrorDescription
File
StorageMedium
3.2.12.1 ItemDescriptorArray
There are no methods defined for this object.
Enumerator
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
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.
File
VB File as string
Access Read/Write
File contains a pathname for a file that stores the item descriptor array.
StorageMedium
VB StorageMedium as 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:
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.
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.
MaxHits
QueriedProperties
Scope
SearchTermsCollection
MaxHits
VB MaxHits as long
C++
Access
QueriedProperties
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.
Scope
VB Scope as String
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.
SearchTermsCollection
VB SearchTermsCollection as Object
Access Read-only
Remarks
The script fragment below creates three groups of search terms:
3.2.14 SearchTermsCollection
Use SearchRequest.SearchTermsCollection to obtain a SearchTermsCollection object.
Add
Count
Conjunct
Remove
Terms
XMLText
Add
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
Parameters
Index— index number of a SearchTerms object.
Count
VB Count as long
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
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
Access Read-only
Parameters
Index—zero-based index number of a SearchTerms object to reference. The value must be less than
Count.
XMLText
VB XMLText as String
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.
<or>
<and>
<eq>
<prop><entitytype/></prop>
<literal><![CDATA[File]]></literal>
</eq>
<contains>
<prop><displayname/></prop>
<literal><![CDATA[proposal]]></literal>
</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.2.15 SearchTerms
Use SearchRequest.SearchTermsCollection.Terms to obtain a SearchTerms collection object.
Add
Count
Conjunct
ID
NestedTerms
Remove
Term
XMLText
Add
Parameters
Parameter Description
Remove
Parameters
Index—index number of a SearchTerms object.
Count
VB Count as Long
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
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.
ID
VB ID as String
Access Read/Write
NestedTerms
NestedTerms contains a SearchTermsCollection object which is used to specify one or more groups of
search terms nested within the current SearchTerms.
Term
Access Read-only
Parameters
Index—zero-based index number of a SearchTerm object to reference. The value must be less than
Count.
XMLText
VB XMLText as String
XMLText generates XML text data based on the search terms contained in the SearchTerms.
3.2.16 SearchTerm
Use SearchRequest.SearchTermsCollection.Terms.Term to obtain a SearchTerm object.
Name
Operator
Value
XMLText
Name
VB Name as String
Access Read/Write
This property contains the name of a DocuShare property which is also the name of the search term.
Operator
VB Operator as String
Access Read/Write
Remarks
The valid operators depend on the search term association with the property type. Operators valid for
typical property types are shown below.
DocuShare handle eq
Value
VB Value as 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
XMLText generates XML text data based on the search term contained in the SearchTerm.
3.3 Constants
3.3.1 Special handle values
OBJTYPE_DOCUMENT Document
OBJTYPE_COLLECTION Collection
OBJTYPE_SERVER Server
OBJTYPE_GATEWAY Gateway
OBJTYPE_CALENDAR Calendar
OBJTYPE_BULLETIN Bulletin
OBJTYPE_USER User
OBJTYPE_GROUP Group
OBJTYPE_EVENT Event
OBJTYPE_SUBSCRIPTION Subscription
DATACOMPR_NONE No compression
To use the Submit method, follow the steps below for sending a request to a server for processing.
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.
<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
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.
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.
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.
ApplyUpload for compound file ParseUploadResult EnumObj for file renditions and
content elements
.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"/>
</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
</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.
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.
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, _
"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=...", _
"")
• 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.
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.
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.
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.
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
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
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.
• 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.
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.
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.
To download 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 )
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.
NextItem
Server
Browser
Wizard
ShortcutStore
Store
CustomProps
PropCollection
NextItem
CustomProp
CheckinServiceManager
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
Add
Parameters
pServer—an object of type Server.
Return value
Value Description
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.
CanAdd
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
Return value
Value Description
Clone
Close
VB Close() As Long
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
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.
DoSelectDialog
The DoSelectDialog method sets the IsSelected parameter (IsSelected on page 4–64) to True for each
server item selected.
Parameters
Parameter Description
Return value
Value Description
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.
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
Find
The Find method searches a Store object and returns the first Server object that meets the criteria.
Parameters
Parameter Description
Flags Description
Return value
This function returns an IDispatch pointer to a created Server object.
Load
VB Load() As Long
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
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
Protect
VB Protect() As Long
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
Remarks
See Save on page 4–15 for details.
Remove
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
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
Reset
VB Reset() As Long
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
Remarks
See Save on page 4–15 for details.
Save
VB Save() As Long
The Save method is used to save a Store object to the registry memory.
Parameters
None.
Return value
Value Description
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
Unprotect
VB Unprotect() As Long
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
Remarks
See Save on page 4–15 for details.
BaseRegistryKey
VB BaseRegistryKey As String
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.
ISProtected
VB IsProtected As Long
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
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.
NextPos
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).
Remarks
The following example iterates through a Store object and logs in all of the Server objects.
Options
VB Options As Long
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
SelectDialogOption
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.
Parameters
Parameter Description
Use one of the 32-bit wide constants below to choose between check box and radio button.
Constants Description
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
Remarks
If a value is not assigned, SelectDialogOption contains a value of -1.
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.
4.2.2 Browser
List of Browser methods and properties.
Cookie Options
DocuShareAddress ProxyAddress
Init View
NavigateTo ViewProps
OwnerHwnd
Init
Parameters
pServer—a valid Server object.
Return value
Value Description
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
NavigateTo
NavigateTo runs a new instance of MS Internet Explorer and opens a specified URL in its window.
Parameters
Parameter Description
Return value
Value Description
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.
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
View
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
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.
Specifiers Description
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.
ViewProps
The ViewProps method runs a new instance of MS Internet Explorer and opens a Services page for a
specified DocuShare item.
Parameters
Parameter Description
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.
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
Cookie
Access Read/Write
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
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.
Options
VB Options As Long
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
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
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/
4.2.3 Wizard
List of Wizard methods and properties.
Init
Options
Run
Init
VB Init(pServer As Server)
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.
Run
VB Run() As Long
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
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.
Options
VB Options As Long
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:
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
Methods Properties
ProtocolScheme
ProxyAddress
ProxyAuth
ReadOnly
SessionFlags
SHItemDescriptor
ShortcutStore
TypeIndex
UseProxy
UserHandle
UserName
UseWindowsAuth
Version
WIPFolder
WorkFolder
WWWAuth
WWWSecure
AuthenticateUser
VB AuthenticateUser() As Long
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
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.
• 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
BroadcastEvent
Parameters
lEvent—can be set to one of the following event flags.
SVRMAP_EVENT_REMOVE The server map for this Server object has been
removed from the server database.
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
Value Description
Remarks
This method is automatically called by Server.Logon.
CacheCredentials
VB CacheCredentials(() As Long
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
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.
Compare
Parameters
Parameter Description
Flag Description
Return value
Zero—The method was successful. A non-zero return occurs if the Server objects are dissimiliar.
CopyTo
The CopyTo method copies the properties from one Server object to another.
Parameters
pServer—the target Server object for copies.
Return value
Value Description
Remarks
The following Options flags control how CopyTo performs the copying:
See Options on page 4–66 for constants and to set the copy options.
CreateObject
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.
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.
EnsureWIPFolderExist
VB EnsureWIPFolderExists() As Long
Parameters
None
Return value
Value Description
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.
Load
VB Load() As Long
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
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.
Logoff
VB Logoff() As Long
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
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.
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.
Logon
VB Logon() As Long
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
Remarks
The following options can be used to control the logon dialog's behavior.
Option Description
Option Description
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
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.
Protect
VB Protect())As Long
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
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.
Save
VB Save() As Long
The Save method serializes the server map settings into an associated server database.
Parameters
None
Return value
Value Description
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.
Unprotect
VB Unprotect() As Long
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
Remarks
Unprotect always should be called if Protect has been called. Failure to do so may cause a concurrent
process to lock up.
UpdateSchemaCache
VB UpdateSchemaCache() as Long
UpdateSchemaCache retrieves schemata from a server and updates the schema cache maintained on the
client machine.
Return value
Value Description
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.
AuthDigest
VB AuthDigest as Long
The property contains a 32-bit digest of the authentication token. Uniqueness is not guaranteed.
AuthToken
VB AuthToken as String
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
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.
CheckinServiceManager
Access Read-only
Contains an object which manages file checkin services available to the server associated with this Server
object.
CustomProps
C++
Access Read-only
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:
CustomPropName
VB CustomPropName As String
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
Access Read/Write
Remarks
Refer to CustomPropName on page 4–55 to save and load a custom property.
DBAccessToken
VB DBAccessToken as 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
Access Read/Write
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/
Domain
VB Domain as String
Access Read/Write
ErrorDescription
VB ErrorDescription As String
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.
FolderHandle
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
Access Read/Write
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.
GuestAccess
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.
HostServer
VB HostServer As Long
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
Icon
Access Read-only
The Icon property obtains an icon picture associated with the Server object.
Parameters
Parameter Description
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.
Instanceld
VB InstanceId As Long
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.
IsLoggedOn
VB IsLoggedOn As Long
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
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.
IsSelected
VB IsSelected As Long
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:
LastError
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.
MapIndex
VB MapIndex As Integer
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
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.
Options
VB Options As Long
Access Read/Write
The Options property controls Server behavior for certain methods and properties.
Remarks
OwnerHwnd
VB OwnerHwnd As Long
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
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.
Password
VB Password As String
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
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
ProtocolScheme
VB ProtocolScheme As String
Access Read/Write
Remarks
Valid values are HTTP and HTTPS.
ProxyAddress
VB ProxyAddress As String
Access Read/Write
Remarks
The UseProxy property toggles usage of the proxy server specified by ProxyAddress.
ProxyAuth
VB ProxyAuth as Boolean
Access Read/Write
ReadOnly
VB ReadOnly As Long
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
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.
• MapIndex
• UseProxy
• WWWSecure
• WWWAuth
• IsLoggedOn
• ReadOnly
• LastError
• GuestAccess
An SDK application should use these properties to learn the current session status.
SHItemDescriptor
VB SHItemDescriptor as Variant
Access Read-only
ShortcutStore
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.
Use the following Store methods and properties to perform enumeration tasks.
The following Store methods and properties are not supported by ShortcutStore.
DBAccessToken Always 0.
LockCount Always 0.
SelectDialogOption Always 0.
TypeIndex
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
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.
UserHandle
VB UserHandle As Long
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
Access Read/Write.
Remarks
None
UseWindowsAuth
VB UseWindowsAuth as Long
Access Read/Write
Remarks
SessionFlags raises the SVRMAP_SESSFLAG_WINLOGON flag if UseWindowsAuth is True.
Version
VB Version As Long
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
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.
WorkFolder
VB WorkFolder As String
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
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
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.
4.2.5 CheckinServiceManager
List of CheckinServiceManager methods.
IsCheckinFormRequired
OpenUIService
OpenUIService
Opens a UI service which can be used to run a dialog for checking an item in DocuShare.
IsCheckinFormRequired
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.6 PropCollection
List of PropCollection methods and properties
Add NextItem
Close Next
Find NextPos
ID Remove
Length Reset
Load Save
Name
Add
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.
Close
VB Close() as long
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
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.
Load
VB Load()
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.
Next
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();
Remove
VB Remove(ID as string)
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
Return value
Non-zero if the method succeeds; zero, if no item exists in the collection.
Save
VB Save() as long
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").
ID
VB ID as string
Access Read/Write
Remarks
Server.CustomProps uses PropCollection.ID to locate a specified collection of custom properties.
Length
VB Length as long
Access Read-only
Name
VB Name as string
Access Read/Write
NextItem
VB NextItem as CustomProp
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.
NextPos
VB NextPos as long
Access Read-only
Contains the next enumeration position if another CustomProp object is available. If not, NextPos is zero.
4.2.7 CustomProp
List of CustomProp methods and properties
Attribute
Description
Flags
ID
Name
Value
Attribute
Access Read/Write
Parameters
Name—contains an attribute name.
Description
VB Description as string
Access Read/Write
Flags
VB Flags as long
Access Read/Write
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.
ID
VB ID as string
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
Access Read/Write
Value
VB Value as string
Access Read/Write
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
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
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
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
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
Attach
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
AttachGateway
Parameters
Parameter Description
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.
AttachParents
Parameters
pEnumDisp—a ItemEnum object that contains a list of valid parent handles.
Return value
Value Description
CancelTask
VB CancelTask() as Long
Parameters
Return value
Value Description
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.
Compare
Parameters
Parameter Description
IFlags Description
IFlags Description
Return value
Zero—ItemObjs were compared to have no differences for the criteria tested. A non-zero return signifies
an unequal comparison.
CopyTo
The CopyTo method copies the properties of one ItemObj to another ItemObj.
Parameters
Parameter Description
Return value
Value Description
CreateObject
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:
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.
DetachGateway
VB DetachGateway() as Object
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.
DSCopy
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
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.
• File
• Collection
• Calendar
• BulletinBoard
• 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.
• 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.
DSCreate
VB DSCreate() As Long
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_DOCUMENT Document
DSXITEMTYPE_CALENDAR Calender
Return value
Value Description
Value Description
Remarks
Depending on the type of current ItemObj object, the properties that are specified may differ. The table
below shows the dependency.
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.
DSDelete
VB DSDelete() As Long
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
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.
• Collection
• File
• Calendar
• BulletinBoard
• URL
• SavedQuery
DSDownload
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
Return value
Value Description
Remarks
DSDownload supports the following item types:
• File
• Version
• Collection
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.
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.
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
DSEdit
VB DSEdit() As Long
The DSEdit method downloads, locks (optional), and opens a file for editing.
Parameters
None
Return value
Value Description
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.
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.
DSFind
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.
Return value
Value Description
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.
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.
DSLoadChildren
VB DSLoadChildren() As Long
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
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.
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.
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.
• 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.
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:
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.
DSLoadProps
VB DSLoadProps() As Long
The DSLoadProps method retrieves the properties for the current ItemObj.
Parameters
None
Return value
Value Description
Remarks
DSLoadProps supports the following ItemObj types:
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.
For a Server ItemObj, the DSLoadProps method updates the following properties:
DSLock
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
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.
DSMove
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
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.
DSSaveProps
VB DSSaveProps() As Long
The DSSaveProps method saves the ItemObj properties to the object stored within the DocuShare server.
Parameters
None
Return value
Value Description
Remarks
This method is called to apply property changes to the ItemObj object representation of the actual object
stored on a DocuShare server.
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.
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.
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
DSSelect
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
IFlag Description
Return value
Value Description
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.
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)
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.
DSUpload
VB DSUpload() As Long
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
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
• 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.
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.
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
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.
GetPropStruct
VB GetPropStruct() as Variant
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);
GetStateInfo
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
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
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.
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
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.
LoadDefaultProps
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
Return value
DSAXES_SUCCESS—default values were successfully loaded.
OpenGateway
Parameters
OpenGateway opens a gateway to DocuShare.
Return value
A DSGateway.GatewayHandler object.
PreloadCustomProps
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.
SaveDefaultProps
SaveDefaultProps saves property values that exist in an ItemObj as default property values in a temporary
file on the client machine.
Parameters
Parameter Description
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.
SetPropStruct
Parameters
pvStruct—a variant structure that stores the properties to be set.
Return value
Value Description
UpdateLinks
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.
EnumObjects
The EnumObject method returns an ItemEnum object that enumerates selected parents or children of the
current ItemObj.
Parameters
IFlag Description
Return value
Object/LPDISPATCH—the return value is a VB Object or a C/C++ dispatch interface to a EnumObj.
EnumPresets
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
EnumProps
The following script retrieves properties from DocuShare and use EnumProps to walk through all
properties defined for the File object.
Parameters
Flags—chooses one or more properties categories to enumerate.
Parameter Description
DSPROPF_CLIENTPROPS =_
DSPROPF_CLIENTCOREPROPS or _
DSPROPF_CLIENTCUSTOMPROPS
Parameter Description
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
SchemaEnumerator
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.
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.
DSErrorCode
VB DSErrorCode As Long
The DSErrorCode property returns an error code from the DS server or gateway.
Remarks
Common errors are listed below.
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
500 HTTP_INTERNALSERVERERROR
501 HTTP_NOT_IMPLEMENTED
502 HTTP_BADGATEWAY
503 HTTP_MAXCONNECTS
504 HTTP_GATEWAYTIMEOUT
WSAEINTR
WSAEBADF
WSAEACCES
WSAEFAULT
WSAEINVAL
WSAEMFILE
WSAEWOULDBLOCK
WSAEINPROGRESS
WSAEALREADY
WSAENOTSOCK
WSAEDESTADDRREQ
WSAEMSGSIZE
WSAEPROTOTYPE
WSAENOPROTOOPT
WSAEPROTONOSUPPORT
WSAESOCKTNOSUPPORT
WSAEOPNOTSUPP
WSAEPFNOSUPPORT
WSAEAFNOSUPPORT
WSAEADDRINUSE
WSAEADDRNOTAVAIL
WSAENETDOWN
WSAENETUNREACH
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
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
DSGatewayMode
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
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.
Reload
VB Reload As Boolean
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
AccessControlGrants
VB AccessControlGrants as 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.
AlternateRendition
Access Read/Write
Author
VB Author As String
Access Read/Write
The Author property accesses the author of a document stored in a DocuShare server.
AutoDelete
VB AutoDelete As Boolean
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.
BackgroundImage
VB BackgroundImage As String
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
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
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.
ClientProp
VB ClientProp as Variant
Access Read/Write
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.
Comment
VB Comment As String
Access Read/Write
CompoundContainer
Access Read/Write
ContainerItemObject
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.
Contents
VB Contents as 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.
CorePropIds
VB CorePropIds as Long
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.
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.
CustomProp
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
Remarks
Refer to Working with properties on page 2–46 to utilize CustomProp.
Data
VB Data As Variant
Access Read/Write
Remarks
This variant provides the developer with a location to store and retrieve information for this object.
Description
VB Description As String
Access Read/Write
ExcludedCoreProps
VB ExcludedCoreProps As Long
Access Read/Write
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.
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 *
NOTE: The properties marked with asterisks (*) can be queried and therefore can be excluded using
ExcludedCoreProps in conjunction with DSLoadProps but not DSSaveProps.
ExcludedProps
VB ExcludedProps As Long
Access Read/Write
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.
DSAXES_PROPID_FILE_MIMETYPE MimeType
DSAXES_PROPID_FILE_AUTHOR Author
DSAXES_PROPID_FILE_MAXVERSION MaxVersions *
DSAXES_PRODID_FILE_SIZE Length *
DSAXES_PROPID_FILE_ABSTRACT Abstract *
DSAXES_PROPID_COLL_SIZE Length *
NOTE: The properties marked with asterisks(*) can be queried and therefore can be excluded using
ExcludedProps in conjunction with DSLoadProps, but not DSSaveProps.
Filename
VB Filename as String
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
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
Access Read/Write
The property HandleNum is the numeric handle for the current ItemObj.
HighestVersionUsed
VB HighestVersionUsed as Long
Remarks
HighestVersionUsed corresponds directly to the DocuShare <highest_version_used> property. The
property is supported on DocuShare Release 3.0 or higher.
Icon
The Icon property is used to retrieve the icon picture for an object.
Parameters
Parameter Description
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.
IsContainer
VB IsContainer as Boolean
IsContainer determines if the ItemObj represents a collection, calendar, bulletin board, or other container
item.
IsCustomType
VB IsCustomType as Boolean
IsCustomType determines if the ItemObj represents an item of a custom DocuShare object class.
IsLocked
VB IsLocked As Boolean
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.
IsPrivate
VB IsPrivate as Boolean
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.
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.
IsReadOnly
VB IsReadOnly As Boolean
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
Access Read/Write
The Keywords property accesses the keyword list associated with the current ItemObj.
Length
VB Length As Long
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
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:
LockedBy
VB LockedBy as String
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
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
Access Read/Write
MaxVersions
VB MaxVersions As Long
Access Read/Write
The MaxVersions property accesses the maximum number of versions that a document object can contain
in a DocuShare server.
MimeType
VB MimeType As String
Access Read/Write
The MimeType property sets the mime type for a document object stored on a DocuShare server.
ModifiedBy
VB ModifiedBy as String
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
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.
Name
VB Name As String
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.
ObjectTypeNum
VB
C++ Integer
Access Read/Write
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.
Options
VB Options as 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.
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.
• 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
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
Owner
VB Owner As String
Access Read/Write
OwnerNum
VB OwnerNum As Long
Access Read/Write
The OwnerNum property accesses the current ItemObj owner’s numeric ID.
Parent
VB Parent As Long
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.
ParentCount
VB ParentCount As Long
The ParentCount property returns the number of parents for the current ItemObj.
ParentHandle
VB ParentHandle as String
Access Read/Write
ParentHandle contains the DocuShare handle for the primary parent object.
ParentHandleNum
VB ParentHandleNum as Long
Access Read/Write
ParentItemObject
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.
ParentType
VB ParentType as String
Access Read/Write
ParentType contains the type identifier for the primary parent object.
ParentTypeNum
VB ParentTypeNum as Long
Access Read/Write
ParentTypeNum contains the type number for the primary parent object.
PreferredRendition
Access Read/Write
Picture
VB Picture as Object
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.
Remarks
The image types for which IPicture objects can be created are:
• image/jpeg
• image/gif
• image/bmp
Prop
Access Read/Write
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.
!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.
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
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.
ReferrerItemObject
Access Read/Write
RequiredPropsAreSet
VB RequiredPropsAreSet as Boolean
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.
Server
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
Access Read/Write
The SortOrder property sets the sort order for a collection object.
Summary
VB Summary As String
Access Read/Write
TaskStatus
VB TaskStatus as Long
TaskStatus contains a status code from an asynchronous task in progress. Possible status codes.
The following script starts a file upload asynchronously and watches TaskStatus until it is set to a code
different from DSAXES_INPROG.
Thumbnail
VB Thumbnail As StdPicture
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
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
Access Read/Write
The TimeCreated property accesses the creation time of the current ItemObj.
TimeModified
VB TimeModified As Date
Access Read/Write
The TimeModified property returns the time the current ItemObj was modified.
Title
VB Title As String
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
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.
TypeId
VB TypeId as String
Access Read/Write
TypeId contains a type identifier that determines the class of the DocuShare object associated with this
ItemObj object.
TypeIndex
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.
TypeNum
VB TypeNum As Long
Access Read/Write
The TypeNum property sets or retrieves the type of object for the current ItemObj.
URL
VB URL As String
Access Read/Write
The URL property accesses the http URL for the current ItemObj.
User
VB User As String
Access Read/Write
The User property accesses the last user to modify the current ItemObj.
UserNum
VB UserNum As Long
Access Read/Write
The UserNum property accesses the numeric ID of the last user to modify the current ItemObj.
ValidatedFileHandle
VB ValidatedFileHandle As String
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.
VersionNum
VB VersionNum As Long
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.
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
Attach
Parameters
pEnumDisp—an ItemEnum object. The ItemEnum object needs to be valid.
Return value
Value Description
Attach2
Parameters
Parameter Description
Flag Description
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.
Clear
VB Clear() as Long
Parameters
None
Return value
DSAXES_SUCCESS—the object cleared successfully.
CopyTo
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
GetLengthOf
Parameters
Parameter Description
Return value
The quantity of numbered sub-items belonging to the ItemObj passed to the function.
GetNode
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.
Load
Parameters
Parameter Description
Flags Description
DSCONTF_CHILDREN Load all the children items from the source file.
Return value
Value Description
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
The NewItem method creates a blank item and adds it to the list.
RemoveItem
Parameters
pItem—the pItemObj to be deleted.
Return value
Value Description
Reset
VB Reset() As Long
Parameters
None
Return value
Value Description
Remarks
Always call this method before calling Next.
Sort
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
Flags Description
Return value
Value Description
Remarks
This script retrieves a collection and uses the Sort method to sort the item list and print the sorted list.
Flags
VB Flags as Long
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
The Length property returns the number for the ItemObj object held by the current ItemEnum object.
NextItem
VB NextItem as ItemObj
NextPos
VB NextPos As Long
The NextPos property obtains and returns the position of the next item.
Remarks
NextPos returns -1 if there are no more items.
5.2.3 EnumSchema
List of EnumSchema methods and properties
Length NewItem
Load Reset
NextItem RemoveItem
NextPos
NewItem
Reset
VB Reset() as Long
RemoveItem
Load
Length
VB Length as Long
NextItem
NextPos
VB NextPos as Long
Contains the position for the next item (0, if there are no more items).
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
ResetMenu
VB ResetMenu() as Long
NewMenuItem
RemoveMenuItem
ClearMenu
VB ClearMenu as Long
Makes the destination object into an identical copy of the source object.
CopyTo
Makes the destination object into an identical copy of the source object.
Name
VB Name as String
Access Read/Write
Label
VB Label as String
Access Read/Write
TypeNum
VB TypeNum as Long
Access Read/Write
HelpText
VB HelpText as String
Access Read/Write
IsSystem
VB IsSystem as Boolean
Access Read/Write
IsRequired
VB IsRequired as Boolean
Access Read/Write
IsReadOnly
VB IsReadOnly as Boolean
Access Read/Write
DefaultValue
VB DefaultValue as Variant
Access Read/Write
MinimumValue
VB MinimumValue as Variant
Access Read/Write
MaximumValue
VB MaximumValue as Variant
Access Read/Write
MenuLength
VB MenuLength as Long
NextMenuItem
VB MenuLength as Long
NextMenuPos
VB NextMenuPos as Long
TypeStr
VB TypeStr as String
Access Read/Write
PropsEnumerator
IsMultivalued
VB IsMultivalued as Boolean
Access Read/Write
ItemTypeNum
VB ItemTypeNum as Long
Access Read/Write
Server
Access Read/Write
ItemObject
Contains an ItemObj for the DocuShare object class associated with this schema.
5.2.5 EnumSchemaProps
List of EnumSchemaProps methods and properties.
Length NextPos
NextItem Reset
NextItem
Reset
VB Reset as Long
Next
Length
VB Length as Long
NextItem
NextPos
VB NextPos as Long
5.2.6 SchemaProp
List of SchemaItemProp properties.
Properties
Name
TypeNum
Value
Name
VB Name as String
TypeNum
VB TypeNum as Long
Value
VB Value as Variant
5.2.7 EnumItemProps
List of EnumItemProps methods and properties
Clear NextPos
Item NextPos
Length Reset
NextPos RemoveItem
NextItem
Clear
VB Clear() as long
NewItem
VB NewItem() as ItemProp
Next
RemoveItem
Reset
VB Reset() as Long
Item
Parameters
Index—an integer specifying an enumeration index.
Length
VB Length as Long
Contains the enumeration length that is the number of ItemProp objects belonging to the enumerator.
NextPos
VB NextPos as Long
Contains the next enumeration position if another ItemProp object is available. If not, NextPos contains a
zero.
NextItem
Contains the next ItemProp object if one is available. If not, NextItem contains a NULL object.
Remarks
Checks the value of NextPos before referencing NextItem. NextPos contains a non-zero if NextItem
contains a valid ItemProp object.
5.2.8 ItemProp
List of ItemProp methods and properties
CreateControl Name
ID Scope
EnumPropValues Type
ID Value
ItemSchema XMLName
Label
CreateControl
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
EnumValues
Parameters
Flags—optional, not currently used; should be set to zero.
ID
VB ID as Long
Access Read/Write
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
Type
VB Type as 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
Access Read/Write
XMLName
VB XMLName as String
XMLName contains the XML element name of a DocuShare property. If no XML name is defined for the
property, XMLName is empty.
Label
VB Label as String
Access Read/Write
Value
VB Value as 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.2.9 EnumPropValues
List of EnumPropsValue methods and properties.
Clear NextPos
Item NewItem
Length RemoveItem
NextItem Reset
NextItem
Clear
VB Clear() as long
Next
NewItem
VB NewItem() as ItemProp
RemoveItem
Reset
VB Reset() as Long
Item
Parameters
Index—an integer specifying an enumeration index.
Length
VB Length as Long
Length contains the enumeration length that is the number of PropValue objects belonging to the
enumerator.
NextItem
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.
NextPos
VB NextPos as Long
NextPos contains the next enumeration position if another PropValue object is available. If not, NextPos
contains a zero.
5.2.10 PropValue
List of PropValue methods and properties
Index
Value
XMLValue
Index
VB Index as Long
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
Access Read/Write
XMLValue
VB XMLValue as String
Access Read/Write
5.2.11 ErrorReportObj
List of ErrorReportObj methods and properties
AttemptedCommand Init
ClientRequest LogFile
DSAccessData Report
ErrorCode ServerResponse
ErrorDescription SetErrorInfo
ErrorDisplayType ShowDialog
ErrorPhrase Silent
GatewaySettings StatusCode
Init
Initializes the ErrorReportObj with gateway objects. The method keeps copies of the objects.
Return value
None.
Report
VB Report()
Runs a simple dialog to display error information if the property, Silent, is set to False.
SetErrorInfo
ShowDialog
Parameters
ShowDetails can be set to one of the following:
AttemptedCommand
VB AttemptedCommand as String
Access Read/Write
ClientRequest
ClientRequest contains a client request object that was in use when an error was encountered.
DSAccessData
DSAccessData contains a client access data object that was in use when an error was encountered.
ErrorCode
VB ErrorCode as Long
Access Read/Write
ErrorDescription
VB ErrorDescription as String
Access Read/Write
ErrorDisplayType
VB ErrorDisplayType as DSX_ERRDISP
Flag Description
ErrorPhrase
VB ErrorPhrase as String
Access Read/Write
GatewaySettings
GatewaySettings contains a gateway settings object that was in use when an error was encountered.
LogFile
VB LogFile as String
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.
ServerResponse
ServerResponse contains a server response object that was in use when an error was encountered.
Silent
VB Silent as Boolean
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
Access Read/Write
StatusCode contains a DSAXES_SUCCESS or DSAXES_E status code from a DocuShare command that
has failed.
5.2.12 NameConflictResolver
List of NameConflictResolver methods and properties
AutoComment ReplacedItemHandle
CollectionObject ResolveLocalName
ErrorDisplayType ResolveRemoteName
FixedComment ResolveRemoteName2
ForceRename RunCommentDialog
ForceReplace VersionComment
Rename
Rename
Parameters
Parameter Description
Return value
Value Description
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.
ResolveLocalName
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
Return value
One of the DSX_NAMECONFRES codes.
Value Description
Value Description
ResolveRemoteName
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
Return value
One of the DSX_NAMECONFRES conflict resolution codes below.
Value Description
Value Description
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.
ResolveRemoteName2
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
Return value
One of the DSX_NAMECONFRES codes.
Value Description
Value Description
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.
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.
RunCommentDialog
Parameters
Parameter Description
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.
AutoComment
VB AutoComment as Boolean
Access Read/Write
CollectionObject
Access Read/Write
ErrorDisplayType
VB ErrorDisplayType as DSX_ERRDISP
FixedComment
VB FixedComment as String
Access Read/Write
ForceRename
VB ForceRename as Variant
Access Read/Write
ForceReplace
VB ForceReplace as Variant
Access Read/Write
ReplacedItemHandle
VB ReplacedItemHandle as String
ReplacedItemHandle contains the DocuShare object handle of an item subject to a replace action by
ResolveRemoteName.
VersionComment
VB VersionComment as String
5.2.13 StatusObj
List of StatusObj 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
HideDialog
VB HideDialog()
HideProgress
VB HideProgress()
HideProgress hides the progress bar from the status dialog box.
ShowDialog
VB ShowDialog()
ShowProgress
VB ShowProgress()
Subscribe
Subscribes to notification from the system tray for the associated icon.
Parameters
Parameter Description
Return value
None
Remarks
An application must implement the following event handling functions:
CanCancel
VB CanCancel as Boolean
Access Read/Write
CancelCode
VB CancelCode as Long
Access Read/Write
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.
CanReportNetworkStatus
VB CanReportNetworkStatus as Boolean
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
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
Access Read/Write
GatewayEventWindow
VB GatewayEventWindow as OLE_HANDLE
IconPath
VB IconPath as String
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
Access Read/Write
ParentWindow
VB ParentWindow as OLE_HANDLE
Progress
VB Progress as Long
Access Read/Write
SubLowerLimit
VB SubLowerLimit as Long
Access Read/Write
SubLowerLimit sets the secondary lower limit for the progress bar.
SubText
VB SubText as String
Access Read/Write
SubUpperLimit
VB SubUpperLimit as Long
Access Read/Write
SubUpperLimit sets the secondary upper limit for the progress bar.
Text
VB Text as String
Access Read/Write
Title
VB Title as String
Access Read/Write
Title contains a title to be shown on the caption bar of the dialog box.
TopMostDialog
VB TopMostDialog as Boolean
Access Read/Write
UpperLimit
VB UpperLimit as Long
Access Read/Write
UpperLimit sets the primary upper limit for the progress bar.
Visible
VB Visible as Boolean
Access Read/Write
WindowHandle
VB WindowHandle as OLE_HANDLE
5.2.14 CommentUI
5.2.14.1 CommentUI methods
This section contains the CommentUI method definitions.
RunDialog
Parameters
ItemObj—contains the Comment property of an ItemObj object that is displayed and editable by a user.
Remarks
None
WindowHandle
VB WindowHandle as OLE_HANDLE
Access Read/Write
WindowHandle contains the window handle for the window that owns the input dialog window.
5.2.15 RenameUI
5.2.15.1 Rename methods
This section contains the RenameUI method definitions.
RunDialog
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:
WindowHandle
VB WindowHandle as OLE_HANDLE
Access Read/Write
WindowHandle contains the window handle for the window that owns the rename dialog window.
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.
AddItemObject
Loads the enumerator. The presets are obtained for the authenticated DocuShare user associated with the
IItemObj parameter.
Function Next
Function Reset
Property Length
Property nextItem
Property NextPos
DefaultPreset
VB DefaultPreset As IPreset
Access Read/Write
UsePersonalPreset
VB UsePersonalPreset As Boolean
Access Read/Write
UsePersonalPreset specifies the default value of the use personal preset setting described above.
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.
DisplayName
DSOwnerHandle
Property Name
VB Property Name As String
RecordType
fileObj.Name = "abc123.htm"
fileObj.CompoundContainer.Name = "c:\doc\abc123"
fileObj.Options = fileObj.Options or ITEMOBJ_OPTION_UPDATELINKS
fileObj.DSUpload
• PropObj. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6–2
• DsPropsObj. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6–4
• PermObj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6–7
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.
Property Description
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.
• 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.
Method Description
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.
Property Description
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.
• 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.
Method Description
Property Description
• Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–2
• Script Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–4
• DSAxess console enhancements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–5
• Script Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–8
• Console commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–14
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.
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:
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.
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.
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.
• 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.
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
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.
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.
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.
• CD
• Copy
• Delete
• Edit
• Get
• GetProps
• History
• Lock
• Move
• Open
• Rename
• Replicate
• SetProps
7.4.1 Login
The following examples demonstrate the methods and properties that can be utilized to set or select a
server for login.
Command notations
FilePath—specifies the pathname of a file in the local machine.
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.
CD
CD [CollHandle]
Changes the current directory (collection) to the collection specified by CollHandle in DocuShare.
• 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:
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).
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.
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.
• 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
Delete
Delete <ObjectHandle/name=FileName/name=FileMask>
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:
FILE1: Document1
FILE2: Document2
To delete Document1, enter:
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.
• *.*—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
DeleteUser
DeleteUser <User-n>; or DeleteUser <username>
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.
LOGON admin
DELETEUSER -q joecool
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 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.
Disown
Disown [ObjectHandle]
The Disown command removes a DocuShare object of ObjectHandle from a parent collection.
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.
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.
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.
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.
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.
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.
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:
If the handle parameter specifies a collection, Get downloads the file versions only. It does not retrieve the
file properties.
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.
Enhancements
Example 1: Downloading RDO
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.
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.
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.
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.
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"
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
User parameters
Parameter Description
Socket parameters
Parameter Description
Transaction parameters
Parameter Description
Server information
Transfer mode
GetProps
GetProps <ObjectHandle>
The GetProps command finds properties for a DocuShare object (ObjectHandle). Only the standard
properties are queried.
GetProps sets DSHandle to the handle number for the parent (collection) of the queried object.
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:
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.
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 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.
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.
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
...
GETSCHEMA -link
Goto
The Goto command passes control to a subsequent line containing the specified label prefixed with a
colon, ':'.
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.
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
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 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.
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.
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:
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.
CD %FileCollection%
Put %FilePath% title=%FileTitle%
NOTE: The variable identifier is case sensitive. %FilePath% is valid, while %filepath% is not.
The following script variables are pre-defined and automatically updated when certain commands are
executed.
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%.
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.
ListRenditions
ListRenditions <Version-x>; or ListRenditions <File-n/[m]>
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
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.
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.
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.
Logout
The Logout command logs out from the current server session and clears the internally cached password.
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.
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.
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 sets script variable DSHandle to the handle number of the destination collection.
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.
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
Open
The Open command opens a DocuShare object in an Internet Explorer window.
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.
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:
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.
When uploading multiple files, such as files that match a file name pattern, the -quiet option can be used to
disable the confirmation prompt.
Folder abc123
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).
[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
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.
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.
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
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.
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.
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 sets script variable DSHandle to the handle number for the renamed object.
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).
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.
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.
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:
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
Search
Search <"term1=value1" ...> [output=FilePath]
The Search command searches DocuShare objects that meet the criteria given by a combination of the
following terms:
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
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
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.
sortby=key-order1,key-order2,key-order3,...
• 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.
CD Collection-42
SEARCH -xdb context=AR
To save the XML query results in a file, enter:
Setparam
Setparam <name> <value>
The Setparam command assigns a new value to the named parameter. The modified names and their
valid values are:
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.
The SetProps command can be used to modify properties of a file version that is specified by a file handle
and a version number.
If you know the Version handle of a version object, use the version handle.
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
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.
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.
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 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.
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.
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.
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.
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.
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:
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.
For a web server protected by basic authentication, this command may be used. Again, the DocuShare
server enables auto login.
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.