Export (0) Print
Expand All
This topic has not yet been rated - Rate this topic

IWbemServices::OpenNamespace method

The IWbemServices::OpenNamespace method provides the caller with a new IWbemServices pointer that has the specified child namespace as its operating context. All operations through the new pointer, such as class or instance creation, only affect that namespace. The namespace must be a child namespace of the current object through which this method is called.

Syntax


HRESULT OpenNamespace(
  [in]   const BSTR strNamespace,
  [in]   LONG lFlags,
  [in]   IWbemContext *pCtx,
  [out]  IWbemServices **ppWorkingNamespace,
  [out]  IWbemCallResult **ppResult
);

Parameters

strNamespace [in]

Path to the target namespace. For more information, see Creating Hierarchies within WMI. This namespace can only be relative to the current namespace associated with the IWbemServices interface pointer. This parameter cannot be an absolute path or NULL.

lFlags [in]

This parameter can be set to 0 to make this a synchronous call. To make this a semisynchronous call, set lFlags to WBEM_FLAG_RETURN_IMMEDIATELY, provide a valid pointer for the ppResult parameter, and this call will return immediately. For more information, see Calling a Method.

pCtx [in]

Reserved. This parameter must be NULL.

ppWorkingNamespace [out]

Receives the object that represents the new namespace context. The returned pointer has a positive reference count. The caller must call Release on this pointer when it is no longer needed. This pointer is set to NULL when there are errors. If this parameter is specified, then ppResult must be NULL.

ppResult [out]

Typically NULL. If not NULL, then ppWorkingNamespace must be NULL. In this case, the parameter receives a pointer to a new IWbemCallResult object. If the lFlags parameter is set to WBEM_FLAG_RETURN_IMMEDIATELY this call returns immediately. Then the caller can periodically poll the IWbemCallResult::GetResultServices method until the pointer for the requested namespace becomes available. This parameter is set to point to NULL when there is an error and a new object is not returned.

Note  It is important to note that when you use this parameter, you must set ppResult to point to NULL before calling the method. This is a COM rule.

Return value

This method returns an HRESULT indicating the status of the method call. The following table lists the value contained within an HRESULT.

On failure, you can obtain any available information from the COM function GetErrorInfo.

COM-specific error codes may also be returned if network problems cause you to lose the remote connection to Windows Management.

Return codeDescription
WBEM_E_ACCESS_DENIED

The user does not have permission to access the requested namespace.

WBEM_E_FAILED

This indicates other unspecified errors.

WBEM_E_INVALID_NAMESPACE

The specified namespace does not exist.

WBEM_E_INVALID_PARAMETER

An invalid parameter was specified or the namespace could not be parsed.

WBEM_E_OUT_OF_MEMORY

There was not enough memory to complete the operation.

WBEM_E_SHUTTING_DOWN

Windows Management service was probably stopped and restarted. A new call to ConnectServer is needed.

WBEM_E_TRANSPORT_FAILURE

The communications link between the current process and Windows Management has failed.

WBEM_S_NO_ERROR

The call succeeded.

 

Remarks

The IWbemLocator::ConnectServer method can also be used to open the same namespace. The only difference is that the OpenNamespace method allows you to place relative object paths in the Namespace parameter to open child namespaces recursively; IWbemLocator::ConnectServer requires a full object path. For more information, see Describing a WMI Namespace Object Path.

For example, if the current namespace associated with the IWbemServices interface pointer is root, then using Default in the Namespace parameter yields a new pointer bound to the root\default namespace.

The namespace is closed when Release is called and the reference count reaches 0 (zero).

Examples

For script code examples, see WMI Tasks for Scripts and Applications and the TechNet ScriptCenter Script Repository.

For C++ code examples, see WMI C++ Application Examples.

Requirements

Minimum supported client

Windows XP

Minimum supported server

Windows Server 2003

Header

Wbemcli.h (include Wbemidl.h)

Library

Wbemuuid.lib

DLL

Fastprox.dll;
Esscli.dll;
Framedyn.dll;
Ntevt.dll;
Stdprov.dll;
Viewprov.dll;
Wbemcomn.dll;
Wbemcore.dll;
Wbemess.dll;
Wbemsvc.dll;
Wmipicmp.dll;
Wmidcprv.dll;
Wmipjobj.dll;
Wmiprvsd.dll

See also

IWbemServices
Creating Hierarchies within WMI
Retrieving an Error Code
IWbemLocator::ConnectServer

 

 

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft. All rights reserved.