Credential types
[NetIDMgr Credentials Database]


Detailed Description


Data Structures

struct  tag_kcdb_credtype
 Credential type descriptor. More...

Defines

#define KCDB_CREDTYPE_MAX_ID   31
 Maximum value of a credential type identifier.
#define KCDB_CREDTYPE_ALL   (-1)
 Specify all credential types.
#define KCDB_CREDTYPE_AUTO   (-2)
 Automatically determine a credential type identifier.
#define KCDB_CREDTYPE_INVALID   (-3)
 An invalid credential type.
#define KCDB_CREDTYPE_IS_VALID(t)   ((t) >= 0)
 Macro predicate for testing whether a credtype is valid.

Typedefs

typedef tag_kcdb_credtype kcdb_credtype
 Credential type descriptor.

Functions

KHMEXP khm_int32 KHMAPI kcdb_credtype_register (const kcdb_credtype *type, khm_int32 *new_id)
 Register a credentials type.
KHMEXP khm_int32 KHMAPI kcdb_credtype_get_info (khm_int32 id, kcdb_credtype **type)
 Return a held reference to a kcdb_credtype object describing the credential type.
KHMEXP khm_int32 KHMAPI kcdb_credtype_release_info (kcdb_credtype *type)
 Release a reference to a kcdb_credtype object.
KHMEXP khm_int32 KHMAPI kcdb_credtype_unregister (khm_int32 id)
 Unregister a credentials type.
KHMEXP khm_int32 KHMAPI kcdb_credtype_get_name (khm_int32 id, wchar_t *buf, khm_size *cbbuf)
 Retrieve the name of a credentials type.
KHMEXP khm_handle KHMAPI kcdb_credtype_get_sub (khm_int32 id)
 Retrieve the type specific subscription for a type.
KHMEXP khm_int32 KHMAPI kcdb_credtype_describe (khm_int32 id, wchar_t *buf, khm_size *cbbuf, khm_int32 flags)
 Get the description of a credentials type.
KHMEXP khm_int32 KHMAPI kcdb_credtype_get_id (const wchar_t *name, khm_int32 *id)
 Look up the identifier of a credentials type by name.


Define Documentation

#define KCDB_CREDTYPE_ALL   (-1)

Specify all credential types.

This value is used by functions which filter credentials based on credential types. Specifying this value tells the filter to accept all credential types.

#define KCDB_CREDTYPE_AUTO   (-2)

Automatically determine a credential type identifier.

Used with kcdb_credtype_register() to specify that the credential type identifier should be automatically determined to avoid collisions.

#define KCDB_CREDTYPE_INVALID   (-3)

An invalid credential type.

Even though any non positive credential type ID is invalid anywhere where a specific credential type ID is required, this value is provided for explicit indication that the credential type is invalid. Also it makes code more readable to have a constant that shouts out INVALID.

#define KCDB_CREDTYPE_IS_VALID (  )     ((t) >= 0)

Macro predicate for testing whether a credtype is valid.

Returns TRUE if the given credtype is valid. This is a safe macro.

#define KCDB_CREDTYPE_MAX_ID   31

Maximum value of a credential type identifier.

Credential type identifiers are assigned serially unless the process registering the credential type sets a specific identity. The maximum identifier number places a hard limit to the number of credential types that can be registered at one time, which is KCDB_CREDTYPE_MAX_ID + 1.


Function Documentation

KHMEXP khm_int32 KHMAPI kcdb_credtype_describe ( khm_int32  id,
wchar_t *  buf,
khm_size cbbuf,
khm_int32  flags 
)

Get the description of a credentials type.

Unlike the name of a credential type, the description is localized.

Parameters:
[in] id Credentials type identifier
[out] buf Receives the description. Can bet set to NULL if only the size of the buffer is required.
[in,out] cbbuf On entry, specifies the size of the buffer pointed to by buf. On exit, specifies the required size of the buffer or the number of bytes copied, depending on whether the call succeeded or not.
[in] flags Specify KCDB_TS_SHORT if the short version of the description is desired if there is more than one.
Return values:
KHM_ERROR_SUCCESS The call succeeded
KHM_ERROR_TOO_LONG Either buf was NULL or the supplied buffer was insufficient. The required size is specified in cbbuf.
KHM_ERROR_INVALID_PARAM One or more parameters were invalid.

