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.