WinInet.h 함수들 (FTP 구현할때)

InternetTimeFromSystemTime function

Formats a date and time according to the HTTP version 1.0 specification.

HTTP 버전 1.0 사양에 따라 날짜와 시간을 형식화.

Syntax

C++

BOOL InternetTimeFromSystemTime(
  _In_  const SYSTEMTIME *pst,
  _In_        DWORD      dwRFC,
  _Out_       LPTSTR     lpszTime,
  _In_        DWORD      cbTime
);

Parameters

pst [in]

Pointer to a SYSTEMTIME structure that contains the date and time to format.

dwRFC [in]

RFC format used. Currently, the only valid format is INTERNET_RFC1123_FORMAT.

lpszTime [out]

Pointer to a string buffer that receives the formatted date and time. The buffer should be of size INTERNET_RFC1123_BUFSIZE.

cbTime [in]

Size of the lpszTime buffer, in bytes.

InternetTimeToSystemTime function

Converts an HTTP time/date string to a SYSTEMTIME structure.

Syntax

C++

BOOL InternetTimeToSystemTime(
  _In_  LPCTSTR    lpszTime,
  _Out_ SYSTEMTIME *pst,
  _In_  DWORD      dwReserved
);

Parameters

lpszTime [in]

Pointer to a null-terminated string that specifies the date/time to be converted.

pst [out]

Pointer to a SYSTEMTIME structure that receives the converted time.

dwReserved [in]

This parameter is reserved and must be 0.

http의 시간과 날짜 스트링들을 가져와서 시스템 시간으로 컨버팅하는 용도.

InternetCrackUrl function

Cracks a URL into its component parts.

Syntax

C++

BOOL InternetCrackUrl(
  _In_    LPCTSTR          lpszUrl,
  _In_    DWORD            dwUrlLength,
  _In_    DWORD            dwFlags,
  _Inout_ LPURL_COMPONENTS lpUrlComponents
);

Parameters

lpszUrl [in]

Pointer to a string that contains the canonical URL to be cracked.

dwUrlLength [in]

Size of the lpszUrl string, in TCHARs, or zero if lpszUrl is an ASCIIZ string.

dwFlags [in]

Controls the operation. This parameter can be one of the following values.

URL 분해

InternetCreateUrl function

Creates a URL from its component parts.

Syntax

C++

BOOL InternetCreateUrl(
  _In_    LPURL_COMPONENTS lpUrlComponents,
  _In_    DWORD            dwFlags,
  _Out_   LPTSTR           lpszUrl,
  _Inout_ LPDWORD          lpdwUrlLength
);

Parameters

lpUrlComponents [in]

Pointer to a URL_COMPONENTS structure that contains the components from which to create the URL.

dwFlags [in]

Controls the operation of this function. This parameter can be one or more of the following values.

컴포넌트들을 기반으로 URL 생성

InternetCanonicalizeUrl

BOOL InternetCanonicalizeUrl(
    IN LPCTSTR lpszUrl,
    OUT LPTSTR lpszBuffer,
    IN OUT LPDWORD lpdwBufferLength,
    IN DWORD dwFlags
);

Converts a URL to a canonical form, which includes converting unsafe characters into escape sequences.

• Returns TRUE if successful, or FALSE otherwise. To get extended error information, call GetLastError. Possible errors include:

  ERROR_INVALID_PARAMETER

  Bad string, buffer, buffer size, or flags parameter.

  ERROR_INSUFFICIENT_BUFFER

  Canonicalized URL is too large to fit in the buffer provided. The *lpdwBufferLength parameter is set to the size, in bytes, of the buffer required to hold the resultant, canonicalized URL.

  ERROR_BAD_PATHNAME

  The URL could not be canonicalized.

  ERROR_INTERNET_INVALID_URL

  The format of the URL is invalid.

lpszUrl

Address of the input URL to canonicalize.

lpszBuffer

Address of the buffer that receives the resulting canonicalized URL.

lpdwBufferLength

Length, in bytes, of the lpszBuffer buffer. If the function succeeds, this parameter receives the length of the lpszBuffer buffer--the length does not include the terminating null. If the function fails, this parameter receives the required length, in bytes, of the lpszBuffer buffer--the required length includes the terminating null.

dwFlags

Flags that control canonicalization. Can be one of these values:

