IUniformResourceLocator Interface

IUniformResourceLocator Interface Methods

This section provides information about IUniformResourceLocator interface methods.

IUniformResourceLocator::GetURL

IUniformResourceLocator::InvokeCommand

IUniformResourceLocator::SetURL

IUniformResourceLocator::GetURL

HRESULT GetURL(
 LPSTR *ppszURL
);

This method retrieves an object's URL.

• The function 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_SYTNAX	The URL's syntax in 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. Since 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;
);

This method invokes a command on an object's URL.

• The function 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 will 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_SYTNAX	The URL's syntax in 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
);

This method sets an object's URL.

• The function returns S_OK if the object's URL was set successfully. Otherwise, the return value is an error code that will 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_SYTNAX	The URL's syntax in invalid.
  URL_E_UNREGISTERED_PROTOCOL	The URL's protocol does not have a registered protocol handler.

pcszURL

Pointer to a const 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.

Value

Meaning

IURL_SETURL_FL_GUESS_PROTOCOL

If the protocol scheme is not specified in pcszURL, the system will automatically choose a scheme and add it to the URL.

IURL_SETURL_FL_USE_DEFAULT_PROTOCOL

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