C-Unterprogramm-Schnittstelle YAPFAPI des FTP

Die C-Unterprogramm-Schnittstelle des FTP lehnt sich eng an die interaktive Schnittstelle an und wird durch die C-Funktion YAPFAPI realisiert. Das aufrufende Programm übergibt das FTP-Kommando als Zeichenkette an YAPFAPI. Als Ergebnis liefert YAPFAPI Meldung(en) des FTP-Servers sowie lokale Fehlerinformationen in entsprechende Puffer.

Möchte das aufrufende Programm die Ausgabe eines dir- oder ls-Kommandos nicht in eine Datei schreiben, sondern z.B. direkt interpretieren, so übergibt es mit dem Parameter dirCallBackFct (siehe unten) die Adresse einer entsprechenden Call-Back-Funktion mit folgender Signatur:

void dirCallBackFct(char *buffer, int bufLen);

Hierbei ist buffer ein Zeiger auf einen Puffer, der einen Teil der Ausgabe eines dir- bzw. ls-Kommandos enthält. buflen spezifiziert die Länge des Pufferinhalts.

Wenn bei TLS-gesicherten Verbindungen Client-Authentifizierung verwendet wird, kann das aufrufende Programm eine Passphrase für den privaten Schlüssel übergeben.

Beim Binden des Programms, das die FTP-Unterprogramm-Schnittstelle aufruft, müssen Nutzer der Unterprogramm-Schnittstelle, welche den Standard-C/C++- Compiler einsetzen, den Modul FTPAPI aus der folgenden Bibliothek hinzubinden:

SYSLIB.TCP-IP-AP.nnn SKUOML.TCP-IP-AP.nnn

(bei /390-Servern) (bei x86-Servern)

Außerdem muss die externe Referenz auf die benutzerdefinierte Exit-Routine aufgelöst werden (siehe Handbuch „interNet Services Administratorhandbuch“). Wenn Sie keine eigene Exit-Routine benötigen, können Sie hierfür den Dummy-Modul EXITFTP aus der folgenden Bibliothek verwenden:

SYSLNK.TCP-IP-AP.nnn SKMLNK.TCP-IP-AP.nnn

(bei /390-Servern) (bei x86-Servern)

Da der FTP-Unterprogramm-Modul aus C-Quelltexten produziert wurde, müssen außerdem die C-Laufzeitbibliotheken (CRTE) hinzugebunden werden.

Funktionsprototyp von YAPFAPI

Der Funktionsprototyp für den Unterprogramm-Aufruf lautet:

void YAPFAPI(struct YAPFAPI_pl_mdl *param)

param ist ein Zeiger auf eine Variable vom Typ struct YAPFAPI_pl_mdl.

Beschreibung der Struktur YAPFAPI_pl_mdl

Der nachfolgend beschriebene Datentyp struct YAPFAPI_pl_mdl ist in der Header-Datei YAPFAPI.H in der Bibliothek SYSLIB.TCP-IP-AP.nnn deklariert.

struct YAPFAPI_pl_mdl {
   struct {
       int version;                 /* Interface version                    */
       char *cmd;                   /* Contains command string              */
       char *serverMsg;             /* Buffer for server messages           */
       int maxServerMsgLen;         /* Length of buffer for server messages */
       char *localMsg;              /* Buffer for local messages            */
       int maxLocalMsgLen;          /* Length of buffer for local messages  */
       int combineMessages;         /* Write all messages into one buffer   */
       void (*dirCallBackFct)(char*, int);  /* Call back function */
       char *passPhrase;            /* Password for private key             */
       int passPhraseLen;           /* Length of password for private key   */
   } in_data;
   struct {
       int msgNumber;         /* Message number of last message from server */
       int serverMsgLen;      /* Length of messages from server             */
       int localMsgLen;       /* Length of local message                    */
       int rc;                /* Summary return code                        */
   } out_data;
}
/* Values for rc */
#define YAPFAPIrcOk                        0    /* Ok                      */
#define YAPFAPIrcVersionError              1    /* Wrong interface version */
#define YAPFAPIrcInitError                 2    /* Initialization Error    */
#define YAPFAPIrcLocalError                3    /* Local error             */
#define YAPFAPIrcFatalLocalError           4    /* Fatal local error       */
#define YAPFAPIrcRemoteError               5    /* Remote error            */

Beschreibung der Strukturelemente

version

Version der Schnittstelle. Dieser Parameter muss mit 1 versorgt werden.

cmd