KHMEXP khm_int32 KHMAPI kcdb_credtype_get_id ( const wchar_t *  name,
khm_int32 id 
)

Look up the identifier of a credentials type by name.

Given a name, looks up the identifier.

Parameters:
[in] name Name of the credentials type
[out] id Receives the identifier if the call succeeds

KHMEXP khm_int32 KHMAPI kcdb_credtype_get_info ( khm_int32  id,
kcdb_credtype **  type 
)

Return a held reference to a kcdb_credtype object describing the credential type.

The reference points to a static internal object of type kcdb_credtype. Use the kcdb_credtype_release_info() function to release the reference.

Also, the structure passed in as the type argument to kcdb_credtype_register() is not valid as a credential type descriptor. Use kcdb_credtype_get_info() to obtain the actual credential type descriptor.

Parameters:
[in] id Credentials type identifier.
[out] type Receives the credentials descriptor handle. If type is NULL, then no handle is returned. However, the function will still return KHM_ERROR_SUCCESS if the id parameter passed in is a valid credentials type identifier.
See also:
kcdb_credtype_release_info()

kcdb_credtype_register()

KHMEXP khm_int32 KHMAPI kcdb_credtype_get_name ( khm_int32  id,
wchar_t *  buf,
khm_size cbbuf 
)

Retrieve the name of a credentials type.

Given a credentials type identifier, retrieves the name. The name is not localized and serves as a persistent identifier of the credentials type.

Parameters:
[out] buf The buffer to receive the name. Could be NULL if only the length of the buffer is required.
[in,out] cbbuf On entry, specifies the size of the buffer pointed to by buf if buf is not NULL. On exit, contains the number of bytes copied to buf or the required size of the buffer.
Return values:
KHM_ERROR_SUCCESS The call succeeded.
KHM_ERROR_TOO_LONG Either buf was NULL or the supplied buffer was not large enough. The required size is in cbbuf.
KHM_ERROR_INVALID_PARAM Invalid parameter.

KHMEXP khm_handle KHMAPI kcdb_credtype_get_sub ( khm_int32  id  ) 

Retrieve the type specific subscription for a type.

Given a credentials type, this function returns the credentials type specific subcription. It may return NULL if the subscription is not available.

KHMEXP khm_int32 KHMAPI kcdb_credtype_register ( const kcdb_credtype type,
khm_int32 new_id 
)

Register a credentials type.

The information given in the type parameter is used to register a new credential type. Note that the name member of the type should be unique among all credential types.

You can specify KCDB_CREDTYPE_AUTO as the id member of type to let kcdb_credtype_register() determine a suitable credential type identifier. You can subsequently call kcdb_credtype_get_id() to retrieve the generated id or pass a valid pointer to a khm_int32 type variable as new_id.

Parameters:
[in] type Credential type descriptor
[out] new_id The credential type identifier that this type was registered as.
Return values:
KHM_ERROR_SUCCESS The credential type was successfully registered.
KHM_ERROR_INVALID_PARAM One or more of the parameters were invalid
KHM_ERROR_TOO_LONG One or more of the string fields in type exceeded the character limit for that field.
KHM_ERROR_NO_RESOURCES When autogenerating credential type identifiers, this value indicates that the maximum number of credential types have been registered. No more registrations can be accepted unless some credentials type is unregisred.
KHM_ERROR_DUPLICATE The name or id that was specified is already in use.

KHMEXP khm_int32 KHMAPI kcdb_credtype_release_info ( kcdb_credtype type  ) 

Release a reference to a kcdb_credtype object.

Undoes the hold obtained on a kcdb_credtype object from a previous call to kcdb_credtype_get_info().

See also:
kcdb_credtype_get_info()

KHMEXP khm_int32 KHMAPI kcdb_credtype_unregister ( khm_int32  id  ) 

Unregister a credentials type.

Undoes the registration performed by kcdb_credtype_register().

This should only be done when the credentials provider is being unloaded.


Generated on Fri Aug 3 08:27:14 2007 for Network Identity Manager by Doxygen 1.5.2
© 2004-2007 Massachusetts Institute of Technology.
© 2005-2007 Secure Endpoints Inc.
Contact khimaira@mit.edu