OLE-Steuerelemente einsetzen
am Beispiel von MAPI

Ralf Gladis

Bei OLE-Steuerelementen handelt es sich um Steuerelemente, die in OCX-Dateien gespeichert sind. Die Funktionalität dieser Steuerelemente wird nicht von Visual FoxPro zur Verfügung gestellt, sondern aus der OCX-Datei entnommen. Aus diesem Grund sind OLE-Steuerelemente ein beliebtes Instrument, um die Fähigkeiten von Visual FoxPro zu erweitern.

Die OLE-Steuerelemente stellen eine spezielle Klasse von Steuerelementen dar: Sie sind eigenständige Programmeinheiten, die keine andere Anwendung benötigen, um zu arbeiten. Jede OCX-Datei ist ein kleiner OLE-Server mit der Aufgabe, den Funktionsumfang von Visual FoxPro zu erweitern.

Einige OLE-Steuerelemente, die zum Lieferumfang von Visual FoxPro gehören, finden Sie in Tabelle 1. Die vier OLE-Steuerelemente installiert Visual FoxPro aber nur, wenn Sie ein 32Bit-Betriebssystem wie Windows NT oder Windows 95 einsetzen. Darüber hin­aus können Sie OCX-Dateien käuflich erwerben oder als Shareware bei CompuServe bzw. im Internet abrufen.

OCX-Datei Einsatzgebiet

MSCOMM32

Kommunikation über die serielle Schnittstelle

MSMAPI32

Schnittstelle zu MS Mail oder MS Exchange

MSOUTL32

Hierarchie-Darstellung von Listen analog zum Verzeichnisbaum des Datei-Managers

PICCLIP32

Faßt mehrere BMP-Dateien zusammen

Tabelle 1:              OLE-Steuerelemente von Visual FoxPro

Die CD zum Sybex-Buch enthält weitere OCX-Dateien. In den folgenden Abschnitten finden Sie eine kurze Beschreibung der OCX-Dateien von Visual FoxPro. Das OLE-Steuerelement MSMAPI32.OCX haben wir genauer unter die Lupe genommen und in die Projektdatenbank auf der CD integriert. Dort finden Sie die OLE-Steuer­elemente im Formular Kunden und in der Symbolleistenklasse tbStandard.

OLE-Steuerelemente registrieren

Bevor Sie die OLE-Steuerelemente verwenden können, müssen diese bei Visual FoxPro angemeldet werden. Um ein neues Steuerelement anzumelden, wählen Sie den Befehl Extras/Optionen und dann die Registerkarte Steuerelemente. Markieren Sie dort die Option OLE-Steuerelemente.

Um in der Liste ein neues Steuerelement hinzuzufügen, wählen Sie die Schaltfläche Hinzufügen. Im folgenden Dateiauswahldialog wählen Sie dann die OCX-Dateien aus. Danach erscheint das neue OLE-Steuer­element in der Liste. Damit das neue Steuerelement im Formulardesigner verfügbar ist, müssen Sie das entsprechende Kontrollkästchen ankreuzen.

Oft befinden sich automatisch installierte OCX-Dateien im Verzeichnis Windows\ System. Dort sollten Sie Ihre OLE-Steuer­elemente grundsätzlich ablegen. Insbesondere wenn Sie OLE-Steuer­elemente in Ihre Anwendung integrieren, sollten Sie dafür Sorge tragen,

Abbildung 1: OCX-Dateien melden Sie mit dem Befehl Extras/Optionen im Register Steuerelemente an

daß die OCX-Dateien im entsprechenden Verzeichnis des Anwenders landen.

Eine zweite Möglichkeit, OLE-Steuer­elemente zu registrieren, ist der bekannte Dialog Objekt einfügen. Wählen Sie dort die Option OLE-Steuerelemente einfügen. Hier ist der Vorgang sogar etwas übersichtlicher, da Visual FoxPro nur die OCX-Dateien anzeigt. Wünschen Sie weitere Elemente, so können Sie diese mit der Schaltfläche Steuerelemente hinzufügen anmelden. Wenn alle OCX-Dateien angemeldet sind, können Sie die Steuerelemente ganz normal einsetzen.

E-Mail mit MSMAPI32.OCX

