Click here to view and discuss this page in DocCommentXchange. In the future, you will be sent there automatically.

SQL Anywhere 11.0.1 (Deutsch) » UltraLite - C- und C++-Programmierung » API-Referenz » UltraLite C/C++ - Gemeinsame API-Referenz

 

MLFileTransfer-Funktion

Lädt eine Datei von einem MobiLink-Server über die MobiLink-Schnittstelle herunter

Syntax
ul_bool MLFileTransfer ( ml_file_transfer_info * info );                                  
Parameter

info   Eine Struktur mit den Informationen für die Dateiübertragung

Parameter der ML-Dateiübertragung

Die Parameter der ML-Dateiübertragung sind Mitglieder einer Struktur, die als Parameter an die Funktion MLFileTransfer übergeben werden. Die Struktur ml_file_transfer_info ist in einer Header-Datei mit dem Namen mlfiletransfer.h festgelegt. Die einzelnen Felder der Struktur werden wie folgt festgelegt:

filename   Erforderlich. Der Name der Datei, die vom Server übertragen werden soll, auf dem MobiLink ausgeführt wird. MobiLink durchsucht zuerst das Benutzername-Unterverzeichnis und anschließend das Stammverzeichnis. Weitere Hinweise finden Sie unter Option -ftr.

Wenn die Datei nicht gefunden wird, wird im Fehlerfeld ein Fehler angezeigt. Der Dateiname darf keine Laufwerks- oder Pfadinformationen enthalten, da MobiLink ihn sonst nicht findet.

dest_path   Der lokale Pfad, in dem die heruntergeladene Datei gespeichert werden soll. Wenn dieser Parameter leer ist (Standard), wird die heruntergeladene Datei im aktuellen Verzeichnis gespeichert.

  • Unter Windows Mobile wird die Datei im Stammverzeichnis (\) des Geräts gespeichert, wenn dest_path leer ist.

  • Auf dem PC wird die Datei im aktuellen Benutzerverzeichnis gespeichert, wenn dest_path leer ist.

  • Wenn Sie unter Palm OS auf den externen Speicher des Geräts herunterladen, stellen Sie dest_path die Angabe vfs: voran. Der Pfad muss dann unter Berücksichtigung der plattformspezifischen Namenskonventionen angegeben werden. Weitere Hinweise finden Sie unter Palm OS.

    Wenn das Feld dest_path leer ist, geht MLFileTransfer davon aus, dass eine Palm-Datenbank (.pdb) heruntergeladen wird.

dest_filename   Der lokale Name der heruntergeladenen Datei. Wenn dieser Parameter leer ist, wird der Wert in "filename" verwendet.

stream   Erforderlich. Das Protokoll kann eines der folgenden sein: TCPIP, TLS, HTTP oder HTTPS. Weitere Hinweise finden Sie unter Synchronisationsparameter Stream Type.

stream_parms   Die Protokolloptionen für einen bestimmten Datenstrom. Weitere Hinweise finden Sie unter Netzwerkprotokolloptionen für UltraLite-Synchronisationsdatenströme.

username   Erforderlich. MobiLink-Benutzername.

password   Das Kennwort für den MobiLink-Benutzernamen

version   Erforderlich. Die MobiLink-Skriptversion

observer   Eine Callback-Funktion kann bereitgestellt werden, um den Fortschritt des Datei-Downloads über das Feld "observer" zu beobachten. Weitere Hinweise finden Sie in der Beschreibung der Callback-Funktion.

user_data   Die anwendungsspezifischen Informationen, die der Synchronisations-Beobachtungsfunktion bereitgestellt werden. Weitere Hinweise finden Sie unter Synchronisationsparameter User Data.

force_download   Hat den Wert TRUE, wenn die Datei auch dann heruntergeladen werden soll, wenn der Zeitstempel darauf hinweist, dass sie bereits vorhanden ist. Der Wert ist FALSE, wenn die Datei nur heruntergeladen wird, wenn die Serverversion und die lokale Version unterschiedlich sind. In diesem Fall überschreibt die Serverversion der Datei die Clientversion. Eine ältere Datei mit diesem Namen auf dem Client wird entfernt, bevor die Datei heruntergeladen wird. MLFileTransfer vergleicht die Server- und Clientversion der Datei, indem ein kryptografischer Hash-Wert für jede Datei berechnet wird. Die Hash-Werte sind nur dann identisch, wenn die Dateien inhaltlich identisch sind.

enable_resume   Wenn auf TRUE gesetzt, nimmt MLFileTransfer einen vorangegangenen Download wieder auf, der aufgrund eines Verbindungsfehlers oder eines Abbruchs durch den Benutzer unterbrochen wurde. Wenn die Datei auf dem Server neuer ist als die lokale Teildatei, wird die Teildatei entfernt und die neue Version in ihrer Gesamtheit heruntergeladen. Der Parameter force_download hat Vorrang vor diesem Parameter.

