C
BYTE ExtractURLFields( BYTE * vURL, PROTOCOLS * protocol, BYTE * vUsername, WORD * wUsernameLen, BYTE * vPassword, WORD * wPasswordLen, BYTE * vHostname, WORD * wHostnameLen, WORD * wPort, BYTE * vFilePath, WORD * wFilePathLen );
Description
Extracts all parameters from an URL string (ex: "http://admin:[email protected]:8080/myfile.gif" is split into {PROTOCOL_HTTP, "admin", "passwd", "www.microchip.com", 8080, "/myfile.gif"}.
The URL string can be null terminated, or alternatively could be terminated by a carriage return or line feed.
If the protocol is unrecognized or the protocol is recognized but the URL is malformed, than an error is safely returned. For more information on URL/URI interpretation see RFC 2396.
Preconditions
This function is commented out by default to save code space because it is not used by any current stack features. However, if you want to use it, go ahead and uncomment it. It has been tested, so it (should) work correctly.
Parameters
|
Parameters |
Description |
|
vURL |
Pointer to null terminated URL to decode and extract from. This parameter is required and needs to have the minimum RFC 1738 components in it (protocol and hostname). |
|
protocol |
Optional pointer to a PROTOCOLS enum to retrieve the decoded protocol type. If this parameter is unneeded, specify a NULL pointer. The protocol is a required part of the URL, so it must always be present. The protocol also determines what scheme all other parameters are decoded using, so the function will fail if an unrecognized protocol is provided. The PROTOCOLS enum members show all of the currently supported protocols for this function. For the example URL provided in the function description, PROTOCOL_HTTP would be returned for this field. |
|
vUsername |
Optional pointer to a buffer to write the decoded username portion of the URL. If the URL does not contain a username or a NULL pointer is supplied, then this field is ignored. For the example URL provided in the function description, "admin" would be returned for this field. |
|
wUsernameLen |
On call: Optional pointer to a WORD specifying the maximum length of the vUsername buffer, including the null terminator character. Upon return: If wUsernameLen and vUsername are non-NULL, the *wUsernameLen WORD is updated with the actual number of characters written to the vUsername buffer, including the null terminator character. If vUsername is NULL but wUsernameLen is non-NULL, then no characters are copied, but *wUsernameLen will return the number of characters required to fit the full username string. If wUsernameLen is NULL, then the username field in the URL, if present, is ignored and the vUsername pointer is not used. If zero characters were written, this indicates that the URL did not contain a username field. If one character was written, this indicates that a username field was present, but was a zero character string (ex: ""). For the example URL provided in the function description, 6 (0x0006) would be returned for this field. |
|
vPassword |
Optional pointer to a buffer to write the decoded password portion of the URL. If the URL does not contain a password or a NULL pointer is supplied, then this field is ignored. For the example URL provided in the function description, "passwd" would be returned for this field. |
|
wPasswordLen |
On call: Optional pointer to a WORD specifying the maximum length of the vPassword buffer, including the null terminator character. Upon return: If wPasswordLen and vPassword are non-NULL, the *wPasswordLen WORD is updated with the actual number of characters written to the vPassword buffer, including the null terminator character. If vPassword is NULL but wPasswordLen is non-NULL, then no characters are copied, but *wPasswordLen will return the number of characters required to fit the full password string. If wPasswordLen is NULL, then the password field in the URL, if present, is ignored and the vPassword pointer is not used. If zero characters were written, this indicates that the URL did not contain a password field. If one character was written, this indicates that a password field was present, but was a zero character string (ex: ""). For the example URL provided in the function description, 7 (0x0007) would be returned for this field. |
|
vHostname |
Optional pointer to a buffer to write the decoded hostname portion of the URL. All Internet URLs must contain a hostname or IP address, however, if a NULL pointer is supplied, then this field is ignored. For the example URL provided in the function description, "www.microchip.com" would be returned for this field. If the URL was "http://192.168.0.1", then this field would be returned as "192.168.0.1". The IP address would not be decoded to a DWORD (use the StringToIPAddress() helper function to do this). |
|
wHostnameLen |
On call: Optional pointer to a WORD specifying the maximum length of the vHostname buffer, including the null terminator character. Upon return: If wHostnameLen and vHostname are non-NULL, the *wHostnameLen WORD is updated with the actual number of characters written to the vHostname buffer, including the null terminator character. If vHostname is NULL but wHostnameLen is non-NULL, then no characters are copied, but *wHostnameLen will return the number of characters required to fit the full hostname string. If wHostnameLen is NULL, then the hostname field in the URL, is ignored and the vHostname pointer is not used. For the example URL provided in the function description, 18 (0x0012) would be returned for this field. If the URL was "http://192.168.0.1", then this field would be returned as 12 (0x000C). |
|
wPort |
Optional pointer to a WORD specifying the TCP or UDP port that the server is listening on. If the port field is absent from the URL, then this parameter will specify the default port for the protocol. For example, "http://www.microchip.com" would result in 80 being return as the specified port. If the wPort pointer is NULL, then the port field in the URL is ignored, if present. |
|
vFilePath |
Optional pointer to a buffer to write the decoded file path portion of the URL. If a NULL pointer is supplied, then this field is ignored. If a file path is not present in the URL, then "/" will be returned in this field. For the example URL provided in the function description, "/myfile.gif" would be returned for this field. |
|
wFilePathLen |
On call: Optional pointer to a WORD specifying the maximum length of the vFilePath buffer, including the null terminator character. Upon return: If wFilePathLen and vFilePath are non-NULL, the *wFilePathLen WORD is updated with the actual number of characters written to the vFilePath buffer, including the null terminator character. If vFilePath is NULL but wFilePathLen is non-NULL, then no characters are copied, but *wFilePathLen will return the number of characters required to fit the full file path string. If wFilePathLen is NULL, then the file path field in the URL, if present, is ignored and the vFilePath pointer is not used. This function always returns "/" if no file path is present, so *wFilePathLen will also be at least 2 characters ('/' and null terminator) if the pointer is non-NULL. For the example URL provided in the function description, 12 (0x000C) would be returned for this field. |
Returns
Zero on success. Nonzero indicates an error code. If a nonzero error code is returned, none of the returned buffers or pointer values should be treated as valid, but some of them may have been written to. The following are all possible return values.
|
0 |
No error |
|
1 |
Protocol unknown (additional code needs to be added to ExtractURLFields() and the PROTOCOLS enum needs to be updated if you want to decode URLs of this protocol type. |
|
2 |
URL malformed. Illegal or unknown URL format encountered. |
|
3 |
Buffer too small. One of the input buffer sizes is too small to contain the URL parameter. |