zimbra_wsdl 0.0.2

data/doc/soap-waitset.txt

@@ -0,0 +1,347 @@
+WaitSet: scalable mechanism for listening for changes to one or more accounts
+--------------------------------------------------------------------------------
+
+Non-admin versions in the 'zimbraMail' Namespace:
+-------------------------------------------------
+<CreateWaitSetRequest>
+<CreateWaitSetResponse>
+<WaitSetRequest>
+<WaitSetResponse>
+<DestroyWaitSet>
+<DestroyWaitSetResponse>
+
+
+Admin versions in the 'zimbraAdmin' Namespace:
+-------------------------------------------------
+<AdminCreateWaitSetRequest>
+<AdminCreateWaitSetResponse>
+<AdminWaitSetRequest>
+<AdminWaitSetResponse>
+<AdminDestroyWaitSet>
+<AdminDestroyWaitSetResponse>
+<QueryWaitSetRequest>
+<QueryWaitSetResponse>
+
+note that the admin versions of the APIs are identical in any way,
+except that they can be used to wait on non-owner accounts and can be
+used to wait on "all accounts".
+
+
+*************************************
+
+
+
+INTEREST_TYPES: comma-separated list.  Currently:
+   c: contacts
+   m: msgs (and subclasses)
+   a: appointments
+   all: all types (equiv to "c,m,a")
+
+
+*************************************
+CreateWaitSet/AdminCreateWaitSet: must be called once to initialize
+the WaitSet and to set its "default interest types"
+
+- Non-Admin requests may only specify their own account ID.
+
+- Non-Admin accounts are restricted to a max of 5 (default,
+  overridable via LocalConfig) WaitSets.  Creating more than the max
+  will cause the least-recently-used WaitSet to be destroyed
+
+- If "allAccounts" is set, then all mailboxes on the system will be
+listened to, including any mailboxes which are created on the system
+while the WaitSet is in existence.  Additionally: 
+      -- <add>, <remove> and <update> tags are IGNORED
+      -- The requesting authtoken must be an admin token
+
+- AllAccounts WaitSets are *semi-persistent*, that is, even if the
+server restarts, it is OK to call <WaitSetRequest> passing in your
+previous sequence number.  The server will attempt to resynchronize
+the waitset using the sequence number you provide (the server's
+ability to do this is limited by the RedoLogs that are available)
+================
+<[Admin]CreateWaitSetRequest defTypes="DEFAULT INTEREST_TYPES" [allAccounts=1]>
+  [ <add>
+      [<a id="ACCTID" [token="lastKnownSyncToken"] [types="if_not_default"]/>]+
+    </add> ]
+</[Admin]CreateWaitSetRequest>
+
+<[Admin]CreateWaitSetResponse waitSet="setId" defTypes="types" seq="0">
+  [ <error id="AccountId" t="ERROR_CODE"/>]*
+</[Admin]CreateWaitSetResponse>
+
+
+ERROR_CODEs:
+        // RUNTIME errors:
+        MAILBOX_DELETED: the mailbox has been deleted, it is no longer in the waitset
+
+        // ADD errors:
+        ALREADY_IN_SET_DURING_ADD: the account was not added, it was already there
+        ERROR_LOADING_MAILBOX: exception while trying to fetch the mailbox, not added
+        MAINTENANCE_MODE: mailbox currently in Maintenance Mode.  Try to add it again later.
+        NO_SUCH_ACCOUNT: unknown account, not added
+        WRONG_HOST_FOR_ACCOUNT: that account's mailbox is on another host.  Add it there.
+
+        // REMOVE/UPDATE errors
+        NOT_IN_SET_DURING_REMOVE
+        NOT_IN_SET_DURING_UPDATE
+        
+
+***IMPORTANT: Note that the seq number is **NOT** guaranteed to be an
+integer.  Clients MUST treat this value as an opaque string.***
+
+
+
+
+************************************
+WaitSetRequest/AdminWaitSetRequest: optionally modifies the wait set
+and checks for any notifications.  If block=1 and there are no
+notificatins, then this API will BLOCK until there is data.
+
+Client should always set 'seq' to be the highest known value it has
+received from the server.  The server will use this information to
+retransmit lost data.
+
+If the client sends a last known sync token then the notification is
+calculated by comparing the accounts current token with the client's
+last known.
+
+If the client does not send a last known sync token, then notification
+is based on change since last Wait (or change since <add> if this
+is the first time Wait has been called with the account)
+
+The client may specifiy a custom timeout-length for their request if
+they know something about the particular underlying network.  The
+server may or may not honor this request (depending on server
+configured max/min values).  The server will allow a wider range of
+requested timeouts from admin auth tokens. See LocalConfig values:
+zimbra_waitset_default_request_timeout,
+zimbra_waitset_min_request_timeout, 
+zimbra_waitset_max_request_timeout,
+zimbra_admin_waitset_default_request_timeout,
+zimbra_admin_waitset_min_request_timeout, and
+zimbra_admin_waitset_max_request_timeout
+
+
+================
+<[Admin]WaitSetRequest waitSet="setId" defTypes="DEFAULT INTEREST TYPES"
+                seq="highestSeqKnown" [block="1"] [timeout="timeout"]>
+  [ <add>
+      [<a id="ACCTID" [token="lastKnownSyncToken"] [types]/>]+
+    </add> ]
+  [ <update>
+      [<a id="ACCTID" [token="lastKnownSyncToken"] [types]/>]+
+    </update> ]  
+  [ <remove>
+      [<a id="ACCTID"/>]+
+    </remove> ]  
+</[Admin]WaitSetRequest>
+
+<[Admin]WaitSetResponse waitSet="setId" [seq="seqNo" OR canceled="1"]>
+  [ <n id="ACCTID"/>]*
+  [ <error id="AccountId" t="ERROR_CODE"/>]*
+</[Admin]WaitSetResponse>
+
+If the specified wait set does not exist, the server will throw an
+admin.NO_SUCH_WAITSET exception.
+
+NOTE: an empty response to a blocking request *is* possible: it would
+happen if the server timed-out the waiting.  The server does this
+occasionally just so that requests don't get "stuck".  The client
+should re-submit the original request if this happens.
+
+If a second WaitMultiple request arrives at the server while one is
+already waiting, the first request will be immediately completed and
+will return with the "canceled" flag set.
+
+ERROR_CODEs:
+        // RUNTIME errors:
+        MAILBOX_DELETED: the mailbox has been deleted, it is no longer in the waitset
+
+        // ADD errors:
+        ALREADY_IN_SET_DURING_ADD: the account was not added, it was already there
+        ERROR_LOADING_MAILBOX: exception while trying to fetch the mailbox, not added
+        MAINTENANCE_MODE: mailbox currently in Maintenance Mode.  Try to add it again later.
+        NO_SUCH_ACCOUNT: unknown account, not added
+        WRONG_HOST_FOR_ACCOUNT: that account's mailbox is on another host.  Add it there.
+
+        // REMOVE/UPDATE errors
+        NOT_IN_SET_DURING_REMOVE
+        NOT_IN_SET_DURING_UPDATE
+
+
+
+
+*************************************
+DestroyWaitSet/AdminDestroyWaitSet: Use this to close out the wait
+set.  Note that the server will automatically time out a wait set if
+there is no reference to it for (default of) 20 minutes.
+*************************************
+<[Admin]DestroyWaitSetRequest waitSet="setId"/>
+
+<[Admin]DestroyWaitSetResponse waitSet="setId"/>
+
+
+
+
+**********************************************************************
+There are three basic use cases for WaitSets:
+**********************************************************************
+1) wait on a single account:
+<CreateWaitSetRequest defTypes="TYPES"/>
+   <add>
+      <a id="ACCTID"/>
+   </add>
+</CreateWaitSetRequest>
+
+<WaitSetsRequest waitSet="id" seq="seqno">
+   <update>
+      <a id="ACCTID" token="lastKnownSyncToken"/>
+   </update>
+</WaitSetRequest>
+
+<DestroyWaitSetRequest waitSet="id"/>
+
+
+2) Wait on many accounts (admin-only -- Remember to use the
+   zimbraAdmin namespace):
+<AdminCreateWaitSetRequest defTypes="TYPES"/>
+   <add>
+      <a id="ACCTID" [token="lastKnownSyncToken"]/>
+      <a id="ACCTID" [token="lastKnownSyncToken"]/>
+   </add>
+</AdminCreateWaitSetRequest>
+
+<AdminWaitSetRequest defTypes="TYPES" waitSet="id" seq="seqno">
+   <update>
+      <a id="ACCTID" [token="lastKnownSyncToken"]/>
+   </update>
+   <remove>
+      <a id="ACCTID"/>
+   </update>
+   <add>
+      <a id="ACCTID" [token="lastKnownSyncToken"]/>
+   </update>
+</AdminWaitSetRequest>
+
+<AdminDestroyWaitSetRequest waitSet="id"/>
+
+
+3) Wait on ALL accounts (admin-only):
+<AdminCreateWaitSetRequest defTypes="TYPES" allAccounts="1"/>
+
+<AdminWaitSetRequest waitSet="id" seq="seqno" defTypes="TYPES"/>
+...
+// SERVER RESTARTS!
+...
+<AdminWaitSetRequest waitSet="id" seq="seqno" defTypes="TYPES"/> // server will re-sync using RedoLogs
+
+<AdminDestroyWaitSetRequest waitSet="id"/>
+
+
+
+
+**********************************************************************
+A Detailed Example:
+**********************************************************************
+<AdminCreateWaitSetRequest defTypes="c">
+  <add>
+    <a id="a1"/>
+  </add>  
+</AdminCreateWaitSetRequest>
+<!-- a1 receives a contact update -->
+<AdminCreateWaitSetResponse waitSet="foo" defTypes="c" seq="0"/>
+
+<!--client syncs to a1 state AFTER added to WaitSet (not using sync token) -->
+<!-- a3 receives a contact update (token goes to 100)-->
+<!--client syncs to a3 BEFORE adding to WaitSet (client has token 100) -->
+
+<AdminWaitSetRequest waitSet="foo" seq="0" block="1">
+  <add>
+    <a id="a3" token="100"/>
+  </add>
+</AdminWaitSetRequest>
+<!-- Will return *immediately* b/c a1 has changed since the <add> -->
+<AdminWaitSetResponse waitSet="foo" seq="1">
+  <n id="a1"/>
+</AdminWaitSetResponse>
+
+<!-- At this point, client *must* sync with a1, even though the a1 update might have
+     happened before we synched with a1 there is no way to know.  a3 is not notified
+     and does not have to sync, because it is using sync tokens.  -->
+
+<AdminWaitSetRequest waitSet="foo" seq="1" block="1">
+  <add>
+    <a id="a2"/>
+  </add>
+</AdminWaitSetRequest>
+<!-- the client must sync with a2 state AFTER setting a2 wait, however because
+     block="1" the wait will not return until some account has new data: therefore
+     the client MUST sync a2 using another thread here.  The client cannot sync
+     before doing the <add> because of race conditions.  If the client is not
+     multi-threaded, then it should issue the <add> as block="0" in this case -->
+<!-- ...BLOCKS until... -->
+<!-- a3 receives a contact update (sync token goes to 107) -->
+<AdminWaitSetResponse waitSet="foo" seq="2">
+  <n id="a3"/>
+</AdminWaitSetResponse>
+
+<!-- client syncs to a3 -->
+
+<AdminWaitSetRequest waitSet="foo" seq="2" block="1">
+  <update>
+    <a id="a3" token="107"/>
+  </update>  
+</AdminWaitSetRequest>
+  
+<!-- Client is up to date, server  blocks until there is new data 
+     on a1,a2 or a3 -->
+  
+
+
+*************************************
+QueryWaitSet
+   This API dumps the internal state of all active waitsets.  It is
+   intended for debugging use only and should not be used for
+   production uses.  This API is not guaranteed to be stable between
+   releases in any way and might be removed without warning.
+*************************************
+
+<QueryWaitSetRequest waitset="WAITSETID">
+
+<QueryWaitSetResponse>
+
+SomeAccountsWaitSet:
+----------------------
+<QueryWaitSetResponse id="WAITSETID"
+                      defTypes="DEFAULT_TYPES"
+                      owner="WAITSET_OWNER_ACCOUNT_ID"
+                      ld="LAST_ACCESS_DATE"                      
+                      cbSeqNo="SEQNO_OF_CB"
+                      currentSeqNo="CURRENT_SEQUENCE_NUMBER">
+  [<ready accounts="comma-separated list of account IDs"/>]?
+  [<session types="TYPES" account="ACCOUNT_ID">
+     [
+     <WaitSetSession interestMask="BITMASK" highestChangeId="MBOX_CHANGE_ID"
+                     lastAccessTime="LAST_ACCESS_TIME"
+                     creationTime="CREATION_TIME"/>
+     ]?
+   </session>]*
+</QueryWaitSetResponse>
+
+
+AllAccountsWaitSet:
+-------------------
+<QueryWaitSetResponse id="WAITSETID"
+                      defTypes="DEFAULT_TYPES"
+                      owner="WAITSET_OWNER_ACCOUNT_ID"
+                      ld="LAST_ACCESS_DATE"                      
+                      nextSeqNo="NEXT_SEQNO"
+                      cbSeqNo="CB_SEQNO"
+                      currentSeqNo="CURRENT_SEQNO"
+                      >
+  [<buffered>
+     [<commit aid="ACCOUNT_ID" cid="COMMIT_ID"/>]* // only during WS creation before first WaitSetRequest
+  ]?
+  [<ready accounts="comma-separated list of account IDs"/>]?
+</QueryWaitSetResponse>

