Die Komponente NCWebtoy.ASPHTM 1.5

Die Komponente NCWebToy.ASPHTM 1.5

Kurzbeschreibung

Das COM-Objekt "ASPHTM" kann beliebige HTTP-Objekte (also zum Beispiel ASP-Dateien) lesen und auf dem Server lokal speichern, oder eine Verbindung zu einem FTP-Server aufbauen und dort die Datei speichern. Diese Komponente eignet sich also hervorragend zum lokalen Speichern von dynamischen Seiten.

Das COM-Objekt befindet sich in einer dynamischen Bibliothek (DLL, Dynamic Link Library). Diese DLL muß nur einmal auf dem Server registriert werden, und schon kann sie von den verschiedensten Skript- und Programmiersprachen auf einfachste Weise benutzt werden, wie zum Beispiel von Visual Basic, Visual C++, Visual J++, ASP/VB-Skript, Windows Skripting Host.

Erfolgreich getestet wurde die Komponente unter folgender Konfiguration: Windows NT Workstation/Server 4.0, SP 4-6, Windows 2000 Professional und Server, Internet Information Server 4.0 und 5.0, Microsoft Personal Web Server.

Erläuterung der Eigenschaften und Methoden

Boolean WriteToFile (String Inputfile, String FormData, String OutputFile);	Die HTTP-Datei Inputfile (vollständiger URL) wird gelesen und auf dem Server unter den in Outputfile angegebenen Namen gespeichert. Der Parameter FormData kann eventuelle Post-Variablen enthalten, die dem Server beim Laden der Inputfile übergeben werden (zum Format siehe unten). Der Rückgabewert gibt an, ob der Aufruf erfolgreich war. Wird FALSE zurückgegeben, so beeinhalten ErrorCode und ErrorString die Fehlerinformationen.
String WriteToString (String Inputfile, String FormData);	Die HTTP-Datei Inputfile (vollständiger URL) wird gelesen und als String zurückgegeben. Der Parameter FormData kann eventuelle Post-Variablen enthalten, die dem Server beim Laden der Inputfile übergeben werden (zum Format siehe unten). ErrorCode gibt an, ob der Aufruf erfolgreich war.
String WriteToStringHTTPS (String Inputfile, String FormData);	Gleiche Arbeitsweise wie WriteToString, nur mit der Erweiterung, daß HTTPS-Objekte gelesen werden können.
Variant WriteToSaveArray (String Inputfile, String FormData);	Die HTTP-Datei Inputfile (vollständiger URL) wird gelesen und das Ergebnis in einem Byte-Array zurückgegeben. Zur Benutzbarkeit in ASP wurde der Rückgabetyp als VARIANT (VT_ARRAY \| VT_UI1) gewählt. Das Bytearray besitzt kein abschließendes Nullzeichen. Im Fehlerfall enthält das Array nur ein einzelnes Nullelement. Der Parameter FormData kann eventuelle Post-Variablen enthalten, die dem Server beim Laden der Inputfile übergeben werden (zum Format siehe unten). ErrorCode gibt an, ob der Aufruf erfolgreich war.
Boolean WriteToFTP (String Inputfile, String Outputfile, String FormData, Boolean Anonymous, String Username, String Password);	Die HTTP-Datei Inputfile (vollständiger URL) wird gelesen und in die FTP-Datei Outputfile geschrieben. Hierbei ist zu beachten, daß der Parameter Outputfile einen vollständigen FTP-Pfad enthalten muß. Der Parameter Anonymous gibt an, ob die Anmeldung an den FTP-Server anonym erfolgen soll. Ist Anonymous = TRUE, so werden die Parameter Username und Password ignoriert. Der Parameter FormData kann eventuelle Post-Variablen enthalten, die dem Server beim Laden der Inputfile übergeben werden (zum Format siehe unten). Der Rückgabewert der Methode gibt an, ob der Aufruf erfolgreich war. Wird FALSE zurückgegeben, so beeinhalten ErrorCode und ErrorString die Fehlerinformationen.
Boolean Execute (String Inputfile, String FormData);	Die HTTP-Datei Inputfile (vollständiger URL) wird gelesen, der Inhalt wird aber nicht gespeichert oder zurückgegeben. Der Parameter FormData kann eventuelle Post-Variablen enthalten, die dem Server beim Laden der Inputfile übergeben werden (zum Format siehe unten). Diese Methode eignet sich zum Aufruf von ASP-Seiten, die nichts zurückgeben.
String GetHeader (String URL, Long HeaderType Long HeaderIndex);	Von der angegebenen URL wird der in HeaderType angegegebene Teil des Header gelesen und als String zurückgegeben. (Mögliche Konstanten für HeaderType siehe unten.) HeaderIndex gibt dabei den Index des zu lesenden Headers an (0-basiert). Anwendungsfall: Soll beispielsweise ein Link auf Gültigkeit überprüft werden, so kann dies wie folgt geschehen: Der Aufruf GetHeader("http://www.netcomplett.de/not-exist.htm") liefert den String "404" zurück (File not found).
String GetCustomHeader (String URL, String HeaderName Long HeaderIndex);	Von der angegebenen URL wird in HeaderName angegebene Header gelesen und als String zurückgegeben. HeaderIndex gibt dabei den Index des zu lesenden Headers an (0-basiert).
AddRequestHeaders (String Headers, short Flag);	Diese Methode setzt Headerdaten, die bei jedem nachfolgenden Abruf von HTTP-Objekten an den Server übergeben werden. Der Flag-Parameter steuert die Wirkungsweise der Headerdaten: Flag = 0: Fügt die neuen Header zu und ersetzt notfalls bestehende gleichnamige Header (Standardwert) (HTTP_ADDREQ_FLAG_REPLACE \| HTTP_ADDREQ_FLAG_ADD) Flag = 1: Fügt Headerdaten nur hinzu, es werden keine bestehende Headerdaten ersetzt.(HTTP_ADDREQ_FLAG_ADD) Flag = 2: Fügt Headerdaten nur dann hinzu, wenn sie neu sind. (HTTP_ADDREQ_FLAG_ADD_IF_NEW)
ResetAllRequestHeaders ();	Setzt die in AddRequestHeader gesetzten Headerinformationen zurück auf die Standardwerte, das Flag wird wieder auf 0 gesetzt.
Boolean ChangeProxySettings (Integer ProxyType, String ProxyAddress, String ProxyBypass);	Definiert, ob die Verbindungen zum Internet durch einen Proxyserver erfolgen sollen. ProxyType kann einen der folgenden Werte annehmen: 0 (Proxyeinstellungen werden aus Registry gelesen, identisch mit Einstellungen im Internet Explorer 4.0), 1 (direkte Verbindung zum Internet), 2 (Verbindung über einen Proxyserver aufbauen). Ist ProxyType = 0 oder 1, so sind die letzten beiden Parameter ohne Bedeutung. Im Falle ProxyType = 2 gibt ProxyAddress den vollständigen Namen / die IP-Adresse des Proxyservers an, eventuell mit Port, und ProxyBypass enthält eine Liste von Adressen, für die kein Proxyserver verwendet wird (Trennung durch Semikolon). Wird diese Methode nicht aufgerufen, so werden die Einstellungen aus der Registry genutzt (ProxyType = 0).
SetAgentName (String NewAgentName);	Diese Methode setzt den Agentnamen (Browserbezeichnung), den die Komponente beim Lesen von allen weiteren HTTP-Objekten angibt. Der Standardwert ist ASPHTM.
ErrorCode (Long)	Stellt den Fehlercode des letzten Methodenaufrufs dar (0 = Kein Fehler).
ErrorString (String)	Stellt die Fehlerbeschreibung des letzten Methodenaufrufs dar.