Die Datei MSMAPI32.OCX enthält Steuerelmente, die FoxPro zum elektronischen Postboten befördern. Damit Visual FoxPro den E-Mail-Transport übernimmt, ist allerdings ein funktionstüchtiges Mail-system erforderlich.

Die OCX-Datei enthält zwei Steuerelemente, ein Steuerelement für MAPI-Sitzungen (MapiSession) und eins für den MAPI-Nachrichtenversand (MapiMessage). Ersteres erledigt die Anmeldung beim Mailsystem und das Download der E-Mails. Das zweite Steuerelement für MAPI-Nachrichten ist für den Versand von E-Mail-Nachrichten zuständig.

Abbildung 2: Damit ein FoxPro-Formular Mails versendet, legen Sie zwei unsichtbare OLE-Steuerelemente an und programmieren eine Schaltfläche mit den OCX-Funktionen

Um die Steuerelemente in einem Formular zu plazieren, klicken Sie in der Symbolleiste Formular-Steuerelemente auf das Symbol Klassen anzeigen und wählen dort die Option OLE-Steuerelemente aus. Daraufhin erscheinen Symbole für alle angemeldeten OCX-Dateien in der Symbolleiste.

Sitzung aufbauen

Zum Versenden einer E-Mail-Nachricht müssen Sie erst eine Anmeldung beim Mailsystem vornehmen. Dazu verwenden Sie das Steuerelement MapiSession, das für die An- und Abmeldung verantwortlich ist. Nach der Anmeldung enthält die SessionID-Eigenschaft die Kennung der MAPI-Sitzung, die an das zweite Steuerelement, MapiMessage, übergeben wird.

Die An- und Abmeldung erfolgt mit Hilfe der MapiSession-Methoden SignOn() und SignOff(). Mit der Eigenschaft LogonUI können Sie den Anmeldedialog für Benutzerkennung und Paßwort ein- (.T.) oder ausschalten (.F.). Sofern der Dialog ausgeschaltet wird, verwendet Visual FoxPro die Benutzerkennung und das Paßwort der Eigenschaften Password und UserName. Sollten diese nicht korrekt sein, kann die Sitzung nicht eingeleitet werden.

Um zu vermeiden, daß ein Nutzer mehrere Sitzungen anmeldet, stellen Sie die Eigenschaft NewSession auf den Wert .F.. Damit erreichen Sie, daß Visual FoxPro bei jedem weiteren Befehl die eingerichtete Sitzung benutzt. Durch den Einsatz mehrerer Steuerelemente können trotzdem mehrere Sitzungen genutzt werden.

Mit Hilfe der Eigenschaft DownloadMail legen Sie fest, ob beim Verbindungsaufbau das Download der eingegangenen E-Mails erfolgt (.T.). Das folgende Listing zeigt die Eröffnung einer Mapi-Sitzung, wie sie in der Projektdatenbank auf der CD benutzt wird.

IF ThisForm.oleMapiSession.SessionID=0       && Sitzung offen?
      ThisForm.oleMapiSession.LogonUI=.T.    && Mapi-Dialog ein
      ThisForm.oleMapiSession.DownloadMail=.F.  && Keine Mails holen
      ThisForm.oleMapiSession.SignOn()       && Anmeldung
      ThisForm.oleMapiMessage.SessionID=ThisForm.oleMapiSession.SessionID
EndIf

E-Mails versenden

Nachdem die Mail-Sitzung aufgebaut wurde, übernimmt das Steuerelement MapiMessages die nachrichtendienstlichen Funktionen: Mit Hilfe der Compose()-Methode wird eine Nachricht angelegt. Die Show()-Methode öffnet den Dialog Mail-Adreßbuch für die Auswahl der Empfänger. Mit Hilfe der Eigenschaften msgSubject und msgNoteText können Sie Texte in die Mail-Nachricht eintragen und mit der Send()-Methode versenden.

Zu diesem Zweck besitzt das Steuerelement MapiMessage die Methode AttachmentCount. Anschließend wird mit Hilfe der AttachmentType-Eigenschaft der Dateityp festgelegt, zum Beispiel 0 für Binärdateien. Übergeben Sie der Eigenschaft AttachmentPathName Verzeichnis- und Dateinamen der Datei. Jeder Dateianhang wird in der Mail wie ein Zeichen eingefügt. Deshalb können Sie mit der Eigenschaft AttachmentPosition die Position des Dateianhangs im Text festlegen.

