MDS_Initialize

If both a Table of Contents and Search form are not displayed in separate frames along with this one, you may wish to redisplay this book in a frameset, beginning with the first page.

HP Open Source Security for OpenVMS Volume 1:...

API Functions

GetTimeValue

MDS_Install

MDS_Initialize

Library
Description
Errors

Parameters
Return Value
See Also

NAME

MDS_Initialize - Initiate service context with MDS (CDSA)

SYNOPSIS

# include <cdsa/mds.h>

CSSM_RETURN CSSMAPI MDS_Initialize
(const CSSM_GUID *pCallerGuid,
const CSSM_DATA *pCallerManifest,
const CSSM_MEMORY_FUNCS *pMemoryFunctions,
MDS_FUNCS_PTR pDlFunctions,
MDS_HANDLE *hMds)

LIBRARY

Module Directory Services library (cdsa$mds300_shr.exe)

PARAMETERS

`pCallerGuid` (input/optional)
		The GUID of the module calling MDS.
`pCallerManifest` (input/optional)
		The Manifest of the module calling MDS.
`pMemoryFunctions` (input)
		The memory-management routines MDS uses to allocate query results on behalf of the caller.
`pDlFunctions` (output)
		The function table containing MDS programming interfaces for database access.
`hMds` (output)
		A new handle that can be used to interact with the MDS. The value will be set to CSSM_INVALID_HANDLE if the function fails.

DESCRIPTION

This function initiates a service context with MDS and returns an opaque handle corresponding to that context. The caller provides memory functions that MDS can use to manage memory in the caller's space on behalf of the caller. The caller also provides input/output table pDlFunctions to get access to MDS databases.

If the caller is a CDSA service provider that will require write-access to an MDS database, (such as a module that supports dynamic insertion and removal events), then the caller can provide the caller's GUID as input parameter pCallerGuid. When provided as input, the GUID is associated with the MDS handle and is used during DbOpen processing. If write-access is requested during DbOpen, MDS uses the associated GUID to locate the service provider's signed manifest credentials in the DS Common relation. The service provider module and its credentials are verified to ensure that write-access is permitted on this database by this module.

The installers will have to provide the pCallerManifest instead of pCallerGuid, as GUID cannot be used to locate an application unless it is installed. Only one of the two parameters pCallerGuid and pCallerManifest should be non NULL in an MDS_Initialize() call, otherwise an error will be returned.

RETURN VALUE

A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.

ERRORS

Errors are described in the CDSA Technical Standard.

CSSMERR_DL_INVALID_POINTER
CSSMERR_DL_INTERNAL_ERROR
CSSMERR_DL_MEMORY_ERROR
CSSMERR_DL_FUNCTION_FAILED