Synchronization Server SDK
Version 4.1.2
NOTE
This document is provided for informational purposes only, and does not constitute a binding legal document unless specifically incorporated by reference into a binding legal agreement between you and Research In Motion (RIM). In the event that you enter into a binding legal agreement with RIM, all provisions contained in such binding legal agreement shall apply, regardless of whether such provisions conflict with information contained herein.
©2008 Research In Motion Limited. All Rights Reserved. The BlackBerry and RIM families of related marks, images, and symbols are the exclusive properties of Research In Motion Limited. RIM, Research In Motion, BlackBerry, “Always On, Always Connected” and the “envelope in motion” symbol are registered with the U.S. Patent and Trademark Office and may be pending or registered in other countries.
Java is a trademark of Sun Microsystems, Inc. Microsoft, Windows, Visual Studio, and Visual C++ are trademarks of Microsoft Corporation. Intel and Pentium are trademarks of Intel Corporation. All other brands, product names, company names, trademarks and service marks are the properties of their respective owners.
The BlackBerry device and/or associated software are protected by copyright, international treaties, and various patents, including one or more of the following U.S. patents: 6,278,442; 6,271,605; 6,219,694; 6,075,470; 6,073,318; D445,428; D433,460; D416,256. Other patents are registered or pending in various countries around the world. Visit www.rim.com/patents.shtml for a current list of RIM [as hereinafter defined] patents.
This document is provided “as is” and Research In Motion Limited (RIM) assumes no responsibility for any typographical, technical, or other inaccuracies in this document. RIM reserves the right to periodically change information that is contained in this document; however, RIM makes no commitment to provide any such changes, updates, enhancements, or other additions to this document to you in a timely manner or at all. RIM MAKES NO REPRESENTATIONS, WARRANTIES, CONDITIONS, OR COVENANTS, EITHER EXPRESS OR IMPLIED (INCLUDING, WITHOUT LIMITATION, ANY EXPRESS OR IMPLIED
WARRANTIES OR CONDITIONS OF FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, MERCHANTABILITY, DURABILITY, TITLE, OR RELATED TO THE PERFORMANCE OR
NON-PERFORMANCE OF ANY SOFTWARE REFERENCED HEREIN, OR NON-PERFORMANCE OF ANY
SERVICES REFERENCED HEREIN). IN CONNECTION WITH YOUR USE OF THIS DOCUMENTATION, NEITHER RIM NOR THEIR RESPECTIVE DIRECTORS, OFFICERS, EMPLOYEES, OR CONSULTANTS SHALL BE LIABLE TO YOU FOR ANY DAMAGES WHATSOEVER BE THEY DIRECT, ECONOMIC, COMMERCIAL, SPECIAL, CONSEQUENTIAL, INCIDENTAL, EXEMPLARY, OR INDIRECT DAMAGES, EVEN IF RIM HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, INCLUDING, WITHOUT LIMITATION, LOSS OF BUSINESS REVENUE OR EARNINGS, LOST DATA, DAMAGES CAUSED BY DELAYS, LOST PROFITS, OR A FAILURE TO REALIZE EXPECTED SAVINGS.
This document might contain references to third-party sources of information and/or third-party web sites (“Third-Party Information”). RIM does not control, and is not responsible for, any Third-Party Information, including, without limitation, the content, accuracy, copyright compliance, legality, decency, links, or any other aspect of Third-Party Information. The inclusion of Third-Party Information in this document does not imply endorsement by RIM of the third party in any way. Any dealings with third parties, including, without limitation, compliance with applicable licenses, and terms and conditions are solely between you and the third party. RIM shall not be responsible or liable for any part of such dealings.
This document is accurate as of the product release date. For updated documentation, visit the BlackBerry Developer Zone: http://www.blackberry.com/developers.
Send us your comments on release notes and known issues lists:
https://www.blackberry.com/DocsFeedback.
About the Synchronization Server SDK
The Synchronization Server SDK allows corporations to create custom connectors to synchronize corporate backend databases over the wireless network with the BlackBerry device. The Synchronization Server provides an interface between these connectors and the Sync Agent of the BlackBerry device. The Synchronization Server SDK is composed of a sample custom connector, sample device code for wireless synchronization, BlackBerry Enterprise Server connector APIs, and Synchronization Server SDK
documentation.
Synchronization Server SDK system requirements
Important: Do not install the Synchronization Server SDK on a computer with a BlackBerry Enterprise Server. Unstable connectors and applications can cause data loss.
• Microsoft® Windows® 2000 Service Pack 4 or Microsoft Windows XP Service Pack 2
• Microsoft® Visual Studio® 2005 or Microsoft® Visual C++® 2005 Express Edition (download from the Microsoft web site at http://msdn.microsoft.com/vstudio/express/visualc/usingpsdk/)
• Intel® Pentium® III processor or compatible (800 MHz or higher) • 512 MB RAM
• 500 MB available hard disk space
• Java® SDK Version 1.5 (download from the Sun Microsystems web site at http://java.sun.com/) • BlackBerry Enterprise Server Version 4.1.2 or later (Required only if you intend to use the
ConnectorInstall utility to install a connector application)
• BlackBerry Device Simulator Package Version 4.2 or later, or the BlackBerry® Java® Development Environment Version 4.2 or later
• BlackBerry® Email and MDS Services Simulator Package Version 4.1.2.17 or later
Mapping a connector application to a database
In the registry, the SampleConnectorApp connector application points to the SyncSDKSample database. To change this registry setting, change the HKEY_LOCAL_MACHINE\SOFTWARE\Research In
Motion\BlackBerry Enterprise Server\Database\SDKDatabaseName registry key.
Testing with the Synchronization Server SDK
To test new applications created with the Synchronization Server SDK, you must install both the BlackBerry® MDS simulator and the BlackBerry Device Simulator on the same computer on which you installed the Synchronization Server.
The BlackBerry MDS Simulator is part of BlackBerry Email and MDS Services Simulator Package Version 4.1.2.17. You can download this version from the BlackBerry Developer Zone at
http://www.blackberry.com/developers/index.shtml.
Each version of the BlackBerry JDE comes with the BlackBerry device simulators that were available when that version of the BlackBerry JDE was made public. You can download the BlackBerry JDE or additional BlackBerry Device Simulators from the BlackBerry Developer Zone at
Testing environments
Environment Required components Description
Development Environment without the BlackBerry Enterprise Server
BlackBerry MDS simulator Version 4.1.2.17 or later and BlackBerry Device Simulator Version 4.2 or later
The Synchronization Server uses the BlackBerry MDS Simulator instead of the BlackBerry Enterprise Server and the BlackBerry® Infrastructure; the
BlackBerry Device Simulator runs the BlackBerry
application. Development Environment with the
BlackBerry Enterprise Server
BlackBerry Enterprise Server Version 4.1.2 or later, and one or more BlackBerry devices
The Syncrhonization Server uses the BlackBerry Enterprise Server; the BlackBerry device runs the BlackBerry application. Production Environment with the
BlackBerry Enterprise Server
BlackBerry Enterprise Server Version 4.1.2 or later, and one or more BlackBerry devices
The Syncrhonization Server uses the BlackBerry Enterprise Server; the BlackBerry device runs the BlackBerry application.
Documentation
The Synchronization Server SDK Development Guide is available on the BlackBerry Developer Zone web site at http://www.blackberry.com/developers.
Release notes
SampleConnectorApp connector application
SDR119725 The column name value from the SQL query is no longer appended to the m_sGetString
variable.
In previous releases, you needed a workaround including some specialized code to fix this problem.
ConnectorInstall application
SDR165768 The DLLs that are part of the Synchronization Server SDK can now be installed if the
BlackBerry Enterprise Server has multiple users.
Known issues
This section lists known issues for the Synchronization Server SDK Version 4.1.2.
BlackBerry Manager
When using the Synchronization Server SDK with a simulated USB-connected BlackBerry device, using the BlackBerry Manager to assign the simulated BlackBerry device to a user causes a dialog box to appear, displaying the following message: “An error occurred while assigning the device to the user. RPC parameters for the user’s server could not be retrieved.”
This dialog box is displayed erroneously.
Impact: When using the Synchronization Server SDK with a simulated USB-connected
BlackBerry device, in BlackBerry Manager, clicking Device Management > Assign the
device to assign a simulated BlackBerry device to a user erroneously displays an error
message.
Workaround: Do not use the Assign the device menu item in the BlackBerry Manager
to assign a BlackBerry device to a user. When you use BlackBerry Manager to add a user, BlackBerry Manager assigns a BlackBerry device to the user automatically.
SDR107335 Using BlackBerry Manager with the Synchronization Server SDK to send a message
causes a dialog box to appear, displaying the following message:
“Error has occurred while trying to send a message by PIN. RPC error detail: RPC Server is unavailable.”
This dialog box is displayed erroneously.
Impact: Clicking the Account > Send Message menu item when using the BlackBerry
Manager with the Synchronization Server SDK erroneously displays an error message.
Workaround: None.
When using the Synchronization Server SDK with a simulated USB connected BlackBerry device, using BlackBerry Manager to delete data from the simulated BlackBerry device does not work as expected.
Impact: When using the Synchronization Server SDK with a simulated USB-connected
BlackBerry device, in BlackBerry Manager, clicking IT Admin > Erase Data and
Disable Handheld does not delete existing data from the simulated BlackBerry device. Workaround: None.
Attempting to launch the BlackBerry Manager help file produces an error message stating that the bb_mgr.chm file cannot be found.
Impact: The help file for the BlackBerry Manager is not available for use. Workaround: None.
SDR116302 After you delete all data from the BlackBerry Device Simulator, attempting to activate an
existing user causes the BlackBerry Device Simulator to throw an IOException.
Impact: After you delete all data from the BlackBerry Device Simulator, attempting to
activate an existing user will cause the BlackBerry Device Simulator to throw an IOException and does not activate the user.
Workaround:
3. Activate the new user.
Synchronization Server SDK installation
If the Synchronization Server SDK installation process detects the BlackBerry Enterprise Server on the same computer you are installing the Synchronization Server SDK on, the installation process does not complete.
Impact: You cannot install the Synchronization Server SDK on a computer that has the
BlackBerry Enterprise Server installed.
Workaround: Install the Synchronization Server SDK on a computer that does not have
the BlackBerry Enterprise Server.
Removing the sample connector
When using ConnectorInstall to remove the Sample connector, the connector name is case-sensitive. You must specify the connector name as ‘Sample’; otherwise the removal process will not work as expected.
Impact: To use ConnectorInstall to remove the Sample connector, you must refer to the
sample connector as ‘Sample’. To remove the Sample connector, from a command prompt, type ConnectorInstall -u -n Sample.
Workaround: None.
Installing the SampleConnector.dll file
When using ConnectorInstall to install the SampleConnector.dll file, the installation process continues if you specify an incorrect installation path. An error message does not appear.
Impact: When you install the SampleConnector.dll, if you specify an incorrect
installation path, the installation process continues without informing you about the incorrect path information.
Workaround: Make sure you specify the correct installation path when you install the
