Article # 156, added by Geoworks, historical record
| first |
previous |
index |
next |
last |
Making your application FileTransfer friendly.
If you're writing a Nokia 9000 application that creates, views, edits, or otherwise opens documents, here are a couple of things that need to happen for those documents to be properly transferred to and from a PC through the connectivity application while your app is accessing the files. Briefly, the way that the connectivity apps transfer files is this: an initial attempt is made to FileOpen the document in question with Read/Write and deny Read/Write permissions; if the file isn't currently in use by one of the other applications in memory, then this FileOpen should succeed, and the transfer will commence. However, if another application has the file open, the FileOpen will error with ERROR_SHARING_VIOLATION. At this point, the connectivity app will attempt to contact that particular application and ask that it relinquish its hold on the file long enough to complete the transfer. The way it does this is to look up the file in the document registry for an owner of the file. If your application has a file open and *doesn't* register the file by calling IACPRegisterDocument, then there will be no way for the connectivity app to contact your application, and the transfer of that particular document will fail. This, then, is the first requirement: * If your application opens any file that could potentially be * transferred by the connectivity apps (which is basically everything * under the DOCUMENT directory, the contact database, and calendar * data), then it needs to register those files with the document * registry via IACPRegisterDocument. Once the connectivity app connects with your app, it'll send a MSG_META_IACP_ALLOW_FILE_ACCESS and wait for your app to process the message before it tries opening the file again. The second requirement, then: * Your application must handle MSG_META_IACP_ALLOW_FILE_ACCESS * to close the file in question down. Or, you can add the hint * HINT_APPLICATION_QUIT_ON_IACP_ALLOW_FILE_ACCESS to your app * object, which should cause your application to transparently * detach, which will hopefully close any files it had open. When the connectivity application is finished transferring the document, it sends MSG_META_IACP_NOTIFY_FILE_ACCESS_FINISHED over the same connection to let the app know that it's OK to reopen the file, if it hadn't shutdown in the first place. If it had shut down, then you need to gracefully handle the case where your data file changes between sessions. * Your application must not save information to its state file * that might cause problems if a data file disappears, appears, * or changes in any other way between sessions.