Value	Meaning
ICU_DECODE	Convert %XX escape sequences to characters.
ICU_NO_ENCODE	Do not convert unsafe characters to escape sequence.
ICU_NO_META	Do not remove meta sequences (such as "." and "..") from the URL.
ICU_ENCODE_SPACES_ONLY	Encode spaces only.
ICU_BROWSER_MODE	Do not encode or decode characters after #' or '?', and do not remove trailing white space after '?'. If this value is not specified, the entire URL is encoded and trailing white space is removed.

If no flags are specified, the function converts all unsafe characters and meta sequences (such as \.,\ .., and \...) to escape sequences.

InternetCanonicalizeUrl always encodes by default, even if the ICU_DECODE flag has been specified. To decode without re-encoding, use ICU_DECODE | ICU_NO_ENCODE. If the ICU_DECODE flag is used without ICU_NO_ENCODE, the URL is decoded before being parsed; unsafe characters then are re-encoded after parsing. This function will handle arbitrary protocol schemes, but to do so it must make inferences from the unsafe character set.

표준형식의 URL 변환(안전하지 않은 문자열, 이스케이프 문자열 등)

InternetCombineUrl

BOOL InternetCombineUrl(
    IN LPCTSTR lpszBaseUrl,
    IN LPCTSTR lpszRelativeUrl,
    OUT LPTSTR lpszBuffer,
    IN OUT LPDWORD lpdwBufferLength,
    IN DWORD dwFlags
);

Combines a base and relative URL into a single URL. The resultant URL will be canonicalized (see InternetCanonicalizeUrl).

• Returns TRUE if successful, or FALSE otherwise. To get extended error information, call GetLastError. Possible error codes include:

  ERROR_INVALID_PARAMETER

  Bad string, buffer, buffer size, or flags parameter.

  ERROR_INSUFFICIENT_BUFFER

  The *lpdwBufferLength parameter, in bytes, of the buffer required to hold the resultant, combined URL.

  ERROR_BAD_PATHNAME

  The URLs could not be combined.

  ERROR_INTERNET_INVALID_URL

  The format of the URL is invalid.

lpszBaseUrl

Address of the base URL to be combined.

lpszRelativeUrl

Address of the relative URL to be combined.

lpszBuffer

Address of a buffer that receives the resulting URL.

lpdwBufferLength

Size, in bytes, of the lpszBuffer buffer. If the function succeeds, this parameter receives the length, in characters, of the resultant combined URL--the length does not include the null terminator. If the function fails, this parameter receives the length, in bytes, of the required buffer--the length includes the null terminator.

dwFlags

Flags controlling the operation of the function. For a description of the flags, see InternetCanonicalizeUrl.

URL 결합(기본 URL + 상대 URL) return 표준화된 URL

InternetOpen

HINTERNET InternetOpen(
    IN LPCTSTR lpszAgent,
    IN DWORD dwAccessType,
    IN LPCTSTR lpszProxyName OPTIONAL,
    IN LPCSTR lpszProxyBypass OPTIONAL,
    IN DWORD dwFlags
);

Initializes an application's use of the Win32 Internet functions.

• Returns a valid handle that the application passes on to subsequent Win32 Internet functions. If InternetOpen fails, it returns NULL. To get a specific error code, call GetLastError.

lpszAgent

Address of a string that contains the name of the application or entity calling the Internet functions (for example, Microsoft Internet Explorer). This name is used as the user agent in the HTTP protocol.

dwAccessType

Type of access required. Can be one of these values:

INTERNET_OPEN_TYPE_DIRECT

Resolve all host names locally.

INTERNET_OPEN_TYPE_PROXY

Pass requests to the proxy unless a proxy bypass list is supplied and the name to be resolved bypasses the proxy. In this case, the function proceeds as for INTERNET_OPEN_TYPE_DIRECT.

INTERNET_OPEN_TYPE_PRECONFIG

Retrieve the proxy or direct configuration from the registry.

lpszProxyName

Address of a string that contains the name of the proxy server (or servers) to use if proxy access was specified. If this parameter is NULL, the function reads proxy information from the registry. For more information about this parameter, see the comments below.

lpszProxyBypass

Address of an optional list of host names or IP addresses, or both, that are known locally. Requests to these names are not routed through the proxy. The list can contain wildcards, such as "157.55.* *int*", meaning any IP address starting with 157.55, or any name containing the substring "int", will bypass the proxy.