data/doc/soap-wiki.txt

@@ -0,0 +1,290 @@
+//
+// Notebook feature and WikiItem are deprecated as of 7.0.0.  Briefcase
+// feature and Document items are still supported and they can be used 
+// instead of Notebook.
+//
+// This set of API can be used to access private Notes, or public Wiki pages.
+//
+// Private Notes get stored in the mailbox of the requestor.  The access to
+// the private Notes will be determined by ACL of the folder the Notes are stored.
+// By default Notes are accesible to the account holder only, thus private.
+// 
+// Public Wiki pages are stored in a central location allocated to ZCS at the
+// installation time.  The access to the Wiki pages also follow the ACL on the
+// folder the pages are stored.
+//
+// There are two types of public Wiki storage.  There is a public wiki store,
+// and there are optional per-domain wiki store.  The public wiki store
+// is open to all authenticated and unauthenticated users.  The per-domain wiki
+// store has rwid access granted to the domain users only.
+//
+
+
+// Create / Update
+//
+// A Document represents a file.  A file can be created by uploading to FileUploadServlet.
+// Or it can refer to an attachment of an existing message.
+//
+// Both Wiki and Documents are versioned.  The server maintains the metadata
+// of each version, such as by who and when the version was edited, and the
+// fragment of each version.
+//
+// When updating an existing Document or Wiki, the client must supply the id
+// of Document or Wiki, and the last known version of the document in 
+// 'ver' attribute.  This is used to prevent blindly overwriting 
+// someone else's change made between the update.  The update
+// will succeed only when the last known version supplied by the client matches
+// the current version of the item identified by item-id.
+//
+// Saving a new document, as opposed to adding a revision of existing document, should leave
+// the id and ver fields empty in the request.  Then the server checks and see if the named
+// document already exists, if so returns an error.
+//
+// The request should contain either <upload> element or <msg> element, but not both.
+// When <upload> is used, the document should be first uploaded to FileUploadServlet, and
+// then use the upload-id from the FileUploadResponse.
+// When <m> is used, the document is retrieved from an existing message in the mailbox,
+// identified by the msg-id and part-id.
+// The content of the document can be inlined in <content/> element.
+// The content can come from another document / revision specified in <doc/> sub element.
+<SaveDocumentRequest>
+  <doc [id="{item-id}" ver="{last-known-version}"] [name="{file-name}"] [ct="{content-type}"] [l="{folder-id}"] [desc="{description}"] [descEnabled="true|false"]>
+    [<upload id="{upload-id}"/>]
+    [<m id="{msg-id}" part="{part-id}"/>]
+    [<content>{inlined-document-content-string}</content>]
+    [<doc id="{item-id}" ver="{version-to-restore-to}"/>]
+  </doc>
+</SaveDocumentRequest>
+
+<SaveDocumentResponse>
+  <doc id="{item-id}" ver="{version}" name="{item-name}"/>
+</SaveDocumentResponse>
+
+//
+// Example
+//
+// - Saving a new document
+//
+// REQUEST:
+//
+//<SaveDocumentRequest xmlns:ns0="urn:zimbraMail">
+//  <doc>
+//    <upload id="18baa043-394f-42ae-be8a-110b279cb696:cc2f2fdf-7957-4412-aa83-6433662ce5d0"/>
+//  </doc>
+//</SaveDocumentRequest>
+//
+// RESPONSE:
+//
+//<SaveDocumentResponse xmlns:ns0="urn:zimbraMail">
+//  <doc ver="1" id="574" rest="http://localhost:7070/home/user1/Notebook/PICT0370.JPG"/>
+//</SaveDocumentResponse>
+//
+//
+// - Updating an existing document
+//
+// REQUEST:
+//
+//<SaveDocumentRequest xmlns:ns0="urn:zimbraMail">
+//  <doc ver="1" id="574" desc="rev 2.0">
+//    <upload id="18baa043-394f-42ae-be8a-110b279cb696:fcb572ce-2a81-4ad3-b55b-cb998c47b416"/>
+//  </doc>
+//</SaveDocumentRequest>
+//
+// RESPONSE:
+//
+//<SaveDocumentResponse xmlns:ns0="urn:zimbraMail">
+//  <doc ver="2" id="574" rest="http://localhost:7070/home/user1/Notebook/PICT0370.JPG"/>
+//</SaveDocumentResponse>
+//
+//
+// A Wiki is a versioned HTML document.
+// folder-id argument is valid when the new wiki document is being created,
+// otherwise it's ignored, and the subsequent revision is stored in the same folder.
+// 
+// When updating an existing Wiki page, both id and ver attributes must
+// exist.  'id' attribute should contain the item id.  'ver' attribute should
+// contain the last known version of the page.  This is used for checking collision.
+// If the version in the server does not match the supplied last known version, 
+// the server will throw an exception, indicating a collision happened 
+// while the page was being edited.
+<SaveWikiRequest>
+  <w name="{wikiword}" [id="{item-id}" ver="{last-known-version}"] [l="{folder-id}"]> ... contents ... </w>
+</SaveWikiRequest>
+
+<SaveWikiResponse>
+  <w id="{item-id}" ver="{version}"/>
+</SaveWikiResponse>
+
+//
+// Examples
+//
+// - Saving a new page
+//
+// REQUEST:
+//
+//<SaveWikiRequest xmlns:ns0="urn:zimbraMail">
+//  <w l="12" name="mypage">this is a test</w>
+//</SaveWikiRequest>
+//
+// RESPONSE:
+//
+//<SaveWikiResponse xmlns:ns0="urn:zimbraMail">
+//  <w ver="1" id="575"/>
+//</SaveWikiResponse>
+//
+// - Updating an existing page
+//
+// REQUEST:
+//
+//<SaveWikiRequest xmlns:ns0="urn:zimbraMail">
+//  <w l="12" ver="1" name="mypage" id="575">this is a second revision</w>
+//</SaveWikiRequest>
+//
+
+// RESPONSE:
+//<SaveWikiResponse xmlns:ns0="urn:zimbraMail">
+//  <w ver="2" id="575"/>
+//</SaveWikiResponse>
+//
+//
+// Search
+// Documents and Wiki documents can be indexed.  
+// Use the existing Search API with "types" set to "wiki" or "document".
+//
+
+// Get
+// through the rest URL:
+// http://server/zimbra/user/[~]{account-name}/?id={item-id}
+//
+// through the SOAP API:
+// the list of wiki words are managed by the server.  
+
+//
+// GetWiki
+// returns the latest version if version is omitted from the request.
+// if count attribute is present it will return the N revision history of the metadata and fragment,
+// without body, where N <= count.
+//
+// if the attribute tr is set to 1, the server will traverse up the directory tree, then search the
+// central wiki account until the named Wiki item is found.  it's useful when requesting the template
+// items.
+//
+// GetWiki can be invoked with either 'name' or 'id' attribute.  'name' corresponds to
+// the title of the Wiki page, and 'id' corresponds to the zimbraId of the item.
+// Wiki name is unique only within the folder.  Thus when using 'name' attribute
+// to retrieve a Wiki page, the folder must be specified in 'l' attribute.
+//
+<GetWikiRequest>
+  <w [name="{word}"|id="{message-id}"] [ver="{version}"] [count="{num}"] [l="{folder}"] [tr="1|0"]/>
+</GetWikiRequest>
+
+<GetWikiResponse>
+  [<w name="{word}" ver="{version}" cr="{creator}" id="{message-id}" s="{size}" d="{created-date}" md="{modified-date}" l="{folder}" [f="{flags}"] [t="{tags}"]>
+     <fr>... fragment ...</fr>
+     <body>... contents ...</body>
+  </w>]+
+</GetWikiResponse>
+
+//
+// WikiAction
+// See ItemAction and MsgAction API for the usage.
+//
+<WikiActionRequest>
+  <!-- action can be preceeded by a "!" to negate it" -->
+  <action id="{list}" op="delete|read|flag|tag|move|update|spam|template|rename" [tag="..."] [l="{folder}"] [t="..."] [name="{newName}"]/>
+</WikiActionRequest>
+
+<WikiActionResponse>
+  <action id="{list}" op="delete|read|flag|tag|move|update|spam|template|rename"/>
+</WikiActionResponse>
+
+//
+// Template management
+//
+// use WikiAction with op="template"
+//
+// <WikiActionRequest>
+//   <action op="template" id="{wiki-item or folder id}" t="dir|template|styles|header|footer|sidebar|index">
+//     {url to the template}
+//   </action>
+// <WikiActionRequest>
+//
+// e.g.
+//
+// <WikiActionRequest>
+//   <action op="template" id="103" t="dir">
+//     //wiki/Templates/Powerpoint
+//   </action>
+// <WikiActionRequest>
+
+
+//
+// DiffDocument
+//
+// performs line by line diff of two revisions of a Document or WikiItem,
+// then returns a list of <chunk/> containing the result.  Sections of text
+// that are identical to both versions are indicated with disp="common".
+// For each conflict the chunk will show disp="first", disp="second" or both.
+// 
+//
+// v3:
+// line 1<br>
+// line 2<br>
+// line 3<br>
+// line 4<br>
+// line 5<br>
+// <br>
+//
+// v4:
+// line 1<br>
+// line 2<br>
+// line 3.6<br>
+// line 4<br>
+// line 5<br>
+// <br>
+// 
+// REQUEST:
+// -------------
+// <DiffDocumentRequest xmlns:ns0="urn:zimbraMail">
+//   <doc v1="3" v2="4" id="641"/>
+// </DiffDocumentRequest>
+// 
+// RESPONSE:
+// --------------
+// <DiffDocumentResponse xmlns:ns0="urn:zimbraMail">
+//   <chunk disp="common">line 1&lt;br&gt;
+// line 2&lt;br&gt;</chunk>
+//   <chunk disp="first">line 3&lt;br&gt;</chunk>
+//   <chunk disp="second">line 3.6&lt;br&gt;</chunk>
+//   <chunk disp="common">line 4&lt;br&gt;
+// line 5&lt;br&gt;
+// &lt;br&gt;</chunk>
+// </DiffDocumentResponse>
+//
+
+<DiffDocumentRequest>
+  <doc id="{item-id}" v1="{version}" v2="{version}"/>
+</DiffDocumentRequest>
+
+<DiffDocumentResponse>
+  <chunk disp="common|first|second"> ... text ... </chunk>+
+</DiffDocumentResponse>
+
+
+//
+// ListDocumentRevisions
+//
+// returns {num} number of revisions starting from {version} of the requested
+// document.  {num} defaults to 1.  {version} defaults to the current version.
+//
+<ListDocumentRevisionsRequest>
+  <doc id="{item-id}" [ver="{version}"] [count="{num}"]/>
+</ListDocumentRevisionsRequest>
+
+<ListDocumentRevisionsResponse>
+  [<doc name="{name}" ver="{version}" cr="{creator}" id="{message-id}" s="{size}" d="{created-date}" md="{modified-date}" l="{folder}" [f="{flags}"] [t="{tags}"] [loid="{lock-owner-account-id}"] [loe="{lock-owner-email}"] [desc="{optional-description}] [descEnabled="true|false"]>
+     <fr>... fragment ...</fr>
+  </doc>]+
+</ListDocumentRevisionsResponse>
+
+