-
Notifications
You must be signed in to change notification settings - Fork 46
Webservice
Work in progress This page is functionality complete, but the functionality could be described more extensively.
- General
-
Commands
-
WebserviceDevice
- Method: ListDevicesDetails()
- Method: RemoveDevice($deviceId)
- Method: WipeDevice($deviceId)
- Method: ResyncDevice($deviceId)
- Method: ResyncFolder($deviceId, $folderId) (Z-Push 2.2.6 or higher)
- Method: GetDeviceDetails($deviceId, $withHierarchyCache) (Z-Push 2.3.6 or higher)
- Method SetDeviceOptions($deviceId, $filtertype) (Z-Push 2.4.0 or higher)
- Additional Folder for Users (Z-Push 2.3.x or higher)
- WebserviceUsers
- WebserviceInfo (Z-Push 2.3.0 or higher)
-
WebserviceDevice
- Example
Certain administrative work can be triggered to Z-Push over a webservice functionality.
These are a few tasks that can also be done via the z-push-admin tool, but not exclusively.
The call to Z-Push is analogue to the ActiveSync specification. To call a functionality, just build a soap request to the following URL:
https://<server>/Microsoft-Server-ActiveSync?Cmd=<command>&DeviceId=webservice&DeviceType=webservice&User=<username>
- The commands are structured into groups. See the available commands in the section below.
- Actions that are executed on a username will be executed for the User specified in the URL (GET user).
- To authenticate, a username+password combination is required via HTTP Basic Auth.
- The authentication username and URL (GET) user may differ, meaning that the authenticated user wishes to execute the action for the specified user in the URL.
- In this case, the authenticated username must be determined as an "admin user". This is done via a call to the backend->Setup() method, like
ZPush::GetBackend()->Setup("SYSTEM", true); - This command is documented to react as described in the interface description of the IBackend->Setup() method. For the above statement, this means if the authenticated user is considered "admin" or not.
- In this case, the authenticated username must be determined as an "admin user". This is done via a call to the backend->Setup() method, like
The functionality exposed via the webservice is devided into these commands. Each command has an own authentication requirement.
This is intended to allow a user to perform certain actions on his own devices, like listing, re-synchronizing and execute a remote wipe. Per default the authenticated user and GET user should be the same.
If this is not the case, the authenticated user needs to have "admin permissions" over the GET user, as described above.
Returns a list of all known devices of the GET user.
Remove all state data for a device of the GET user. The next time the device will connect it will be treated as a never seen before device. It must run through Provisioning before it is able to proceed.
Marks a device of the GET user to be remotely wiped. This is done via the Provisioning command and will require for the device to connect (once again) to the server to be executed.
Marks a device of the GET user for full re-synchronization. This is similar to RemoveDevice(), but e.g. Provisioning will not be required. Also the "first connection time" will be preserved in this case.
Marks a folder of a device of the GET user for re-synchronization. The folderids are available through the output of ListDeviceDetails().
Returns the details of a given deviceid of the Request::GetGETUser().
Sets device options of the Request::GetGETUser().
Method: AdditionalFolderList($deviceId)
Returns a list of all additional folders of the given device and the GET user. It consists of the Name, Store, FolderID, FolderType and the nature (source) of the folder.
Folders marked as "static" were configured in the "additional folders" section of the z-push configuration file, while "user" folders were created via this API and are available for edit/remove.
"static" folders can not be edited via the API. Being listed here does not mean that they are visible on the device, because the user could not have sufficient permissions to access them. In this case, they are not visible on the device.
Method: AdditionalFolderAdd($deviceId, $add_store, $add_folderid, $add_name, $add_type, $add_flags)
Adds an additional folder to the given device and the GET user. The parameters are:
- string $deviceId - device id the folder should be added to.
- string $add_store - the store where this folder is located, e.g. "SYSTEM" (for public folder) or an username/email address.
- string $add_folderid - the folder id of the additional folder.
- string $add_name - the name of the addtional folder (has to be unique for all folders on the device).
- string $add_type - AS foldertype of SYNC_FOLDER_TYPE_USER_*
- int $add_flags - Additional flags, like DeviceManager::FLD_FLAGS_REPLYASUSER (1)
The methods returns true if the operation succeeded, or a SoapFault with an extensive error message in case of failure (e.g. folder name or id are already in the list).
Method: AdditionalFolderEdit($deviceId, $add_folderid, $add_name, $add_flags)
Updates the name of an additional folder to the given device and the GET user.
- string $deviceId - device id of where the folder should be updated.
- string $add_folderid - the folder id of the additional folder.
- string $add_name - the name of the additional folder (has to be unique for all folders on the device).
- int $add_flags - Additional flags, like DeviceManager::FLD_FLAGS_REPLYASUSER (1)
To update any value, both need to be provided and are saved. E.g. if you want to update the flags for an additional folder, the name has to be sent as well, because it will get overwritten. You should then get the list first and use the latest name from the list.
The methods returns true if the operation succeeded, or a SoapFault with an extensive error message in case of failure (e.g. new folder name is already in the list).
Method: AdditionalFolderRemove($deviceId, $add_folderid)
Removes an additional folder from the given device and the GET user.
- string $deviceId - device id of where the folder should be removed.
- string $add_folderid - the folder id of the additional folder.
The methods returns true if the operation succeeded, or a SoapFault with an extensive error message in case of failure (e.g. folder id can not be found in the list).
Method: AdditionalFolderSetList($deviceId, $set_store, $set_folders)
This method is available since Z-Push 2.3.4.
Sets a list of additional folders of one store to the given device and the Request::GetGETUser(). If there are additional folders for this store, that are not in the list they will be removed.
- string $deviceId - device id the folder should be added to.
- string $set_store - the store where this folder is located, e.g. "SYSTEM" (for public folder) or an username/email address.
- array $set_folders - a list of folders to be set for this user. Other existing additional folders (that are not in this list) will be removed. The list is an array containing folders, where each folder is an array with the following keys:
- 'folderid' (string) the folder id of the additional folder.
- 'parentid' (string) the folderid of the parent folder. If no parent folder is set or the parent folder is not defined, '0' (main folder) is used.
- 'name' (string) the name of the additional folder (has to be unique for all folders on the device).
- 'type' (string) AS foldertype of SYNC_FOLDER_TYPE_USER_*
- 'flags' (int) Additional flags, like DeviceManager::FLD_FLAGS_SENDASOWNER
The methods returns true if the operation succeeded, or a SoapFault with an extensive error message in case of failure.
The access this functionality needs to be expressively granted via the z-push configuration, parameter ALLOW_WEBSERVICE_USERS_ACCESS. The default value is false.
If the access is granted, the authenticated user needs to have "admin rights" as described in the How-to section above.
Returns a list of all known devices.
Returns a list of all known devices of the users.
Returns a list of all known devices with users and when they have been synchronized for the first time.
Returns a list of folders of the Request::GetGETUser(). If the user has not enough permissions an empty result is returned.
Returns the Z-Push version.
Returns signatures saved for the Request::GetGETUser().
Returns information about the user's store: number of folders, store size, full name, email address.
The following small php script allows the listing, adding, editing and removing of an additional folder. The parameters (server, user, password, deviceid, foldername and folderid) need to be adjusted to match and be correct. Comment/Uncomment the command you want to execute.