RegisterNameSpace method

Article
07/13/2016

Registers a temporary pluggable namespace handler on the current process.

Syntax

HRESULT retVal = object.RegisterNameSpace(pCF, rclsid, pwzProtocol, cPatterns, ppwzPatterns, dwReserved);

Parameters

pCF [in]
Type: IClassFactory

A pointer to an IClassFactory interface where an IInternetProtocol object can be created. The object's reference count is increased.
rclsid [in]
Type: REFCLSID

A reference to the CLSID of the namespace. Passing CLSID_NULL is discouraged.
pwzProtocol [in]
Type: LPCWSTR

A string value that contains the protocol to be handled.
cPatterns [in]
Type: unsigned long

Unused. Set to 0.
ppwzPatterns [in]
Type: const LPCWSTR

Unused. Set to NULL.
dwReserved [in]
Type: DWORD

Reserved. Must be set to 0.

Return value

Type: HRESULT

This method can return one of these values.

Return code	Description
E_FAIL	The operation failed.
E_NOINTERFACE	No such interface is supported.

Remarks

The IInternetSession::RegisterNameSpace method enables an interface to handle requests for the specified protocol namespace. A single interface can be registered multiple times for each namespace that it can handle. Because pluggable protocol handlers are not chained, only the last handler to be registered will be active; therefore, it is better to create a new namespace, rather than reuse an existing one.

This method registers a pluggable namespace handler only on the current process; no other processes are affected by this method. An application can register a pluggable namespace handler for a particular period of time. When finished, it should call IInternetSession::UnregisterNameSpace to remove the registration.

Note Registering namespace handlers for HTTP and HTTPS protocols is not recommended. Doing so within the Internet Explorer process incurs a performance penalty when browsing.

The ppwzPatterns and cPatterns parameters are unused; the registered pluggable namespace handler is called for all protocol requests.

Examples

The following example demonstrates how to register a handler for the "about:" pluggable protocol.

IInternetSession *pInetSess;
HRESULT hr = CoInternetGetSession(0, &pInetSess, 0);
if (SUCCEEDED(hr) && pInetSess)
{
    hr = pInetSess->RegisterNameSpace((IClassFactory *)this, 
            CLSID_AboutProtocol, _T("about"), 0, NULL, 0);
}

Share via