If this parameter specifies the "<local>" macro as the only entry, the function bypasses any host name that does not contain a period. For example, "www.microsoft.com" would be routed to the proxy, whereas "internet" would not.

If this parameter is NULL, the function reads the bypass list from the registry.

dwFlags

Flag that indicates various options affecting the behavior of the function. Can be a combination of these values:

INTERNET_FLAG_OFFLINE

Satisfy download operations on this handle through the persistent cache only. If the item does not exist in the cache, the function returns an appropriate error code.

INTERNET_FLAG_ASYNC

Future operations on this handle may fail with ERROR_IO_PENDING. A status callback will be made with INTERNET_STATUS_REQUEST_COMPLETE. This callback will be on a thread other than the one for the original request. A status callback routine must be registered or the functions will be completed synchronously.

This function is the first Win32 Internet function called by an application. It tells the Internet DLL to initialize internal data structures and prepare for future calls from the application. When the application finishes using the Internet functions, it should call InternetCloseHandle to free the handle and any associated resources.

If dwFlags includes INTERNET_FLAG_ASYNC, all handles derived from this handle will have asynchronous behavior as long as a status callback routine is registered. For a function to be completed synchronously, dwContext must be set to zero for that call.

By default, the function assumes that the proxy specified by lpszProxyName is a CERN proxy. For example, "proxy" defaults to a CERN proxy called "proxy" that listens at port 80 (decimal). An application can specify more than one proxy, including different proxies for the different protocols. For example, if you specify "ftp=ftp://ftp-gw gopher=http://jericho:99 proxy", FTP requests are made through the FTP proxy "ftp-gw", which listens at port 21 (default for FTP), and Gopher requests are made through a CERN proxy called "jericho", which listens at port 99. All other requests (for example, HTTP requests) are made through the CERN proxy called "proxy", which listens at port 80. Note that if the application is only using FTP, for example, it would not need to specify "ftp=ftp://ftp-gw:21". It could specify just "ftp-gw". An application must specify the protocol names only if it will be using more than one protocol per handle returned by InternetOpen.

The application can make any number of calls to InternetOpen, although a single call is normally sufficient. The application may need to have separate behaviors defined for each InternetOpen instance, such as different proxy servers configured for each.

See also InternetCloseHandle

인터넷에 관련된 라이브러리 등을 초기화 함.

InternetCloseHandle

BOOL InternetCloseHandle(
    IN HINTERNET hInet
);

Closes a single Internet handle or a subtree of Internet handles.

• Returns TRUE if the handle is successfully closed, or FALSE otherwise. To get extended error information, call GetLastError.

hInet

Valid Internet handle to be closed.

This function can be used to close any Internet handle or subtree of handles of the type HINTERNET and free any associated resources. The function terminates any pending operations on the handle and discards any outstanding data. If a thread is blocking a call to Wininet.dll, another thread in the application can call InternetCloseHandle on the Internet handle being used by the first thread to cancel the operation and unblock the first thread.

InternetCloseHandle should be used to close the handle returned from InternetOpen when the application has finished using the Internet DLL.

If there is a status callback registered for the handle being closed and the handle was created with a non-NULL context value, an INTERNET_STATUS_HANDLE_CLOSING callback will be made. This indication will be the last callback made from a handle and indicates that the handle is being destroyed.

If asynchronous requests are pending for the handle or any of its child handles, the handle cannot be closed immediately, but it will be invalidated. Any new requests attempted using the handle will return with an ERROR_INVALID_HANDLE notification. The asynchronous requests will complete with INTERNET_STATUS_REQUEST_COMPLETE. Applications must be prepared to receive any INTERNET_STATUS_REQUEST_COMPLETE indications on the handle before the final INTERNET_STATUS_HANDLE_CLOSING indication is made, which indicates that the handle is completely closed.

An application can call GetLastError to determine if requests are pending. If GetLastError returns ERROR_IO_PENDING, there were outstanding requests when the handle was closed.

See also FtpFindFirstFile, FtpOpenFile, GopherFindFirstFile, HttpOpenRequest, InternetConnect, InternetOpen

거의 대부분의 close함수와 마찬가지로 썼던 핸들 반환해서 닫는 용도.

InternetConnect