Format für den Parameter FormData

In allen Methoden muß der Parameter FormData URL-Encoded übergeben werden. Sollen beispielsweise die folgenden drei Parameter mittels POST an Inputfile übergeben werden, so ist für FormData der folgende String anzugeben:

name= "netcomplett", address = "Fiete Schulze", etc = "K&L"
FormData: "name=netcomplett&address=Fiete+Schulze&etc=K%26L"

Mögliche Werte für den Parameter HeaderType der Methode GetHeader

Konstante	Wert	Konstante	Wert
HTTP_QUERY_MIME_VERSION	0	HTTP_QUERY_ACCEPT	24
HTTP_QUERY_CONTENT_TYPE	1	HTTP_QUERY_ACCEPT_CHARSET	25
HTTP_QUERY_CONTENT_TRANSFER_ENCODING	2	HTTP_QUERY_ACCEPT_ENCODING	26
HTTP_QUERY_CONTENT_ID	3	HTTP_QUERY_ACCEPT_LANGUAGE	27
HTTP_QUERY_CONTENT_DESCRIPTION	4	HTTP_QUERY_AUTHORIZATION	28
HTTP_QUERY_CONTENT_LENGTH	5	HTTP_QUERY_CONTENT_ENCODING	29
HTTP_QUERY_CONTENT_LANGUAGE	6	HTTP_QUERY_FORWARDED	30
HTTP_QUERY_ALLOW	7	HTTP_QUERY_FROM	31
HTTP_QUERY_PUBLIC	8	HTTP_QUERY_IF_MODIFIED_SINCE	32
HTTP_QUERY_DATE	9	HTTP_QUERY_LOCATION	33
HTTP_QUERY_EXPIRES	10	HTTP_QUERY_ORIG_URI	34
HTTP_QUERY_LAST_MODIFIED	11	HTTP_QUERY_REFERER	35
HTTP_QUERY_MESSAGE_ID	12	HTTP_QUERY_RETRY_AFTER	36
HTTP_QUERY_URI	13	HTTP_QUERY_SERVER	37
HTTP_QUERY_DERIVED_FROM	14	HTTP_QUERY_TITLE	38
HTTP_QUERY_COST	15	HTTP_QUERY_USER_AGENT	39
HTTP_QUERY_LINK	16	HTTP_QUERY_WWW_AUTHENTICATE	40
HTTP_QUERY_PRAGMA	17	HTTP_QUERY_PROXY_AUTHENTICATE	41
HTTP_QUERY_VERSION	18	HTTP_QUERY_ACCEPT_RANGES	42
HTTP_QUERY_STATUS_CODE	19	HTTP_QUERY_SET_COOKIE	43
HTTP_QUERY_STATUS_TEXT	20	HTTP_QUERY_COOKIE	44
HTTP_QUERY_RAW_HEADERS	21	HTTP_QUERY_REQUEST_METHOD	45
HTTP_QUERY_RAW_HEADERS_CRLF	22	HTTP_QUERY_REFRESH	46
HTTP_QUERY_CONNECTION	23	HTTP_QUERY_CONTENT_DISPOSITION	47

