[commits] [Wiki] changed: ActiveSync/Development

Michael Rubinsky mrubinsk at horde.org
Thu Nov 24 00:17:31 UTC 2016 

mrubinsk  Thu, 24 Nov 2016 00:17:31 +0000

Modified page: https://wiki.horde.org/ActiveSync/Development
New Revision:  10
Change log:  Start the overview of the SYNC lifecycle.

@@ -135,5 +135,226 @@


  ++ Life Cycle of a Client.

-What we will describe is the life cycle of a client-server pairing  
from the initial connection to be able to synchronize changes. Let's  
start with a fresh, never before connected client. The first thing  
that happens is the OPTIONS request. This essentially tells the server  
what protocol versions the client supports and the server responds  
with (among other things) the version that it will be using.
+What we will describe is the life cycle of a client-server pairing  
from the initial connection to be able to synchronize changes. Let's  
start with a fresh, never before connected client. The details and  
order of things vary from EAS version to version. This is designed as  
a general overview and most closely resembles what happens in EAS  
version >= 14.
+
+The first thing that happens is the OPTIONS request. This essentially  
tells the server what protocol versions the client supports and the  
server responds with (among other things) the version that it will be  
using. This is usually where the device object is first created. TODO:  
Flesh this out with more details.
+
+Second will normally be a SETTINGS request. This is where the client  
can give the server details about the device and/or OS, application  
name etc... Normally this is responded to with server details about  
the user account. The following is an example synclog of the SETTINGS  
request and response using a Windows 10 Mail client:
+
+<code>
+2016-11-14T17:03:59+00:00 INFO: [10030]  
Horde_Core_ActiveSync_Driver::authenticate() attempt for mike
+2016-11-14T17:03:59+00:00 INFO: [10030] SETTINGS request received for  
user mike
+2016-11-14T17:03:59+00:00 INFO: [10030] Device entry exists for  
340B5431BBC4241BB73F622B4C6D18E9, updating userAgent, version, and  
supported.
+2016-11-14T17:03:59+00:00 INFO: [10030] GET VARIABLES: Array
+(
+    [ProtVer] => 14.1
+    [Cmd] => Settings
+    [Locale] => 1033
+    [DeviceId] => 340b5431bbc4241bb73f622b4c6d18e9
+    [PolicyKey] => 0
+    [DeviceType] => WindowsMail
+)
+
+2016-11-14T17:03:59+00:00 DEBUG: [10030] I  <Settings:Settings>
+2016-11-14T17:03:59+00:00 DEBUG: [10030] I   <Settings:DeviceInformation>
+2016-11-14T17:03:59+00:00 DEBUG: [10030] I    <Settings:Set>
+2016-11-14T17:03:59+00:00 DEBUG: [10030] I     <Settings:Model>
+2016-11-14T17:03:59+00:00 DEBUG: [10030] I       VMware Virtual Platform
+2016-11-14T17:03:59+00:00 DEBUG: [10030] I     </Settings:Model>
+2016-11-14T17:03:59+00:00 DEBUG: [10030] I     <Settings:IMEI />
+2016-11-14T17:03:59+00:00 DEBUG: [10030] I     <Settings:FriendlyName>
+2016-11-14T17:03:59+00:00 DEBUG: [10030] I       DESKTOP-E96J0OF
+2016-11-14T17:03:59+00:00 DEBUG: [10030] I     </Settings:FriendlyName>
+2016-11-14T17:03:59+00:00 DEBUG: [10030] I     <Settings:OS>
+2016-11-14T17:03:59+00:00 DEBUG: [10030] I       Windows 10.0.14393
+2016-11-14T17:03:59+00:00 DEBUG: [10030] I     </Settings:OS>
+2016-11-14T17:03:59+00:00 DEBUG: [10030] I     <Settings:OSLanguage>
+2016-11-14T17:03:59+00:00 DEBUG: [10030] I       English
+2016-11-14T17:03:59+00:00 DEBUG: [10030] I     </Settings:OSLanguage>
+2016-11-14T17:03:59+00:00 DEBUG: [10030] I     <Settings:PhoneNumber />
+2016-11-14T17:03:59+00:00 DEBUG: [10030] I     <Settings:UserAgent>
+2016-11-14T17:03:59+00:00 DEBUG: [10030] I       MSFT-WIN-3/10.0.14393
+2016-11-14T17:03:59+00:00 DEBUG: [10030] I     </Settings:UserAgent>
+2016-11-14T17:03:59+00:00 DEBUG: [10030] I     <Settings:EnableOutboundSMS>
+2016-11-14T17:03:59+00:00 DEBUG: [10030] I     <Settings:MobileOperator>
+2016-11-14T17:03:59+00:00 DEBUG: [10030] I       OperatorName
+2016-11-14T17:03:59+00:00 DEBUG: [10030] I     </Settings:MobileOperator>
+2016-11-14T17:03:59+00:00 DEBUG: [10030] I    </Settings:Set>
+2016-11-14T17:03:59+00:00 INFO: [10030] Device entry exists for  
340B5431BBC4241BB73F622B4C6D18E9, updating userAgent, version, and  
supported.
+2016-11-14T17:03:59+00:00 DEBUG: [10030] I   </Settings:DeviceInformation>
+2016-11-14T17:03:59+00:00 DEBUG: [10030] I   <Settings:UserInformation>
+2016-11-14T17:03:59+00:00 DEBUG: [10030] I    <Settings:Get />
+2016-11-14T17:03:59+00:00 DEBUG: [10030] I   </Settings:UserInformation>
+2016-11-14T17:03:59+00:00 DEBUG: [10030] I  </Settings:Settings>
+2016-11-14T17:03:59+00:00 DEBUG: [10030] O  <Settings:Settings>
+2016-11-14T17:03:59+00:00 DEBUG: [10030] O   <Settings:Status>
+2016-11-14T17:03:59+00:00 DEBUG: [10030] O    1
+2016-11-14T17:03:59+00:00 DEBUG: [10030] O   </Settings:Status>
+2016-11-14T17:03:59+00:00 DEBUG: [10030] O   <Settings:DeviceInformation>
+2016-11-14T17:03:59+00:00 DEBUG: [10030] O    <Settings:Status>
+2016-11-14T17:03:59+00:00 DEBUG: [10030] O     1
+2016-11-14T17:03:59+00:00 DEBUG: [10030] O    </Settings:Status>
+2016-11-14T17:03:59+00:00 DEBUG: [10030] O   </Settings:DeviceInformation>
+2016-11-14T17:03:59+00:00 DEBUG: [10030] O   <Settings:UserInformation>
+2016-11-14T17:03:59+00:00 DEBUG: [10030] O    <Settings:Status>
+2016-11-14T17:03:59+00:00 DEBUG: [10030] O     1
+2016-11-14T17:03:59+00:00 DEBUG: [10030] O    </Settings:Status>
+2016-11-14T17:03:59+00:00 DEBUG: [10030] O    <Settings:Get>
+2016-11-14T17:03:59+00:00 DEBUG: [10030] O     <Settings:Accounts>
+2016-11-14T17:03:59+00:00 DEBUG: [10030] O      <Settings:Account>
+2016-11-14T17:03:59+00:00 DEBUG: [10030] O       <Settings:AccountName>
+2016-11-14T17:03:59+00:00 DEBUG: [10030] O        Default Identity
+2016-11-14T17:03:59+00:00 DEBUG: [10030] O       </Settings:AccountName>
+2016-11-14T17:03:59+00:00 DEBUG: [10030] O       <Settings:EmailAddresses>
+2016-11-14T17:03:59+00:00 DEBUG: [10030] O         
<Settings:PrimarySmtpAddress>
+2016-11-14T17:03:59+00:00 DEBUG: [10030] O         mike at theupstairsroom.com
+2016-11-14T17:03:59+00:00 DEBUG: [10030] O         
</Settings:PrimarySmtpAddress>
+2016-11-14T17:03:59+00:00 DEBUG: [10030] O        <Settings:SmtpAddress>
+2016-11-14T17:03:59+00:00 DEBUG: [10030] O         mike at theupstairsroom.com
+2016-11-14T17:03:59+00:00 DEBUG: [10030] O        </Settings:SmtpAddress>
+2016-11-14T17:03:59+00:00 DEBUG: [10030] O       </Settings:EmailAddresses>
+2016-11-14T17:03:59+00:00 DEBUG: [10030] O      </Settings:Account>
+2016-11-14T17:03:59+00:00 DEBUG: [10030] O     </Settings:Accounts>
+2016-11-14T17:03:59+00:00 DEBUG: [10030] O    </Settings:Get>
+2016-11-14T17:03:59+00:00 DEBUG: [10030] O   </Settings:UserInformation>
+2016-11-14T17:03:59+00:00 DEBUG: [10030] O  </Settings:Settings>
+</code>
+
+
+For the purposes of this page, we are going to ignore the  
PROVISIONING stuff. The next step is the FOLDERSYNC request:
+<code>
+2016-11-14T17:03:59+00:00 DEBUG: [10029] I  <FolderHierarchy:FolderSync>
+2016-11-14T17:03:59+00:00 DEBUG: [10029] I   <FolderHierarchy:SyncKey>
+2016-11-14T17:03:59+00:00 DEBUG: [10029] I     0
+2016-11-14T17:03:59+00:00 DEBUG: [10029] I   </FolderHierarchy:SyncKey>
+2016-11-14T17:03:59+00:00 DEBUG: [10029] I  </FolderHierarchy:FolderSync>
+</code>
+
+First, the client requests a SyncKey of 0. This indicates it is a  
fresh start and that the server should discard any previous sets of  
state it may have for this client and user. The server fetches the  
list of folders that are available. For this purpose each groupware  
share (address book, calendar etc...) is considered a folder. The  
entry point for this is  
//**Horde_Core_ActiveSync_Driver::getFolderList()**//.
+
+At this point we should talk about the backend's id and the  
ActiveSync UID for each folder. From the client's point of view, all  
it cares about is the uid for the folder. We create new UIDs whenever  
a new folder is encountered. The mapping of UIDs to backend ids is  
managed by the Horde_ActiveSync_State driver. So, you will see  
something like this in the sync log:
+
+<code>
+2016-11-14T17:03:59+00:00 INFO: [10029]  
Horde_Core_ActiveSync_Driver::getFolderList()
+2016-11-14T17:03:59+00:00 INFO: [10029] Device entry exists for  
340B5431BBC4241BB73F622B4C6D18E9, updating userAgent, version, and  
supported.
+2016-11-14T12:04:00-05:00 INFO: [10029] Creating new folder uuid for  
Calendar:1w_UP1B0Fbgun61fg3dAqLJ: A2603e3ee
+2016-11-14T12:04:00-05:00 INFO: [10029] Creating new folder uuid for  
@Contacts@: Cd1b7031f
+2016-11-14T12:04:00-05:00 INFO: [10029] Creating new folder uuid for  
@Tasks@: Tb666e6ce
+2016-11-14T12:04:00-05:00 INFO: [10029] Creating new folder uuid for  
@Notes@: N6d6ecbe3
+2016-11-14T12:04:00-05:00 INFO: [10029] Polling  
Horde_Core_ActiveSync_Driver::_getMailFolders()
+2016-11-14T12:04:00-05:00 INFO: [10029] Creating new folder uuid for  
INBOX: Fe4d57a40
+</code>
+
+Now we send the folder tree to the client, along with a synckey (only  
showing one folder for brevity's sake):
+
+<code>
+2016-11-14T12:04:00-05:00 DEBUG: [10029] O  <FolderHierarchy:FolderSync>
+2016-11-14T12:04:00-05:00 DEBUG: [10029] O   <FolderHierarchy:Status>
+2016-11-14T12:04:00-05:00 DEBUG: [10029] O    1
+2016-11-14T12:04:00-05:00 DEBUG: [10029] O   </FolderHierarchy:Status>
+2016-11-14T12:04:00-05:00 DEBUG: [10029] O   <FolderHierarchy:SyncKey>
+2016-11-14T12:04:00-05:00 DEBUG: [10029] O     
{5829ee7f-b60c-405a-822f-272dc0a80160}1
+2016-11-14T12:04:00-05:00 DEBUG: [10029] O   </FolderHierarchy:SyncKey>
+2016-11-14T12:04:00-05:00 DEBUG: [10029] O   <FolderHierarchy:Changes>
+2016-11-14T12:04:00-05:00 DEBUG: [10029] O    <FolderHierarchy:Count>
+2016-11-14T12:04:00-05:00 DEBUG: [10029] O     87
+2016-11-14T12:04:00-05:00 DEBUG: [10029] O    </FolderHierarchy:Count>
+2016-11-14T12:04:00-05:00 DEBUG: [10029] O    <FolderHierarchy:Add>
+2016-11-14T12:04:00-05:00 DEBUG: [10029] O      
<FolderHierarchy:ServerEntryId>
+2016-11-14T12:04:00-05:00 DEBUG: [10029] O      Tb666e6ce
+2016-11-14T12:04:00-05:00 DEBUG: [10029] O      
</FolderHierarchy:ServerEntryId>
+2016-11-14T12:04:00-05:00 DEBUG: [10029] O     <FolderHierarchy:ParentId>
+2016-11-14T12:04:00-05:00 DEBUG: [10029] O      0
+2016-11-14T12:04:00-05:00 DEBUG: [10029] O     </FolderHierarchy:ParentId>
+2016-11-14T12:04:00-05:00 DEBUG: [10029] O     <FolderHierarchy:DisplayName>
+2016-11-14T12:04:00-05:00 DEBUG: [10029] O      Tasks
+2016-11-14T12:04:00-05:00 DEBUG: [10029] O     </FolderHierarchy:DisplayName>
+2016-11-14T12:04:00-05:00 DEBUG: [10029] O     <FolderHierarchy:Type>
+2016-11-14T12:04:00-05:00 DEBUG: [10029] O      7
+2016-11-14T12:04:00-05:00 DEBUG: [10029] O     </FolderHierarchy:Type>
+2016-11-14T12:04:00-05:00 DEBUG: [10029] O    </FolderHierarchy:Add>
+2016-11-14T12:04:01-05:00 DEBUG: [10029] O   </FolderHierarchy:Changes>
+2016-11-14T12:04:01-05:00 DEBUG: [10029] O  </FolderHierarchy:FolderSync>
+</code>
+
+This is a good time to mention the SyncKey. The SyncKey is the unique  
identifier a specific set of state. It represents the state of the  
collection being synced at that point in time. It always has the  
following form:
+
+{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}y where y is a continuously  
increasing counter. That increments any time changes are received from  
or sent to the client. The GUID-looking value in front of the counter  
will remain constant after it's generated for each collection.
+
+Next, the client can issue SYNC requests for each folder it wants to  
populate. Unlike the FOLDERSYNC request, the SYNC request doesn't send  
the actual changes back with the 1st synckey. E.g., the first SYNC  
request for a mail folder contains some options such as the filtertype  
(how far back to sync), bodytype preferences etc... The server sets  
those options in the SyncCache for that collection, creates a new  
synckey, stores it in the collection's state and sends back the  
initial response.
+
+<code>
+2016-11-14T17:04:03+00:00 DEBUG: [10030] I  <Synchronize>
+2016-11-14T17:04:03+00:00 DEBUG: [10030] I   <Folders>
+2016-11-14T17:04:03+00:00 DEBUG: [10030] I    <Folder>
+2016-11-14T17:04:03+00:00 DEBUG: [10030] I     <SyncKey>
+2016-11-14T17:04:03+00:00 DEBUG: [10030] I       0
+2016-11-14T17:04:03+00:00 DEBUG: [10030] I     </SyncKey>
+2016-11-14T17:04:03+00:00 DEBUG: [10030] I     <FolderId>
+2016-11-14T17:04:03+00:00 DEBUG: [10030] I       Fe4d57a40
+2016-11-14T17:04:03+00:00 DEBUG: [10030] I     </FolderId>
+2016-11-14T17:04:03+00:00 DEBUG: [10030] I     <Options>
+2016-11-14T17:04:03+00:00 DEBUG: [10030] I      <FilterType>
+2016-11-14T17:04:03+00:00 DEBUG: [10030] I        5
+2016-11-14T17:04:03+00:00 DEBUG: [10030] I      </FilterType>
+2016-11-14T17:04:03+00:00 DEBUG: [10030] I      <AirSyncBase:BodyPreference>
+2016-11-14T17:04:03+00:00 DEBUG: [10030] I       <AirSyncBase:Type>
+2016-11-14T17:04:03+00:00 DEBUG: [10030] I         1
+2016-11-14T17:04:03+00:00 DEBUG: [10030] I       </AirSyncBase:Type>
+2016-11-14T17:04:03+00:00 DEBUG: [10030] I       <AirSyncBase:Preview>
+2016-11-14T17:04:03+00:00 DEBUG: [10030] I         128
+2016-11-14T17:04:03+00:00 DEBUG: [10030] I       </AirSyncBase:Preview>
+2016-11-14T17:04:03+00:00 DEBUG: [10030] I      </AirSyncBase:BodyPreference>
+2016-11-14T17:04:03+00:00 DEBUG: [10030] I      <AirSyncBase:BodyPreference>
+2016-11-14T17:04:03+00:00 DEBUG: [10030] I       <AirSyncBase:Type>
+2016-11-14T17:04:03+00:00 DEBUG: [10030] I         2
+2016-11-14T17:04:03+00:00 DEBUG: [10030] I       </AirSyncBase:Type>
+2016-11-14T17:04:03+00:00 DEBUG: [10030] I       <AirSyncBase:Preview>
+2016-11-14T17:04:03+00:00 DEBUG: [10030] I         128
+2016-11-14T17:04:03+00:00 DEBUG: [10030] I       </AirSyncBase:Preview>
+2016-11-14T17:04:03+00:00 DEBUG: [10030] I      </AirSyncBase:BodyPreference>
+2016-11-14T17:04:03+00:00 DEBUG: [10030] I      <MIMESupport>
+2016-11-14T17:04:03+00:00 DEBUG: [10030] I        1
+2016-11-14T17:04:03+00:00 DEBUG: [10030] I      </MIMESupport>
+2016-11-14T17:04:03+00:00 DEBUG: [10030] I      <AirSyncBase:BodyPreference>
+2016-11-14T17:04:03+00:00 DEBUG: [10030] I       <AirSyncBase:Type>
+2016-11-14T17:04:03+00:00 DEBUG: [10030] I         4
+2016-11-14T17:04:03+00:00 DEBUG: [10030] I       </AirSyncBase:Type>
+2016-11-14T17:04:03+00:00 DEBUG: [10030] I       <AirSyncBase:TruncationSize>
+2016-11-14T17:04:03+00:00 DEBUG: [10030] I         107520
+2016-11-14T17:04:03+00:00 DEBUG: [10030] I        
</AirSyncBase:TruncationSize>
+2016-11-14T17:04:03+00:00 DEBUG: [10030] I       <AirSyncBase:Preview>
+2016-11-14T17:04:03+00:00 DEBUG: [10030] I         128
+2016-11-14T17:04:03+00:00 DEBUG: [10030] I       </AirSyncBase:Preview>
+2016-11-14T17:04:03+00:00 DEBUG: [10030] I      </AirSyncBase:BodyPreference>
+2016-11-14T17:04:03+00:00 DEBUG: [10030] I      <Conflict>
+2016-11-14T17:04:03+00:00 DEBUG: [10030] I        1
+2016-11-14T17:04:03+00:00 DEBUG: [10030] I      </Conflict>
+2016-11-14T17:04:03+00:00 DEBUG: [10030] I       
<RightsManagement:RightsManagementSupport>
+2016-11-14T17:04:03+00:00 DEBUG: [10030] I        1
+2016-11-14T17:04:03+00:00 DEBUG: [10030] I       
</RightsManagement:RightsManagementSupport>
+2016-11-14T17:04:03+00:00 DEBUG: [10030] I     </Options>
+2016-11-14T17:04:03+00:00 DEBUG: [10030] I    </Folder>
+2016-11-14T17:04:03+00:00 DEBUG: [10030] I   </Folders>
+2016-11-14T17:04:03+00:00 DEBUG: [10030] I  </Synchronize>
+
+2016-11-14T17:04:03+00:00 DEBUG: [10030] O  <Synchronize>
+2016-11-14T17:04:03+00:00 DEBUG: [10030] O   <Status>
+2016-11-14T17:04:03+00:00 DEBUG: [10030] O    1
+2016-11-14T17:04:03+00:00 DEBUG: [10030] O   </Status>
+2016-11-14T17:04:03+00:00 DEBUG: [10030] O   <Folders>
+2016-11-14T17:04:03+00:00 DEBUG: [10030] O    <Folder>
+2016-11-14T17:04:03+00:00 DEBUG: [10030] O     <SyncKey>
+2016-11-14T17:04:03+00:00 DEBUG: [10030] O       
{5829ee83-11e8-472d-bc66-272ec0a80160}1
+2016-11-14T17:04:03+00:00 DEBUG: [10030] O     </SyncKey>
+2016-11-14T17:04:03+00:00 DEBUG: [10030] O     <FolderId>
+2016-11-14T17:04:03+00:00 DEBUG: [10030] O      Fe4d57a40
+2016-11-14T17:04:03+00:00 DEBUG: [10030] O     </FolderId>
+2016-11-14T17:04:03+00:00 DEBUG: [10030] O     <Status>
+2016-11-14T17:04:03+00:00 DEBUG: [10030] O      1
+2016-11-14T17:04:03+00:00 DEBUG: [10030] O     </Status>
+2016-11-14T17:04:03+00:00 DEBUG: [10030] O    </Folder>
+2016-11-14T17:04:03+00:00 DEBUG: [10030] I   </Folders>
+2016-11-14T17:04:03+00:00 DEBUG: [10030] I  </Synchronize>
+</code>

More information about the commits mailing list