Zeiger auf den null-terminierten Kommando-String, der das Kommando in derselben Syntax enthält, wie sie die interaktive Schnittstelle fordert (siehe Abschnitt „Kommandoübersicht (FTP-Client)“).

serverMsg

Zeiger auf einen vom Aufrufer bereitgestellten Puffer zur Aufnahme der Server-Meldungen.

maxServerMsgLen

Länge des Puffers, auf den serverMsg zeigt. Reicht die Puffergröße zur Aufnahme aller Meldungen nicht aus, dann werden die überzähligen Meldungen nur fragmentarisch oder überhaupt nicht ausgegeben.

localMsg

Zeiger auf einen vom Aufrufer bereitgestellten Puffer zur Aufnahme lokaler Meldungen.

maxLocalMsgLen

Länge des Puffers, auf den localMsg zeigt. Reicht die Puffergröße zur Aufnahme aller Meldungen nicht aus, dann werden die überzähligen Meldungen nur fragmentarisch oder überhaupt nicht ausgegeben.

combineMessages

Spezifiziert der Aufrufer für combineMessages einen von 0 verschiedenen Wert, dann werden sowohl Server-Meldungen als auch lokale Meldungen in dem von localMsg referenzierten Puffer bereitgestellt. Ein eigener Puffer für Server-Meldungen braucht in diesem Fall nicht bereitgestellt zu werden.

dirCallBackFct

Adresse einer Call-Back-Funktion. Soll keine Call-Back-Funktion verwendet werden, dann ist NULL zu spezifizieren.

passPhrase

Zeiger auf einen Puffer, der die Passphrase für den privaten Schlüssel enthält.

passPhraseLen

Länge der Passphrase

msgNumber

In msgNumber wird die Nummer der letzten Server-Meldung gemäß RFC 959 (FTP) zurückgeliefert.

serverMsgLen

Der in serverMsgLen zurückgelieferte Integer-Wert zeigt an, wie viele Zeichen aktuell in den durch serverMsg spezifizierten Puffer übertragen wurden.

localMsgLen

Der in localMsgLen zurückgelieferte Integer-Wert zeigt an, wie viele Zeichen aktuell in den durch localMsg spezifizierten Puffer übertragen wurden.

rc

In rc wird der insgesamt resultierende Return-Code zurückgeliefert.

Beispielprogramm für die Nutzung der FTP-Unterprogramm-Schnittstelle

Nachfolgend ist ein Beispielprogramm abgedruckt, das die FTP-Unterprogramm-Schnittstelle nutzt.

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include "yapfapi.h"
void printDir(char*, int);
main(int argc, char *argv[])
{
   struct YAPFAPI_pl_mdl param;
   char line[200];
   char serverMsg[2000];
   char localMsg[2000];
   FILE *fp_in;
   fp_in = fopen("(SYSDTA)", "r");
   for (;;) {
       printf("ftp> ");
       if (fgets(line, sizeof line, fp_in) == 0) 
           break;
       param.in_data.version = 1;
       param.in_data.cmd = line;
       param.in_data.serverMsg = serverMsg;
       param.in_data.maxServerMsgLen = sizeof(serverMsg);
       param.in_data.localMsg = localMsg;
       param.in_data.maxLocalMsgLen = sizeof(localMsg);
       param.in_data.combineMessages = 1;
       param.in_data.dirCallBackFct = &printDir;
       param.in_data.passPhrase = "ABCDEFGH";
       param.in_data.passPhraseLen = 8;
       YAPFAPI(&param);
       printf("Ret: msgNumber:    %d\n", param.out_data.msgNumber);
       if (param.out_data.serverMsgLen != 0)
          printf("Ret: serverMsgLen: %d\n", param.out_data.serverMsgLen);
       printf("Ret: localMsgLen:  %d\n", param.out_data.localMsgLen);
       if (param.out_data.serverMsgLen != 0) {
          serverMsg[param.out_data.serverMsgLen] = '\0';
          printf("Ret: serverMsg: \n");
          printf("%s", serverMsg);
          printf("Ret: serverMsgEnd\n");
       }
       localMsg[param.out_data.localMsgLen] = '\0';
       printf("Ret: localMsg: \n");
       printf("%s", localMsg);
       printf("Ret: localMsgEnd\n");
       printf("Ret: rc: %d\n", param.out_data.rc);
       if (param.out_data.rc == YAPFAPIrcInitError)
          break;
     }
}
void printDir(char* buffer, int bufLen)
{
   printf("%.*s", bufLen, buffer);
}