The Sync Manager provides functions that allow a sync application—with the user's permission—to gain access to secure databases that have the sync bypass rule set.
This chapter is organized as follows:
Sync Manager Constants
Sync Manager Functions and Macros
The header file SyncMgr.h
declares the API that this chapter describes.
Sync Manager Constants
Sync Manager Error Codes
Purpose
Error codes returned by the various Sync Manager functions.
Declared In
SyncMgr.h
Constants
-
#define syncMgrErrAccessDenied (syncMgrErrorClass | 0x04)
- Access was denied. Either the user refused to authorize registration of the sync client, or an unregistered sync client is attempting to get or release access
-
#define syncMgrErrMaxSessionsActive (syncMgrErrorClass | 0x06)
-
#define syncMgrErrMemAllocFailure (syncMgrErrorClass | 0x03)
-
#define syncMgrErrOperationNotSupported (syncMgrErrorClass | 0x01)
-
#define syncMgrErrSystemErr (syncMgrErrorClass | 0x02)
- A system error occurred.
-
#define syncMgrErrUserRefusedSyncApp (syncMgrErrorClass | 0x05)
Sync Manager Security Policies
Purpose
Security policies enforced by the Sync Manager.
Declared In
SyncMgr.h
Constants
-
#define kSyncPolicyRestrictAppRegistration 'sync'
- Limits the set of applications that are allowed to register to those specified in in the security policy.
-
#define kSyncPolicyNonUiAuthentication 'noui'
- Allows specified applications to register non-intrusively (without UI).
Miscellaneous Sync Manager Constants
Purpose
The Sync Manager also defines these constants.
Declared In
SyncMgr.h
Constants
-
#define kSyncAppDescriptionMaxLen (95 + 1)
- The maximum length in bytes—including the null terminator—of the product description supplied to
SyncAddSynchronizer()
. -
#define kSyncMaxActiveSessions (32)
-
#define kSyncProductNameMaxLen (43 + 1)
- The maximum length in bytes—including the null terminator—of the product display name supplied to
SyncAddSynchronizer()
.
Sync Manager Functions and Macros
SyncAddSynchronizer Function
Purpose
Ask the user for permission to register a sync application with the Sync Manager and, if permission is granted, register that application.
Declared In
SyncMgr.h
Prototype
status_t SyncAddSynchronizer ( const char*displayNameP
, const char*descriptionP
)
Parameters
-
→ displayNameP
- Pointer to the display name of the product. This string is displayed to the user. This string should be no more than kSyncProductNameMaxLen bytes long, including the null terminator.
-
→ descriptionP
- Pointer to a brief description of the product, the vendor, or both that is to be displayed to the user. Supply
NULL
for this parameter if no description is needed. This string should be no more than kSyncAppDescriptionMaxLen bytes long, including the null terminator.
Returns
Returns errNone
if the sync application was successfully registered, or syncMgrErrAccessDenied if there was an error.
Comments
A sync application can synchronize or back up secure databases only if it is registered with the Sync Manager.
The sync client should call this function once after it is installed on the handheld. This function prompts the user to approve the sync client by entering the system password. If the user is unable or unwilling to approve the sync client, this function returns syncMgrErrAccessDenied
.
Comments
IMPORTANT: When called from the main application thread, this function may block. While blocked, the application will not receive events and won't redraw its windows. As well, deferred sublaunches and notifications won't execute while the main application thread is blocked.
See Also
SyncSessionGetAccess()
, SyncSessionReleaseAccess()
SyncSessionGetAccess Function
Purpose
Get access to secure databases for a sync session.
Declared In
SyncMgr.h
Prototype
status_t SyncSessionGetAccess ( void )
Parameters
Returns
Returns errNone
if the Sync Manager was able to add the sync client's token to the global bypass rule, or syncMgrErrAccessDenied
if not.
Comments
The sync client must be registered prior to this call.
The sync client must call this function once for every sync session. After the sync client has accessed the desired secure databases, it should call SyncSessionReleaseAccess()
.
See Also
SyncSessionReleaseAccess Function
Purpose
Signal that the sync client no longer needs access to any secure databases.
Declared In
SyncMgr.h
Prototype
status_t SyncSessionReleaseAccess ( void )
Parameters
Returns
Returns errNone
as long as the sync client is registered. Otherwise, returns syncMgrErrAccessDenied
.
Comments
The sync client must call this function once for every sync session. Prior to accessing any secure databases it should call SyncSessionGetAccess()
. Once it is done accessing secure databases, it should call SyncSessionReleaseAccess()
.