The System Manager interface is an application’s access to the DMA information that is visible to and available at a point of access. It is also used by DMA-compliant applications to enumerate and connect to registered systems.
This method must be supported in every implementation of this interface.
Syntax
DmaRC IdmaSystemManager::ConnectSystem (
pDmaId pSystemId,
pDmaString pLocaleName,
DMA_REFIID riid,
pDmapv ppISystem)
Parameters
Name | Mode | Description |
pSystemId | input | The System Id which uniquely identifies the system configuration to connect to. |
pLocaleName | input | The name of the locale to be used by the returned system object. If this parameter is NULL, the system object is to employ its default locale.If this parameter is non-NULL and does not correspond to a locale supported by this system object, the system object will utilize its default locale. |
riid | input | Interface Identifier for the desired interface on resulting object. |
ppISystem | output | Returns a reference to the requested interface for the System object, which will be NULL if unsuccessful. |
Returns an interface that provides a (usually unauthenticated) DMA System object representing the indicated DMA System. If the operation succeeds, a new System Object is returned, representing a point-of-access view of the identified system. Each System Object returned by IdmaSystemManager::ConnectSystem is a distinct instance.
In general, the IdmaAuthentication interface must be exercised on the returned DMA System object before the object can be used for anything other than inspecting the system’s non-object valued properties.
There is a small well defined set of DMA return codes returned from this method. There is no DMA supplied mechanism for mapping these return codes into a meaningful message (e.g., IdmaSystem::GetResultCodeDescription), until a DMA System object becomes available.
Return Values
Name | Description |
DMARC_BAD_INTERFACE | (E_NOINTERFACE) The requested interface is not supported by this object. |
DMARC_BAD_PARAMETER | (E_INVALIDARG) Invalid input parameter. |
DMARC_NETWORK_UNAVAILABLE | The network needed to perform this operation is not available. |
DMARC_NOT_FOUND | Requested item not found. |
DMARC_OK | (S_OK) Success. |
This method must be supported in every implementation of this interface.
Syntax
DmaRC IdmaSystemManager::EnumerateSystems (
DMA_REFIID riid,
pDmapv ppIEnumOfSystem)
Parameters
Name | Mode | Description |
riid | input | Interface Identifier for the desired interface on resulting object. |
ppIEnumOfSystem | output | Returns a reference to the requested interface or NULL if unsuccessful. |
TThe IdmaSystemManager::EnumerateSystems function returns an interface (typically IdmaEnumOfObject) to a COM object which the caller can use to enumerate DMA System objects which the System Manager was able to locate and connect to via IdmaSystemManager::ConnectSystem (using the character set encoding id and locale name parameters specified in a prior call to dmaConnectSystemManager).
In general, the IdmaAuthentication interface must be exercised on the returned DMA System object before the object can be used for anything other than inspecting the System's non-object valued properties.
There is a small well defined set of DMA return codes returned from this method. There is no DMA supplied mechanism for mapping these return codes into a meaningful message (e.g., IdmaSystem::GetResultCodeDescription), until a DMA System object becomes available.
Return Values
Name | Description |
DMARC_BAD_PARAMETER | (E_INVALIDARG) Invalid input parameter. |
DMARC_OK | (S_OK) Success. |
This method must be supported in every implementation of this interface.
Syntax
DmaRC IdmaSystemManager::GetMalloc (
DMA_REFIID riid,
pDmapv ppIMalloc)
Parameters
Name | Mode | Description |
riid | input | Interface Identifier for the desired interface on the system manager’s Memory Management object. |
ppIMalloc | output | Returns the selected interface of the COM Memory Management object used by this DMA System Manager and its children. This is an interface of the object whose interface was supplied as the pIMalloc parameter of the dmaConnectSystem-Manager operation if that parameter was non-NULL, otherwise it is an interface on the COM Memory Management object that the System Manager supplied. This is always the correct Memory Manager to use for freeing data referenced by non-interface output pointers returned from methods on this System Manager object or its children. |
Returns the selected interface for the memory manager used by this DMA System Manager object. This is the memory manager used for all allocations of data passed to the client as a result of a DMA method call. This interface must be used to free any of that data when the returned pointer is no longer needed.
See the Component Object Model specification for a complete definition of the IMalloc interface. The following specialized methods are included in this interface: Alloc, Free, Realloc, GetSize, DidAlloc, HeapMinimize. The interface specification does not require that all of these methods be supported by the object supplying the interface.
If the returned object does not support the interface specified by the riid parameter, the operation will fail and the result code DMARC_BAD_INTERFACE will be returned. In case the operation is successful, the returned interface must be released using the method IUnknown::Release.
Return Values
Name | Description |
DMARC_BAD_INTERFACE | (E_NOINTERFACE) The requested interface is not supported by this object. |
DMARC_BAD_PARAMETER | (E_INVALIDARG) Invalid input parameter. |
DMARC_OK | (S_OK) Success. |