Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

34    Sync Manager

System Management

Exploring Palm OS®

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 ^TOP^

Sync Manager Error Codes ^TOP^

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 ^TOP^

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 ^TOP^

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 ^TOP^

SyncAddSynchronizer Function ^TOP^

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 ^TOP^

Purpose

Get access to secure databases for a sync session.

Declared In

SyncMgr.h

Prototype

status_t SyncSessionGetAccess (
   void
)

Parameters

None.

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

SyncAddSynchronizer()

SyncSessionReleaseAccess Function ^TOP^

Purpose

Signal that the sync client no longer needs access to any secure databases.

Declared In

SyncMgr.h

Prototype

status_t SyncSessionReleaseAccess (
   void
)

Parameters

None.

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().

See Also

SyncAddSynchronizer()