Menangani Pencari Sumber Daya Seragam
Uniform Resource Locator (URL) adalah representasi kompak dari lokasi dan metode akses untuk sumber daya yang terletak di Internet. Setiap URL terdiri dari skema (HTTP, HTTPS, atau FTP) dan string khusus skema. String ini juga dapat menyertakan kombinasi jalur direktori, string pencarian, atau nama sumber daya. Fungsi WinINet menyediakan kemampuan untuk membuat, menggabungkan, memecah, dan mengonisalisasi URL. Untuk informasi selengkapnya tentang URL, lihat RFC-1738 di Uniform Resource Locators (URL).
Fungsi URL beroperasi dengan cara berorientasi tugas. Konten dan format URL yang diberikan ke fungsi tidak diverifikasi. Aplikasi panggilan harus melacak penggunaan fungsi-fungsi ini untuk memastikan bahwa data dalam format yang dimaksudkan. Misalnya, fungsi InternetCanonicalizeUrl akan mengonversi karakter "%" menjadi urutan escape "%25" saat tidak menggunakan bendera. Jika InternetCanonicalizeUrl digunakan pada URL kanonis, urutan escape "%25" akan dikonversi menjadi urutan escape "%2525", yang tidak akan berfungsi dengan baik.
- Apa itu URL Kanonis?
- Menggunakan Fungsi WinINet untuk Menangani URL
- URL kanonisisasi
- Menggabungkan URL Dasar dan Relatif
- URL Retak
- Membuat URL
- Mengakses URL Secara Langsung
Apa itu URL Kanonis?
Format semua URL harus mengikuti sintaks dan semantik yang diterima untuk mengakses sumber daya melalui Internet. Kanonisisasi adalah proses pemformatan URL untuk mengikuti sintaks dan semantik yang diterima ini.
Karakter yang harus dikodekan mencakup karakter apa pun yang tidak memiliki karakter grafis yang sesuai dalam kumpulan karakter berkode US-ASCII (heksadesimal 80-FF, yang tidak digunakan dalam kumpulan karakter berkode US-ASCII, dan heksadesimal 00-1F dan 7F, yang merupakan karakter kontrol), spasi kosong, "%" (yang digunakan untuk mengodekan karakter lain), dan karakter yang tidak aman (<, , , >", #, {, }, |, \, ^, ~, ], dan ').
Menggunakan Fungsi WinINet untuk Menangani URL
Tabel berikut ini meringkas fungsi URL.
| Fungsi | Deskripsi |
|---|---|
| InternetCanonicalizeUrl | Canonicalizes the URL. |
| InternetCombineUrl | Menggabungkan URL dasar dan relatif. |
| InternetCrackUrl | Mengurai string URL ke dalam komponen. |
| InternetCreateUrl | Membuat string URL dari komponen. |
| InternetOpenUrl | Mulai mengambil sumber daya FTP, HTTP, atau HTTPS. |
URL kanonisisasi
Kanonikalisasi URL adalah proses yang mengonversi URL, yang mungkin berisi karakter yang tidak aman seperti spasi kosong, karakter yang dipesan, dan sebagainya, ke dalam format yang diterima.
Fungsi InternetCanonicalizeUrl dapat digunakan untuk mengkanonisalisasi URL. Fungsi ini sangat berorientasi pada tugas, sehingga aplikasi harus melacak penggunaannya dengan hati-hati. InternetCanonicalizeUrl tidak memverifikasi bahwa URL yang diteruskan ke dalamnya sudah dikanonisisasi dan bahwa URL yang dikembalikannya valid.
Lima bendera berikut mengontrol bagaimana InternetCanonicalizeUrl menangani URL tertentu. Bendera dapat digunakan dalam kombinasi. Jika tidak ada bendera yang digunakan, fungsi akan mengodekan URL secara default.
| Nilai | Makna |
|---|---|
| ICU_BROWSER_MODE | Jangan mengodekan atau mendekode karakter setelah "#" atau "?", dan jangan hapus spasi kosong berikutnya setelah "?". Jika nilai ini tidak ditentukan, seluruh URL dikodekan, dan spasi kosong berikutnya akan dihapus. |
| ICU_DECODE | Konversikan semua urutan %XX menjadi karakter, termasuk urutan escape, sebelum URL diurai. |
| ICU_ENCODE_SPACES_ONLY | Kodekan spasi saja. |
| ICU_NO_ENCODE | Jangan mengonversi karakter yang tidak aman untuk meloloskan urutan. |
| ICU_NO_META | Jangan hapus urutan meta (seperti "." dan "..") dari URL. |
Bendera ICU_DECODE harus digunakan hanya pada URL kanonis, karena mengasumsikan bahwa semua urutan %XX adalah kode escape dan mengonversinya menjadi karakter yang ditunjukkan oleh kode. Jika URL memiliki simbol "%" di dalamnya yang bukan bagian dari kode escape, ICU_DECODE masih memperlakukannya sebagai satu. Karakteristik ini dapat menyebabkan InternetCanonicalizeUrl membuat URL yang tidak valid.
Untuk menggunakan InternetCanonicalizeUrl untuk mengembalikan URL yang didekodekan sepenuhnya, bendera ICU_DECODE dan ICU_NO_ENCODE harus ditentukan. Penyiapan ini mengasumsikan bahwa URL yang diteruskan ke InternetCanonicalizeUrl sebelumnya telah dikanoniskan.
Menggabungkan URL Dasar dan Relatif
URL relatif adalah representasi ringkas dari lokasi sumber daya yang relatif terhadap URL dasar absolut. URL dasar harus diketahui oleh pengurai dan biasanya mencakup skema, lokasi jaringan, dan bagian dari jalur URL. Aplikasi dapat memanggil InternetCombineUrl untuk menggabungkan URL relatif dengan URL dasarnya. InternetCombineUrl juga mengotomatiskan URL yang dihasilkan.
URL Retak
Fungsi InternetCrackUrl memisahkan URL ke bagian komponennya dan mengembalikan komponen yang ditunjukkan oleh struktur URL_COMPONENTS yang diteruskan ke fungsi.
Komponen yang membentuk struktur URL_COMPONENTS adalah nomor skema, nama host, nomor port, nama pengguna, kata sandi, jalur URL, dan informasi tambahan (seperti parameter pencarian). Setiap komponen, kecuali skema dan nomor port, memiliki anggota string yang menyimpan informasi, dan anggota yang memegang panjang anggota string. Skema dan nomor port hanya memiliki anggota yang menyimpan nilai yang sesuai; keduanya dikembalikan pada semua panggilan yang berhasil ke InternetCrackUrl.
Untuk mendapatkan nilai komponen tertentu dalam struktur URL_COMPONENTS , anggota yang menyimpan panjang string komponen tersebut harus diatur ke nilai bukan nol. Anggota string dapat berupa alamat buffer atau NULL.
Jika anggota pointer berisi alamat buffer, anggota panjang string harus berisi ukuran buffer tersebut. InternetCrackUrl mengembalikan informasi komponen sebagai string dalam buffer dan menyimpan panjang string dalam anggota panjang string.
Jika anggota penunjuk ADALAH NULL, anggota panjang string dapat diatur ke nilai bukan nol. InternetCrackUrl menyimpan alamat karakter pertama string URL yang berisi informasi komponen dan mengatur panjang string ke jumlah karakter di bagian string URL yang tersisa yang berkaitan dengan komponen.
Semua anggota pointer diatur ke NULL dengan anggota panjang bukan nol menunjuk ke titik awal yang sesuai dalam string URL. Panjang yang disimpan dalam anggota panjang harus digunakan untuk menentukan akhir informasi komponen individu.
Untuk menyelesaikan inisialisasi struktur URL_COMPONENTS dengan benar, anggota dwStructSize harus diatur ke ukuran struktur URL_COMPONENTS , dalam byte.
Contoh berikut mengembalikan komponen URL dalam kotak edit, IDC_PreOpen1, dan mengembalikan komponen ke kotak daftar, IDC_PreOpenList. Untuk hanya menampilkan informasi untuk komponen individual, fungsi ini menyalin karakter segera setelah informasi komponen dalam string dan menggantinya untuk sementara dengan NULL.
#include <windows.h>
#include <tchar.h>
#include <strsafe.h>
#include <wininet.h>
#include <stdlib.h>
#pragma comment(lib, "wininet.lib")
#pragma comment(lib, "user32.lib")
#define CRACKER_BUFFER_SIZE MAX_PATH
// For sample source code implementing the InternetErrorOut( )
// function referenced below, see the "Handling Errors" topic
// under "Using WinInet"
extern BOOL WINAPI InternetErrorOut( HWND hWnd, DWORD dwError,
LPCTSTR szFailingFunctionName );
// Forward declaration of listUrlPart helper functions:
BOOL listURLpart( HWND hDlg, int nListBoxID,
LPTSTR szPartName, LPTSTR part, DWORD partLength );
BOOL listURLpart( HWND hDlg, int nListBoxID,
LPTSTR szPartName, int partValue );
// Static list describing the URL Scheme types
// enumerated in INTERNET_SCHEME:
TCHAR* schemeType[] =
{
TEXT( "[Partial URL]" ), // 0
TEXT( "[Unknown scheme]" ), // 1
TEXT( "[Default scheme]" ), // 2
TEXT( "FTP" ), // 3
TEXT( "Gopher" ), // 4
TEXT( "HTTP" ), // 5
TEXT( "HTTPS" ), // 6
TEXT( "File" ), // 7
TEXT( "News" ), // 8
TEXT( "MailTo" ), // 9
TEXT( "Socks" ), // 10
TEXT( "JavaScript" ), // 11
TEXT( "VBScript" ) // 12
};
#define CRACKER_SCHEME_TYPE_ARRAY_SIZE 13
BOOL WINAPI Cracker( HWND hDlg, int nURLtextBoxId, int nListBoxId )
{
int i, j;
TCHAR* failedFunctionName;
TCHAR URL_buffer[CRACKER_BUFFER_SIZE];
URL_COMPONENTS URLparts;
URLparts.dwStructSize = sizeof( URLparts );
// The following elements determine which components are displayed
URLparts.dwSchemeLength = 1;
URLparts.dwHostNameLength = 1;
URLparts.dwUserNameLength = 1;
URLparts.dwPasswordLength = 1;
URLparts.dwUrlPathLength = 1;
URLparts.dwExtraInfoLength = 1;
URLparts.lpszScheme = NULL;
URLparts.lpszHostName = NULL;
URLparts.lpszUserName = NULL;
URLparts.lpszPassword = NULL;
URLparts.lpszUrlPath = NULL;
URLparts.lpszExtraInfo = NULL;
SendDlgItemMessage( hDlg, nListBoxId, LB_RESETCONTENT, 0, 0 );
if( !GetDlgItemText( hDlg, nURLtextBoxId,
URL_buffer, CRACKER_BUFFER_SIZE ) )
{
failedFunctionName = TEXT( "GetDlgItemText" );
goto CrackerError_01;
}
if( FAILED( StringCchLength( URL_buffer, CRACKER_BUFFER_SIZE,
(size_t*) &i ) ) )
{
failedFunctionName = TEXT( "StringCchLength" );
goto CrackerError_01;
}
if( !InternetCrackUrl( URL_buffer, (DWORD)_tcslen( URL_buffer ), 0,
&URLparts ) )
{
failedFunctionName = TEXT( "InternetCrackUrl" );
goto CrackerError_01;
}
failedFunctionName = TEXT( "listURLpart" );
i = URLparts.nScheme + 2;
if( ( i >= 0 ) && ( i < CRACKER_SCHEME_TYPE_ARRAY_SIZE ) )
{
StringCchLength( schemeType[i],
CRACKER_BUFFER_SIZE,
(size_t*) &j );
if( !listURLpart( hDlg, nListBoxId,
TEXT("Scheme type"),
schemeType[i], j ))
goto CrackerError_01;
}
if( !listURLpart( hDlg, nListBoxId, TEXT( "Scheme text" ),
URLparts.lpszScheme,
URLparts.dwSchemeLength ) ||
!listURLpart( hDlg, nListBoxId, TEXT( "Host name" ),
URLparts.lpszHostName,
URLparts.dwHostNameLength) ||
!listURLpart( hDlg, nListBoxId, TEXT( "Port number" ),
(int) URLparts.nPort ) ||
!listURLpart( hDlg, nListBoxId, TEXT( "User name" ),
URLparts.lpszUserName,
URLparts.dwUserNameLength) ||
!listURLpart( hDlg, nListBoxId, TEXT( "Password" ),
URLparts.lpszPassword,
URLparts.dwPasswordLength) ||
!listURLpart( hDlg, nListBoxId, TEXT( "Path" ),
URLparts.lpszUrlPath,
URLparts.dwUrlPathLength) ||
!listURLpart( hDlg, nListBoxId, TEXT( "Extra information"),
URLparts.lpszExtraInfo,
URLparts.dwExtraInfoLength))
goto CrackerError_01;
return( TRUE );
CrackerError_01:
// For sample source code of the InternetErrorOut( ) function
// referenced below, see the "Handling Errors"
// topic under "Using WinInet"
InternetErrorOut( hDlg, GetLastError( ), failedFunctionName );
return FALSE;
}
// listURLpart( ) helper function for string parts
BOOL listURLpart( HWND hDlg, int nListBoxId,
LPTSTR szPartName, LPTSTR part, DWORD partLength )
{
TCHAR outputBuffer[CRACKER_BUFFER_SIZE];
LPTSTR nextStart;
size_t nextSize;
if( partLength == 0 ) // Just skip empty ones
return( TRUE );
if( FAILED( StringCchCopyEx( outputBuffer,
(size_t) CRACKER_BUFFER_SIZE,
szPartName, &nextStart,
&nextSize, 0 ) ) ||
FAILED( StringCchCopyEx( nextStart, nextSize, TEXT( ": " ),
&nextStart, &nextSize, 0 ) ) ||
FAILED( StringCchCopyNEx( nextStart, nextSize, part,
(size_t) partLength,
&nextStart, &nextSize, 0 ) ) )
return( FALSE );
*nextStart = 0;
if( SendDlgItemMessage( hDlg, nListBoxId, LB_ADDSTRING, 0,
(LPARAM)outputBuffer ) < 0 )
return( FALSE );
return( TRUE );
}
// listURLpart( ) helper function for numeric parts
BOOL listURLpart( HWND hDlg, int nListBoxId,
LPTSTR szPartName, int partValue )
{
TCHAR outputBuffer[CRACKER_BUFFER_SIZE];
if( FAILED( StringCchPrintf( outputBuffer,
(size_t) CRACKER_BUFFER_SIZE,
TEXT( "%s: %d" ), szPartName,
partValue ) ) ||
( SendDlgItemMessage( hDlg, nListBoxId, LB_ADDSTRING, 0,
(LPARAM)outputBuffer ) < 0 ) )
return( FALSE );
return( TRUE );
}
Membuat URL
Fungsi InternetCreateUrl menggunakan informasi dalam struktur URL_COMPONENTS untuk membuat Uniform Resource Locator.
Komponen yang membentuk struktur URL_COMPONENTS adalah skema, nama host, nomor port, nama pengguna, kata sandi, jalur URL, dan informasi tambahan (seperti parameter pencarian). Setiap komponen, kecuali nomor port, memiliki anggota string yang menyimpan informasi, dan anggota yang memegang panjang anggota string.
Untuk setiap komponen yang diperlukan, anggota pointer harus berisi alamat buffer yang menyimpan informasi. Anggota panjang harus diatur ke nol jika anggota penunjuk berisi alamat string yang dihentikan nol; anggota panjang harus diatur ke panjang string jika anggota penunjuk berisi alamat string yang tidak dihentikan nol. Anggota penunjuk dari komponen apa pun yang tidak diperlukan harus NULL.
Mengakses URL Secara Langsung
Sumber daya FTP, dan HTTP di Internet dapat diakses langsung dengan menggunakan fungsi InternetOpenUrl, InternetReadFile, dan InternetFindNextFile . InternetOpenUrl membuka koneksi ke sumber daya di URL yang diteruskan ke fungsi. Ketika koneksi ini dibuat, ada dua langkah yang mungkin. Pertama, jika sumber daya adalah file, InternetReadFile dapat mengunduhnya; kedua, jika sumber daya adalah direktori, InternetFindNextFile dapat menghitung file dalam direktori (kecuali saat menggunakan proksi CERN). Untuk informasi selengkapnya tentang InternetReadFile, lihat Membaca File. Untuk informasi selengkapnya tentang InternetFindNextFile, lihat Menemukan File Berikutnya.
Untuk aplikasi yang perlu beroperasi melalui proksi CERN, InternetOpenUrl dapat digunakan untuk mengakses direktori dan file FTP. Permintaan FTP dibungkus agar muncul seperti permintaan HTTP, yang akan diterima proksi CERN.
InternetOpenUrl menggunakan handel HINTERNET yang dibuat oleh fungsi InternetOpen dan URL sumber daya. URL harus menyertakan skema (http:, ftp:, file: [untuk file lokal], atau https: [untuk protokol hiperteks aman]) dan lokasi jaringan (seperti www.microsoft.com). URL juga dapat menyertakan jalur (misalnya, /isapi/gomscom.asp? TARGET=/windows/feature/) dan nama sumber daya (misalnya, default.htm). Untuk permintaan HTTP atau HTTPS, header tambahan dapat disertakan.
InternetQueryDataAvailable, InternetFindNextFile, InternetReadFile, dan InternetSetFilePointer (URL HTTP atau HTTPS saja) dapat menggunakan handel yang dibuat oleh InternetOpenUrl untuk mengunduh sumber daya.
Diagram berikut mengilustrasikan handel mana yang akan digunakan dengan setiap fungsi.
Handel HINTERNET akar yang dibuat oleh InternetOpen digunakan oleh InternetOpenUrl. Handel HINTERNET yang dibuat oleh InternetOpenUrl dapat digunakan oleh InternetQueryDataAvailable, InternetReadFile, InternetFindNextFile (tidak ditampilkan di sini), dan InternetSetFilePointer (URL HTTP atau HTTPS saja).
Untuk informasi selengkapnya, lihat Handel HINTERNET.
Catatan
WinINet tidak mendukung implementasi server. Selain itu, itu tidak boleh digunakan dari layanan. Untuk implementasi atau layanan server, gunakan Microsoft Windows HTTP Services (WinHTTP).
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk