IUniformResourceLocator Interface

This section provides information about the following IUniformResourceLocator interface methods:

• IUniformResourceLocator::GetURL
• IUniformResourceLocator::InvokeCommand
• IUniformResourceLocator::SetURL

IUniformResourceLocator::GetURL

HRESULT GetURL(
    LPSTR *ppszURL
);

Retrieves an object's uniform resource locator (URL).

• Returns S_OK if the object's URL was retrieved successfully. If the object does not have a URL associated with it, the function returns S_FALSE and sets ppszURL to NULL. Otherwise, the return value is an error code that can be one of the following:

  Value	Meaning
  E_OUTOFMEMORY	There is not enough memory to complete the operation.
  IS_E_EXEC_FAILED	The URL's protocol handler failed to run.
  URL_E_INVALID_SYNTAX	The URL's syntax is invalid.
  URL_E_UNREGISTERED_PROTOCOL	The URL's protocol does not have a registered protocol handler.

ppszURL

Pointer to an LPSTR that will be filled in with a pointer to the object's URL. Because this method allocates memory for the string, you must instantiate an Imalloc interface and free the memory using IMalloc::Free when it is no longer needed. The following code fragment provides an example of how this can be done:

//  START CODE FRAGMENT
{
    // In this example, pURL is a global IUniformResourceLocator pointer.
    LPSTR lpTemp;

    hres = pURL->GetURL(&lpTemp); 
    if (SUCCEEDED(hres)){
        IMalloc* pMalloc;
        hres = SHGetMalloc(&pMalloc); 
        if (SUCCEEDED(hres)){
            pMalloc->Free(lpTemp);
            pMalloc->Release();
        }
    }
}
//  END CODE FRAGMENT

IUniformResourceLocator::InvokeCommand

HRESULT InvokeCommand(
    PURLINVOKECOMMANDINFO pURLCommandInfo;
);

Runs a command on an object's URL.

• Returns S_OK if the object's URL was opened successfully. If the object does not have a URL associated with it, the function returns S_FALSE. Otherwise, the return value is an error code that can be one of the following:

  Value	Meaning
  E_OUTOFMEMORY	There is not enough memory to complete the operation.
  IS_E_EXEC_FAILED	The URL's protocol handler failed to run.
  URL_E_INVALID_SYNTAX	The URL's syntax is invalid.
  URL_E_UNREGISTERED_PROTOCOL	The URL's protocol does not have a registered protocol handler.

pURLCommandInfo

Pointer to a URLINVOKECOMMANDINFO structure that contains command information for the function.

IUniformResourceLocator::SetURL

HRESULT SetURL(
    LPCSTR pcszURL,
    DWORD dwInFlags
);

Sets an object's URL.

• Returns S_OK if the object's URL was set successfully. Otherwise, the return value is an error code that can be one of the following:

  Value	Meaning
  E_OUTOFMEMORY	There is not enough memory to complete the operation.
  IS_E_EXEC_FAILED	The URL's protocol handler failed to run.
  URL_E_INVALID_SYNTAX	The URL's syntax is invalid.
  URL_E_UNREGISTERED_PROTOCOL	The URL's protocol does not have a registered protocol handler.

pcszURL

Pointer to a zero-terminated string that contains the URL to set. The protocol scheme may be included as part of the URL.

dwInFlags

Flag value that specifies the behavior for setting the protocol scheme. This field can contain one of the following values:

IURL_SETURL_FL_GUESS_PROTOCOL

If the protocol scheme is not specified in pcszURL, the system automatically chooses a scheme and adds it to the URL.

IURL_SETURL_FL_USE_DEFAULT_PROTOCOL

If the protocol scheme is not specified in pcszURL, the system adds the default protocol scheme to the URL.