## 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.

© 1996 Microsoft Corporation