Sie sollten die Eigenschaft AttachmentPosition verwenden, um die einzelnen Dateianhänge mit Bedacht zu positionieren, weil andernfalls die Gefahr besteht, daß jeder Anhang ein Zeichen löscht.

If ThisForm.oleMapiMessage.SessionID<>0      && Anmeldung ok?
      ThisForm.oleMapiMessage.Compose()      && Nachricht erstellen
      ThisForm.oleMapiMessage.Show()         && Empfänger-Dialog
      ThisForm.oleMapiMessage.msgSubject='Betreff'
      ThisForm.oleMapiMessage.msgNoteText='Nachricht'
      ThisForm.oleMapiMessage.Send(.T.)      && Sendedialog
EndIf

Grundsätzlich besitzt das Steuerelement MapiMessages vier Eigenschaftsbereiche: Adreßbuch-, Dateianlage-, Nachrichten- und Empfänger-Eigenschaften. Die Steuerung dieser Eigenschaften erfolgt anhand von Indizes: AttachmentIndex, MsgIndex und RecipIndex. Ändert sich der Indexwert in der Eigenschaft MsgIndex, werden alle anderen Nachrichten-, Dateianlagen- und Empfänger-Eigenschaften an die Merkmale der neuen Nachricht angepaßt. Die Adreßbucheigenschaften beschränken sich leider auf das Aussehen des Dialogfeldes Adreßbuch. Interessanter ist hingegen die Möglichkeit, die E-Mail-Nachricht mit einem Dateianhang zu versehen.

Jede E-Mail-Nachricht kann mehrere Dateianhänge versenden. Wenn Sie eine Datei an die Mail anhängen wollen, müssen Sie deshalb in der Eigenschaft AttachmentIndex an geben, welcher Dateianhang bearbeitet wird.

ThisForm.oleMapiMessage.AttachmentIndex = ; ThisForm.oleMapiMessage.AttachmentCount
ThisForm.oleMapiMessage.AttachmentType = 0
ThisForm.oleMapiMessage.PathName = 'Dateiname.xyz'
ThisForm.oleMapiMessage.AttachmentPosition=LEN(ThisForm.oleMessage.msgNoteText-1)

Das MAPI-Nachrichten-Steuerelememt ver­wendet zum Lesen und Verfassen von Nachrichten je einen Puffer. Der Lesepuffer ist nichts anderes als eine indizierte Gruppe von Nachrichten, die aus dem Posteingang eines Benutzers stammen. Wollen Sie auf eine dieser Nachrichten zugreifen, nutzen Sie die Einträge der Eigenschaft MsgIndex. Die Indizierung ist durchlaufend, beginnt allerdings bereits bei Null.

Um Nachrichten in den Lesepuffer zu bekommen, nutzen Sie die Methode Fetch(). Sie legt eine Nachrichtengruppe an und nimmt alle Nachrichten aus dem Posteingang auf, die dem in der Eigenschaft FetchMsgType entsprechen. Mit Hilfe der Eigenschaft FetchSorted können Sie die Nachrichten nach dem FIFO-Prinzip sortieren: First in, first out. Die Sortierung erfolgt also chronologisch in der Reihenfolge der Mail-Ankunft.

Den zweiten Puffer verwendet das Steuerelement MapiMessages zum Schreiben oder Bearbeiten von Nachrichten, den wir zur Vermeidung von Verwechslungen Arbeitspuffer nennen. Wenn Sie der Eigenschaft MsgIndex den Wert 1 zuweisen, wird der Arbeitspuffer aktiviert.

Achten Sie beim Ausführen der Aktionen darauf, daß der richtige Puffer aktiviert ist. Das Senden oder Speichern von Nachrichten dürfen Sie genau wie das Löschen von Empfängern nur im Arbeitspuffer durchführen. Um die aktuelle Nachricht vom Lesepuffer in den Arbeitspuffer zu kopieren, rufen Sie die Copy-Methode des Steuerelements MapiMessages auf:

ThisForm.MapiMessages.Copy

Hinweis: Bei diesem Artikel handelt es sich um einen Auszug des Buchs „Programmie ren mit Visual FoxPro 5.0“, erschienen beim Sybex Verlag