num_auth_parms   Die Anzahl der Authentifizierungsparameter, die an die Authentifizierungsparameter in MobiLink-Ereignissen übergeben werden. Weitere Hinweise finden Sie unter Synchronisationsparameter Number of Authentication Parameters.

auth_parms   Stellt Authentifizierungsparametern in MobiLink-Ereignissen Parameter bereit. Weitere Hinweise finden Sie unter Synchronisationsparameter Authentication Parameters.

downloaded_file   Hat einen der folgenden Werte:

  • 1- Die Datei wurde erfolgreich heruntergeladen.

  • 0- Es ist ein Fehler aufgetreten. Ein Fehler tritt auf, falls die Datei bereits aktuell ist, wenn MLFileTransfer aufgerufen wird. In diesem Fall gibt die Funktion TRUE anstelle von FALSE zurück. Auf Palm OS lädt MLFileTransfer die Datei beim Download einer Datenbankdatei (.pdb) immer herunter, unabhängig davon, ob die Datei aktuell ist oder nicht.

auth_status   Gibt Auskunft über den Status der MobiLink-Benutzerauthentifizierung. Der MobiLink-Server gibt diese Information an den Client weiter. Weitere Hinweise finden Sie unter Synchronisationsparameter Authentication Status.

auth_value   Gibt Auskunft über die Ergebnisse eines benutzerdefinierten Benutzerauthentifizierungsskripts in MobiLink. Der MobiLink-Server gibt diese Information an den Client weiter. Weitere Hinweise finden Sie unter Synchronisationsparameter Authentication Value.

file_auth_code   Enthält den Rückgabecode des optionalen Skripts authenticate_file_transfer auf dem Server

error   Enthält Informationen über jeden auftretenden Fehler

Rückgabe
  • ul_true   Die Datei wurde erfolgreich heruntergeladen.

  • ul_false   Der Download der Datei war nicht erfolgreich. Sie können im Fehlerfeld der Struktur ml_file_transfer_info Fehlerinformationen angeben. Unvollständige Dateiübertragungen können wieder aufgenommen werden.

Bemerkungen

Sie müssen den Quellspeicherort der zu übertragenden Datei angeben. Dieser Speicherort muss als Verzeichnis eines MobiLink-Benutzers auf dem MobiLink-Server (oder im Standardverzeichnis auf diesem Server) festgelegt sein. Sie können auch den gewünschten Zielspeicherort und den Namen der Datei angeben.

Sie können z.B. Ihre Anwendung so programmieren, dass sie eine neue Datenbank oder eine Ersatzdatenbank vom MobiLink-Server herunterlädt. Sie können die Datei für bestimmte Benutzer anpassen, da der erste Speicherort, der durchsucht wird, das Unterverzeichnis eines bestimmtes Benutzers ist. Sie können auch eine Standarddatei im Stammverzeichnis auf dem Server verwalten, da dieser Speicherort verwendet wird, wenn die betreffende Datei im Benutzerverzeichnis nicht gefunden wird.

Callback-Funktion

Die Callback-Funktion zur Beobachtung des Fortschritts der Dateiübertragung über den observer-Parameter hat den folgenden Prototyp:

typedef void(*ml_file_transfer_observer_fn)( ml_file_transfer_status * status );

Das an die Callback-Funktion übergebene ml_file_transfer_status-Objekt wird wie folgt definiert:

typedef struct ml_file_transfer_status {
    asa_uint64                  file_size;
    asa_uint64                  bytes_received;
    asa_uint64                  resumed_at_size;
    ml_file_transfer_info_a *   info;
    asa_uint16                  flags;
    asa_uint8                   stop;
} ml_file_transfer_status;

file_size   Die Gesamtgröße der heruntergeladenen Datei in Byte

bytes_received   Gibt an, wie viele Dateien bislang heruntergeladen wurden, einschließlich Dateien aus früheren Synchronisationen, falls der Download wieder aufgenommen wurde.

resumed_at_size   Wird zusammen mit der Download-Wiederaufnahme verwendet und gibt an, an welchem Punkt der aktuelle Download wieder aufgenommen wurde

info   Zeigt auf das Informationsobjekt, das MLFileTransfer übergeben wurde. Sie können über diesen Zeiger auf den Parameter user_data zugreifen.

flags   Stellt zusätzliche Informationen bereit. Der Wert MLFT_STATUS_FLAG_IS_BLOCKING wird gesendet, wenn MLFileTransfer bei einem Netzwerkaufruf blockiert wird, und der Download-Status sich seit dem letzten Aufruf der Beobachtungsfunktion nicht geändert hat.

stop   Kann auf TRUE gesetzt werden, um den aktuellen Download abzubrechen. Sie können den Download durch einen nachfolgenden Aufruf von MLFileTransfer wieder aufnehmen, doch nur dann, wenn der Parameter enable_resume gesetzt wurde.