HTTP 1.1 defined headers
HTTP_QUERY_AGE	48	HTTP_QUERY_IF_RANGE	58
HTTP_QUERY_CACHE_CONTROL	49	HTTP_QUERY_IF_UNMODIFIED_SINCE	59
HTTP_QUERY_CONTENT_BASE	50	HTTP_QUERY_MAX_FORWARDS	60
HTTP_QUERY_CONTENT_LOCATION	51	HTTP_QUERY_PROXY_AUTHORIZATION	61
HTTP_QUERY_CONTENT_MD5	52	HTTP_QUERY_RANGE	62
HTTP_QUERY_CONTENT_RANGE	53	HTTP_QUERY_TRANSFER_ENCODING	63
HTTP_QUERY_ETAG	54	HTTP_QUERY_UPGRADE	64
HTTP_QUERY_HOST	55	HTTP_QUERY_VARY	65
HTTP_QUERY_IF_MATCH	56	HTTP_QUERY_VIA	66
HTTP_QUERY_IF_NONE_MATCH	57	HTTP_QUERY_WARNING	67

In der Datei ncwebtoy.inc sind diese Konstanten für die Benutzung in ASP vordefiniert.

Auswahl möglicher Fehlermeldungen

Beispiel-URL, der Fehler erzeugt	ErrorCode	ErrorString
htt://www.abc.com	12006	Der URL verwendet kein bekanntes Protokoll.
ftp://xxx.xxx.com	12007	Der Servername oder die Serveradresse konnte nicht verarbeitet werden.
http:\\www.abc.com	12018	Der Typ der gelieferten Zugriffsnummer entspricht nicht dem angeforderten Vorgang.
http://not-existing.com	12029	Die Serververbindung konnte nicht hergestellt werden.
Unberechtigter FTP- Schreibzugriff	12003	Zugriff wurde verweigert.
Aufruf von WriteToFTP mit falschem Username/Password.	12014	Das Kennwort war unzulässig.

Anwendungsbeispiele

Im folgenden werden Beispielquellcodes für die Benutzung der Komponente in den Programmiersprachen Visual Basic, Visual J++, sowie ASP/VB-Skript und Windows Skripting Host. Dabei wird in allen Beispielen jeweils eine HTML-Datei geladen und lokal gespeichert (mittels WriteToFile); anschließend wird eine Datei auf einem FTP-Server gespeichert.

Microsoft Visual Basic

Nachdem über den Menüpunkt Projekt/Verweise die DLL "ncwebtoy.dll" dem Projekt hinzugefügt wurde, kann das COM-Objekt wie folgt benutzt werden:

Dim Konverter As ASPHTM
Set Konverter = New ASPHTM
Konverter.WriteToFile "http://www.netcomplett.de/index.asp", "",
"c:\index.html"
Konverter.WriteToFTP "http://www.netcomplett.de/default.html",
"ftp://www.netcomplett.de/test.html", "", FALSE, "ftpuser",
"ftp_pw"

Microsoft Visual J++ 6.0

Über den Menüpunkt Projekt/COM-Wrapper hinzufügen... wird die Datei "ncwebtoy.dll" ausgewählt. Anschließend kann die Komponente wie folgt erzeugt und benutzt werden:

ncwebtoy.ASPHTM Konverter = new ncwebtoy.ASPHTM();
Konverter.WriteToFile("http://pluto/testweb/asphtm.asp", "", 
"c:\\testqwe.html");
Konverter.WriteToFTP("http://www.netcomplett.de/default.html",
"ftp://www.netcomplett.de/test.html", "", FALSE, "ftpuser",
"ftp_pw");

Active Server Pages - ASP

<%
Set Konverter = Server.CreateObject ("NCWebToy.ASPHTM")
Konverter.WriteToFile "http://www.netcomplett.de/index.asp", "",
"c:\index.html"
Konverter.WriteToFTP "http://www.netcomplett.de/default.html",
"ftp://www.netcomplett.de/test.html", "", FALSE, "ftpuser",
"ftp_pw"
%>

Microsoft Skripting Host

Set Konverter = CreateObject ("NCWebToy.ASPHTM")
Konverter.WriteToFile "http://www.netcomplett.de/index.asp", "",
"c:\index.html"
Konverter.WriteToFTP "http://www.netcomplett.de/default.html",
"ftp://www.netcomplett.de/test.html", "", FALSE, "ftpuser",
"ftp_pw"

Installation der Komponente

Zur Installation der Komponente sind folgende Schritte nötig:

Kopieren der Datei "ncwebtoy.dll" in das Verzeichnis "c:\winnt\system32". Bemerkung: Hier kann auch ein anderes Verzeichnis gewählt werden.
Aufrufen von "regsvr32 c:\winnt\system32\ncwebtoy.dll".
Erfolgsmeldung: "DllRegisterServer in ncwebtoy.dll succeeded."