HINTERNET InternetConnect(
    IN HINTERNET hInternetSession,
    IN LPCTSTR lpszServerName,
    IN INTERNET_PORT nServerPort,
    IN LPCTSTR lpszUsername OPTIONAL,
    IN LPCTSTR lpszPassword OPTIONAL,
    IN DWORD dwService,
    IN DWORD dwFlags,
    IN DWORD dwContext
);

Opens an FTP, Gopher, or HTTP session for a given site.

• Returns a valid handle to the FTP, Gopher, or HTTP session if the connection is successful, or NULL otherwise. To get extended error information, call GetLastError. An application can also use InternetGetLastResponseInfo to determine why access to the service was denied.

hInternetSession

Handle of the current Internet session. The handle must have been returned by a previous call to InternetOpen.

lpszServerName

Address of a null-terminated string that contains the host name of an Internet server. Alternately, the string can contain the IP number of the site in ASCII dotted-decimal format (for example, 11.0.1.45).

nServerPort

Number of the TCP/IP port on the server to connect to. Can be one of the values in the following list. If this parameter is set to INTERNET_INVALID_PORT_NUMBER, the function uses the default port for the specified service. These values do not cause the function to use this protocol. The value sets the port to be used. A flag must be used to set the service.

Value	Meaning
INTERNET_DEFAULT_FTP_PORT	Use the default port for FTP servers (port 21).
INTERNET_DEFAULT_GOPHER_PORT	Use the default port for Gopher servers (port 70).
INTERNET_DEFAULT_HTTP_PORT	Use the default port for HTTP servers (port 80).
INTERNET_DEFAULT_HTTPS_PORT	Use the default port for HTTPS servers (port 443).

lpszUsername

Address of a null-terminated string that contains the name of the user to log on. If this parameter is NULL, the function uses an appropriate default, except for HTTP. A NULL parameter in HTTP causes the server to return an error. For the FTP protocol, the default is anonymous.

lpszPassword

Address of a null-terminated string that contains the password to use to log on. If both lpszPassword and lpszUsername are NULL, the function uses the default anonymous password. In the case of FTP, the default anonymous password is the user's e-mail name. If lpszPassword is NULL, but lpszUsername is not NULL, the function uses a blank password. The following table describes the behavior for the four possible settings of lpszUsername and lpszPassword:

lpszUsername	lpszPassword	User name sent to FTP server	Password sent to FTP server
NULL	NULL	"anonymous"	User's e-mail name
Non-NULL string	NULL	lpszUsername	""
NULL	Non-NULL string	ERROR	ERROR
Non-NULL string	Non-NULL string	lpszUsername	lpszPassword

dwService

Type of service to access. Can be one of these values:

Value	Meaning
INTERNET_SERVICE_FTP	FTP service.
INTERNET_SERVICE_GOPHER	Gopher service.
INTERNET_SERVICE_HTTP	HTTP service.

dwFlags

Flags specific to the service used. Can be one of these values:

If dwService is:	dwFlags supported
INTERNET_SERVICE_FTP	INTERNET_CONNECT_FLAG_PASSIVE (Use passive mode in all data connections for this FTP session.)

dwContext

An application-defined value that is used to identify the application context for the returned handle in callbacks.

The InternetConnect function is required before communicating with any Internet service.

Having a connect function for all protocols, even those that do not use persistent connections, lets an application communicate common information about several requests using a single function call. In addition, this allows for future versions of Internet protocols that do not require a connection to be established for every client request.

For FTP sites, InternetConnect actually establishes a connection with the server; for others, such as Gopher, the actual connection is not established until the application requests a specific transaction.

For maximum efficiency, applications using the Gopher and HTTP protocols should try to minimize calls to InternetConnect and avoid calling this function for every transaction requested by the user. One way to accomplish this is to keep a small cache of handles returned from InternetConnect; when the user makes a request to a previously accessed server, that session handle is still available.

An application that needs to display multiline text information sent by an FTP server can use InternetGetLastResponseInfo to retrieve the text.

For FTP connections, if lpszUsername is NULL, InternetConnect sends the string "anonymous" as the user name. If lpszPassword is NULL, InternetConnect attempts to use the user's e-mail name as the password.

To close the handle returned from InternetConnect, the application should call InternetCloseHandle. This function disconnects the client from the server and frees all resources associated with the connection.

See also InternetCloseHandle, InternetOpen