Benötigte Laufzeitbibliotheken

Von der Komponente werden folgende Standardbibliotheken (Dynamic Link Libraries) des Betriebssystems (hier: Windows NT 4.0) benötigt: Kernel32.dll, User32.dll, Gdi32.dll, Comdlg32.dll, Winspool.drv, Advapi32.dll, Shell32.dll, Comctl32.dll, Oledlg.dll, Ole32.dll, Oleaut32.dll und Wininet.dll.

Die Komponente im Vergleich zur Java-Komponente IISSample.Asp2Htm

Mit dem Microsoft Internet Information Server 4.0 wird das in Java geschriebene COM-Objekt "IISSample.Asp2Htm" geliefert. Diese Komponente besitzt auch die Möglichkeit, dynamische HTTP-Seiten lokal auf dem Server zu speichern. Der entscheidende Nachteil dieser Komponente ist, daß vor jeder Benutzung dieses COM-Objektes zuerst die Java Virtual Machine auf dem Server gestartet werden muß, die dann den Bytecode der Java-Klassendatei analysiert und ausführt.
Dagegen wird zur Ausführung von ASPHTM 1.4 keine Virtual Machine benötigt, da die Komponente in kompilierter Form (DLL) vorliegt. Somit ergeben sich erhebliche Geschwindigkeitsvorteile bei der Benutzung von ASPHTM 1.4.
Weiterhin besitzt "IISSample.Asp2Htm" nicht die Funktionalität, Dateien auf einem FTP-Server zu speichern.

FAQ

Q1. Bei der Benutzung des COM-Objektes tritt die Fehlermeldung "Objekterstellung durch ActiveX-Komponente nicht möglich" auf.

A1. Die Komponente muß im System registriert werden, z.B. durch den Aufruf "regsvr32 c:\winnt\system32\ncwebtoy.dll", gegebenenfalls muß der Pfad entsprechend angepaßt werden. Es ist darauf zu achten, daß als Erfolgsmeldung "DllRegisterServer in asptohtm.dll succeeded." ausgegeben wird.

Q2. Welche Schritte sind nötig, um die Komponente wieder vollständig aus dem System zu entfernen ? (Windows NT meldet "Der Zugriff wurde verweigert." beim Versuch, die Datei asptohtm.dll zu löschen.)

A2. Die DLL läßt sich nur dann aus dem System entfernen, wenn sie von keinem laufenden Prozeß mehr benutzt wird. Zur Deinstallation muß also zuerst sichergestellt werden, daß kein Programm diese DLL momentan benutzt. Wird die Komponente in einem (serverseitigem) ASP-Skript verwendet, so muß der Webserver (z.B. Internet Information Server oder Personal Web Server) eine Instanz dieser Komponente erstellen; die allerdings nicht sofort freigegeben wird, nachdem alle HTTP-Verbindungen zu diesem Webserver abgebrochen werden. Somit ist es in Einzelfällen nötig, den Webserver anzuhalten (z.B. Beenden des IIS-Administrationsdienstes und des WWW-Publishing-Dienstes). Erst dann werden alle noch vorhandenen Instanzen des COM-Objektes freigegeben, und die DLL läßt sich aus dem System entfernen.
Dieses Vorgehen kann immer dann angewendet werden, wenn die Komponente durch eine neuere Version ersetzt werden soll (Update). Bei diesem Update-Prozeß ist es nicht nötig, die neue Komponente erneut im System zu registrieren (mittels regsvr32), wenn sich die neue DLL im gleichen Pfad wie die alte befindet.
Soll die Komponente dauerhaft aus dem System entfernt werden, so ist vor dem Löschen die Registrierung im System rückgängig zu machen (mittels regsvr32 –u c:\winnt\system32\ncwebtoy.dll). Schlägt dieser Aufruf fehl, so muß die DLL per Hand aus der Registry entfernt werden. Dazu ist mittels regedit oder regedt32 die Registry zu öffnen und es sind folgende vier Schlüssel samt Unterschlüssel zu löschen:

Arbeitsplatz\HKEY_CLASSES_ROOT\NCWebToy.ASPHTM
Arbeitsplatz\HKEY_CLASSES_ROOT\NCWebToy.ASPHTM.1
Arbeitsplatz\HKEY_CLASSES_ROOT\CLSID\{E4E7B3D3-061F-11D4-BE17-00105AD5EC68}
Arbeitsplatz\HKEY_CLASSES_ROOT\TypeLib\{E4E7B3C1-061F-11D4-BE17-00105AD5EC68}

Alle vier Schlüssel können leicht durch Suchen der Zeichenkette "NCWebToy" gefunden werden.

Q3. Bei der Benutzung des Internet Information Server 4.0 tritt bei der Verwendung der Komponente in ASP-Dateien in seltenen Fällen der Fehler "Serverseitige Exception aufgetreten." auf. Wie kann dieses Verhalten umgangen werden ?

A3. Überprüfen Sie in der Microsoft Management Konsole, ob die Einstellungen für das entsprechende Web korrekt sind.

Im Internet Information Server: Rechter Mausklick auf das entsprechende Web, Auswahl "Eigenschaften".

Dann "Basisverzeichnis" -> "Konfiguration" -> "Debuggen der Anwendung".

Weder serverbasiertes, noch clientbasiertes ASP-Skript-Debuggen darf aktiviert sein.

Alle vorgenommenen Änderungen speichern.

Support

Bei Fragen oder Anregungen können Sie eine E-Mail an support{ at }netcomplett.de senden.

Download

Komponente: Sie erhalten damit eine Vollversion zur uneingeschränkten Nutzung.

Beschränkte Garantie

NETCOMPLETT GIBT KEINE GARANTIE ZUR EIGNUNG DER SOFTWARE FÜR EINEN BESTIMMTEN ZWECK. DIESE BESCHRÄNKTE GARANTIE IST AUSSCHLIESSLICH UND ANSTELLE ALLER ANDEREN GARANTIEN, SOWOHL AUSDRÜCKLICHER ALS AUCH IMPLIZIERTER ART, EINSCHLIESSLICH DER IMPLIZIERTEN GARANTIE DER VERKÄUFLICHKEIT, DER EIGNUNG FÜR EINEN BESTIMMTEN ZWECK UND DER NICHTÜBERTRETUNG. DA DIESE SOFTWARE KOSTENLOS IST, HAFTET NETCOMPLETT NICHT FÜR IRGENDWELCHE SCHÄDEN, DIE BENUTZERN DIESER SOFTWARE ENTSTEHEN KÖNNEN. NETCOMPLETT BIETET FÜR DIESE SOFTWARE KEINERLEI UNTERSTÜTZUNG UND WIRD AUCH KEINE UPDATES DER SOFTWARE VORNEHMEN.

Haftungsausschluß

UNABHÄNGIG DAVON, OB EINES DER HIERIN DARGELEGTEN RECHTSMITTEL SEINEN WESENTLICHEN ZWECK NICHT ERFÜLLT, IST NETCOMPLETT IN KEINEM FALLE ERSATZPFLICHTIG FÜR IRGENDWELCHE INDIREKTEN, FOLGE- ODER ÄHNLICHEN SCHÄDEN (EINGESCHLOSSEN SIND SCHÄDEN AUS ENTGANGENEM GEWINN ODER VERLUST VON DATEN), DIE AUFGRUND DER BENUTZUNG DER SOFTWARE ODER DER UNFÄHIGKEIT, DIE SOFTWARE ZU VERWENDEN, ENTSTEHEN, SELBST WENN NETCOMPLETT VON DER MÖGLICHKEIT SOLCHER SCHÄDEN UNTERRICHTET WORDEN IST.