Network Identity Manager: Network Identity Manager

  • Main Page
  • Modules
  • Data Structures
  • Related Pages

Network Identity Manager

Documentation for Developers

Network Identity Manager is a credentials manager, which is capable of managing Kerberos v5, Kerberos v4, Andrew File System, and Kerberized Certificate Authority credentials. This document describes the API that is implemented by the Khimaira framework upon which Network Identity Manager is based.

See the following sections for more information :

  • License agreement and credits
  • Reporting bugs
  • Prior releases

© 2004-2007 Massachusetts Institute of Technology

© 2005-2007 Secure Endpoints Inc.

Generated on Mon Oct 22 22:56:44 2007 for Network Identity Manager by Doxygen 1.5.3
© 2004-2007 Massachusetts Institute of Technology.
© 2005-2007 Secure Endpoints Inc.
Contact khimaira@mit.edu


Network Identity Manager: License agreement and credits

  • Related Pages
Network Identity Manager

License agreement and credits

Network Identity Manager is distributed under the MIT License.

MIT License

Copyright © 2004,2005,2006,2007 Massachusetts Institute of Technology

Copyright © 2005,2006,2007 Secure Endpoints Inc.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Credits

Network Identity Manager was developed at the Massachusetts Institute of Technology in partnership with Secure Endpoints Inc.

Information Services and Technology at Massachusetts Institute of Technology

Secure Endpoints Inc.

Generated on Mon Oct 22 22:56:44 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Reporting bugs

Network Identity Manager

Reporting bugs

Network Identity Manager bugs can be reported to kfw-bugs@mit.edu or netidmgr@secure-endpoints.com

When reporting bugs, please include as much information as possible to help reproduce the problem.

Generated on Mon Oct 22 22:56:44 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Prior releases

Network Identity Manager

Prior releases

The following is a list of releases of Network Identity Manager. Whenever there is an addition to the API or a significant change in behavior, the API version is incremented. A plug-in that is developed against a particular version of the API will be compatible with any release of Network Identity Manager that implements that version of the API.

The Network Identity Manager version number is set as the file and product version of nidmgr32.dll.

The API version refers to the version of the API exposed by nidmgr32.dll. A plug-in that was built against a particular API version will be compatible with any version of Network Identity Manager whose API version is the same.

  • 1.3.0.0 Kerberos for Windows 3.2 August 15, 2007
    API version : 9

  • 1.2.0.2 Kerberos for Windows 3.2 Beta 2 Apr 11, 2007
    API version : 8

  • 1.2.0.1 Apr 06, 2007
    API version : 8

  • 1.2.0.0 Kerberos for Windows 3.2 Beta 1 Mar 29, 2007
    API version : 8

  • 1.1.11.0 Mar 20, 2007
    API version : 8

  • 1.1.10.0 Feb 28, 2007
    API version : 8

  • 1.1.9.0 Jan 20, 2007
    API version : 7

  • 1.1.8.0 Kerberos for Windows 3.1 Final Nov 22, 2006
    API version : 6

  • 1.1.6.0 Kerberos for Windows 3.1 Beta 4 Nov 17, 2006
    API version : 6

  • 1.1.4.0 Kerberos for Windows 3.1 Beta 3 Nov 08, 2006
    API version : 6

  • 1.1.2.0 Oct 09, 2006
    API version : 6

  • 1.1.0.2 Sep 21, 2006
    API version : 6

  • 1.1.0.1 Jul 19, 2006
    API version : 5

  • 1.1.0.0 Mar 08, 2006
    API version : 5

  • 1.0.0.0 Kerberos for Windows 3.0 Dec 05, 2005
    API version : 4

  • 0.1.2.0 Second Alpha release Nov 30, 2005
    API version : 3
    Released along with Kerberos for Windows 3.0 beta 2.

  • 0.1.1 First Alpha release Nov 01, 2005
    Released along with Kerberos for Windows 3.0 beta.
Generated on Mon Oct 22 22:56:44 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Module Index

Network Identity Manager Modules

Here is a list of all modules:
  • Core definitions
  • NetIDMgr errors
    • Error codes
  • NetIDMgr Configuration Provider
  • NetIDMgr Credentials Database
    • Identities
    • Credential sets and individual credentials
      • Credential sets
      • Credentials
    • Credential attribute types
    • Credential attributes
      • Attribute flags
      • Standard attribute IDs and names
    • Credential types
    • Generic access to buffer
  • NetIDMgr Message Queue
    • Message Types
      • KMSG_SYSTEM subtypes
      • KMSG_KCDB subtypes
      • KMSG_KMM subtypes
      • KMSG_ACT subtypes
      • KMSG_CRED subtypes
      • KMSG_ALERT Subtypes
      • KMSG_IDENT Subtypes
  • User Interface
    • Actions
      • Standard Actions
    • Alerter and Error Reporting
    • Configuration Panels
    • Hyperlink
    • Credentials acquisition
    • Property sheets
    • Connecting to NetIDMgr from another process
    • Duration sliders
  • Utilities
    • Hashtable
    • Multi String and CSV functions
    • Synchronization
  • NetIDMgr Module Manager
    • Registration
    • Internationalization support
    • NetIDMgr Plugin Callbacks
  • NetIDMgr Error Reporting
    • Standard Facility IDs
Generated on Mon Oct 22 22:56:47 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Core definitions

Core definitions

Detailed Description

Key type definitions used throughout NetIDMgr.

Data Structures

struct | khm_version
Generic version type. More...

Defines

#define | VALID_INT_BITS INT_MAX
#define | VALID_UINT_BITS UINT_MAX
#define | KHM_UINT32_MAX 4294967295
#define | KHM_INT32_MAX 2147483647
#define | KHM_INT32_MIN (-KHM_INT32_MAX-1)
#define | KHM_UINT16_MAX 65535
#define | KHM_INT16_MAX 32767
#define | KHM_INT16_MIN (-KHM_INT16_MAX-1)
#define | KHM_INVALID_HANDLE ((khm_handle) NULL)
The invalid handle.
#define | _SSIZE_T_DEFINED
#define | KHMAPI __stdcall
Calling convention for NetIDMgr exported functions.
#define | KHMEXP KHMEXP_IMP
Export prefix for NetIDMgr exported functions.
#define | KHMEXP_EXP __declspec(dllexport)
#define | KHMEXP_IMP __declspec(dllimport)
#define | KHM_PERM_READ 0x100
Generic read permission or request.
#define | KHM_PERM_WRITE 0x200
Generic write permission or request.
#define | KHM_FLAG_CREATE 0x1000
Generic create request.
#define | UBOUND32(d) ((((d)-1)&~3) + 4)
Wrap to DWORD boundary.
#define | BYTEOFFSET(p, off) ((void *)(((char *) (p)) + (off)))
Offset a pointer by a number of bytes.
#define | IS_POW2(d) ((d)>=0 && !((d) & ((d) - 1)))
Check for powers of 2.
#define | UBOUNDSS(v, start, step) (((v)<=(start))?(start):(start)+((((v)-((start)+1))/(step))+1)*(step))
Wrap to upper bound based on start and step size.
#define | ARRAYLENGTH(x) (sizeof(x)/sizeof(x[0]))

Typedefs

typedef unsigned __int8 | khm_octet
A byte (8 bit unsigned).
typedef __int16 | khm_int16
A signed 16 bit quantity.
typedef unsigned __int16 | khm_ui_2
An unsigned 16 bit quantity.
typedef __int32 | khm_int32
A signed 32 bit quantity.
typedef unsigned __int32 | khm_ui_4
An unsigned 32 bit quantity.
typedef __int64 | khm_int64
A signed 64 bit quantity.
typedef unsigned __int64 | khm_ui_8
An unsigned 64 bit quantity.
typedef void * | khm_handle
Generic handle type.
typedef khm_int32 | khm_boolean
Boolean.
typedef size_t | khm_size
A size.
typedef _W64 int | ssize_t
Signed size specifier.
typedef ssize_t | khm_ssize
typedef unsigned __int32 | khm_wparm
typedef unsigned __int64 | khm_lparm

Define Documentation

#define BYTEOFFSET | ( | p,
 |  | off | ) | ((void *)(((char *) (p)) + (off)))

Offset a pointer by a number of bytes.

Given a pointer, returns a void pointer that is a given number of bytes offset from the pointer.

#define IS_POW2 ( d ) ((d)>=0 && !((d) & ((d) - 1)))

Check for powers of 2.

Return TRUE if the operand is a positive power of 2 or 0

#define KHM_FLAG_CREATE 0x1000

Generic create request.

For most lookup functions, specifying this flag indicates that if the requested object is not found it should be created.

#define KHM_INVALID_HANDLE ((khm_handle) NULL)

The invalid handle.

Just used to indicate that this handle does not point to anything useful. Usually returned by a function that returns a handle as a signal that the operation failed.

#define KHMAPI __stdcall

Calling convention for NetIDMgr exported functions.

The caling convention for all NetIDMgr exported functions is __stdcall , unless otherwise noted.

#define KHMEXP KHMEXP_IMP

Export prefix for NetIDMgr exported functions.

When compiling source that exports functions, those exported function declarations will be done as follows:

   __declspec(dllexport) khm_int32 __stdcall function_name(arguments...);

This eliminates the need for a separate exports definition file. However, it doesn't preserve ordinals, but we aren't guaranteeing that anyway.

On the other hand, if a particular function is going to be imported from a DLL, it should declared as follows:

   __declspec(dllimport) khm_int32 __stdcall function_name(arguments...);

This allows the compiler to properly instrument the import. If the function is not declared this way, there will be a stub function generated that will just jump to the proper import, generating redundant instructions and wasting execution time.

This macro encapsulates the proper declaration specifier.

#define UBOUND32 ( d ) ((((d)-1)&~3) + 4)

Wrap to DWORD boundary.

Returns the smallest integer greater than or equal to the parameter that is a multiple of 4.

Note:
Only use with positive integers.

#define UBOUNDSS | ( | v,
 |  | start,
 |  | step | ) | (((v)<=(start))?(start):(start)+((((v)-((start)+1))/(step))+1)*(step))

Wrap to upper bound based on start and step size.

Return the smallest element in the series s, s+t, s+2*t, s+3*t, ... that is greater than or equal to v.

Typedef Documentation

typedef void* khm_handle

Generic handle type.

Handles in NetIDMgr are generic pointers.

ssize_t

Signed size specifier.

Just a signed version of size_t

Generated on Mon Oct 22 22:56:44 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: khm_version Struct Reference

  • Alphabetical List
  • Data Structures
  • Data Fields

khm_version Struct Reference
[Core definitions]

#include <khdefs.h>

Detailed Description

Generic version type.

Data Fields

khm_ui_2 major
khm_ui_2 minor
khm_ui_2 patch
khm_ui_2 aux

Field Documentation

khm_ui_2 khm_version::major

Major version number

khm_ui_2 khm_version::minor

Minor version number

khm_ui_2 khm_version::patch

Patch level

khm_ui_2 khm_version::aux

Auxilary level (usually carries a build number)

The documentation for this struct was generated from the following file:
  • khdefs.h
Generated on Mon Oct 22 22:56:48 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: NetIDMgr errors

NetIDMgr errors

Modules

Error codes

Defines

#define | KHM_ERROR_BASE 0x40000000L
Base for error codes.
#define | KHM_ERROR_RANGE 256L
Range for error codes.
#define | KHM_SUCCEEDED(rv) ((rv)==KHM_ERROR_NONE)
Tests whether a return value indicates success.
#define | KHM_FAILED(rv) ((rv)!=KHM_ERROR_NONE)
Tests whether a return value indicates failure.

Define Documentation

#define KHM_ERROR_BASE 0x40000000L

Base for error codes.

NetIDMgr errors range from KHM_ERROR_BASE to KHM_ERROR_BASE + KHM_ERROR_RANGE, with the exception of KHM_ERROR_SUCCESS and KHM_ERROR_NONE.

#define KHM_ERROR_RANGE 256L

Range for error codes.

NetIDMgr errors range from KHM_ERROR_BASE to KHM_ERROR_BASE + KHM_ERROR_RANGE.

Generated on Mon Oct 22 22:56:44 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Error codes

Error codes
[NetIDMgr errors]

Defines

#define | KHM_ERROR_NONE 0x00000000L
No error.
#define | KHM_ERROR_SUCCESS KHM_ERROR_NONE
Success. Same as KHM_ERROR_NONE.
#define | KHM_ERROR_INVALID_NAME (KHM_ERROR_BASE + 1)
The supplied name was invalid.
#define | KHM_ERROR_TOO_LONG (KHM_ERROR_BASE + 2)
Too much data.
#define | KHM_ERROR_INVALID_PARAM (KHM_ERROR_BASE + 3)
One or more parameters supplied to a function were invalid.
#define | KHM_ERROR_DUPLICATE (KHM_ERROR_BASE + 4)
A duplicate.
#define | KHM_ERROR_NOT_FOUND (KHM_ERROR_BASE + 5)
An object was not found.
#define | KHM_ERROR_NOT_READY (KHM_ERROR_BASE + 6)
The relevant subsystem is not ready.
#define | KHM_ERROR_NO_RESOURCES (KHM_ERROR_BASE + 7)
No more resources.
#define | KHM_ERROR_TYPE_MISMATCH (KHM_ERROR_BASE + 8)
Type mismatch.
#define | KHM_ERROR_EXISTS (KHM_ERROR_BASE + 9)
Already exists.
#define | KHM_ERROR_TIMEOUT (KHM_ERROR_BASE + 10)
Operation timed out.
#define | KHM_ERROR_EXIT (KHM_ERROR_BASE + 11)
An EXIT message was received.
#define | KHM_ERROR_UNKNOWN (KHM_ERROR_BASE + 12)
Unknown or unspecified error.
#define | KHM_ERROR_GENERAL KHM_ERROR_UNKNOWN
General error.
#define | KHM_ERROR_OUT_OF_BOUNDS (KHM_ERROR_BASE + 13)
An index was out of bounds.
#define | KHM_ERROR_DELETED (KHM_ERROR_BASE + 14)
Object already deleted.
#define | KHM_ERROR_INVALID_OPERATION (KHM_ERROR_BASE + 15)
Invalid operation.
#define | KHM_ERROR_INVALID_SIGNATURE (KHM_ERROR_BASE + 16)
Signature check failed.
#define | KHM_ERROR_NOT_IMPLEMENTED (KHM_ERROR_BASE + 17)
Not implemented yet.
#define | KHM_ERROR_EQUIVALENT (KHM_ERROR_BASE + 18)
The objects were equivalent.
#define | KHM_ERROR_NO_PROVIDER (KHM_ERROR_BASE + 19)
No provider exists to service the request.
#define | KHM_ERROR_PARTIAL (KHM_ERROR_BASE + 20)
The operation succeeded, but with errors.
#define | KHM_ERROR_INCOMPATIBLE (KHM_ERROR_BASE + 21)
An incompatibility was found.
#define | KHM_ERROR_HELD (KHM_ERROR_BASE + 22)
The operation was put on hold.

Define Documentation

#define KHM_ERROR_DELETED (KHM_ERROR_BASE + 14)

Object already deleted.

One or more objects that were referenced were found to have been already deleted.

#define KHM_ERROR_DUPLICATE (KHM_ERROR_BASE + 4)

A duplicate.

Usually means that something that should have been unique was found to be not.

#define KHM_ERROR_EXISTS (KHM_ERROR_BASE + 9)

Already exists.

Usually indicates that an exclusive create operation failed due to the existence of a similar object. Subtly different from KHM_ERROR_DUPLICATE

#define KHM_ERROR_HELD (KHM_ERROR_BASE + 22)

The operation was put on hold.

A request was put on hold or postponed.

#define KHM_ERROR_INVALID_OPERATION (KHM_ERROR_BASE + 15)

Invalid operation.

The operation was not permitted to continue for some reason. Usually because the necessary conditions for the operation haven't been met yet or the operation can only be performed at certain times during the execution of NetIDMgr.

#define KHM_ERROR_NO_RESOURCES (KHM_ERROR_BASE + 7)

No more resources.

A limited resource has been exhausted.

#define KHM_ERROR_NOT_FOUND (KHM_ERROR_BASE + 5)

An object was not found.

An object referenced in a parameter was not found.

#define KHM_ERROR_NOT_IMPLEMENTED (KHM_ERROR_BASE + 17)

Not implemented yet.

The operation that was attempted involved invoking functionality that has not been implemented yet.

#define KHM_ERROR_NOT_READY (KHM_ERROR_BASE + 6)

The relevant subsystem is not ready.

Indicates that initialization has not been completed for a subsystem.

#define KHM_ERROR_TOO_LONG (KHM_ERROR_BASE + 2)

Too much data.

A supplied buffer was invalid, was of insufficient size, or a buffer was of a larger size than expected

Generated on Mon Oct 22 22:56:44 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: NetIDMgr Configuration Provider

NetIDMgr Configuration Provider

Detailed Description

Data Structures

struct | kconf_schema
Configuration schema descriptor record. More...

Configuration data types

#define | KC_NONE 0
Not a known type.
#define | KC_SPACE 1
When used as kconf_schema type, defines the start of a configuration space.
#define | KC_ENDSPACE 2
Ends a configuration space started with KC_SPACE.
#define | KC_INT32 3
A 32 bit integer.
#define | KC_INT64 4
A 64 bit integer.
#define | KC_STRING 5
A unicode string.
#define | KC_BINARY 6
An unparsed binary stream.

Defines

#define | KCONF_FLAG_ROOT 0x00000001
This is the root configuration space.
#define | KCONF_FLAG_USER 0x00000002
Indicates the configuration store which stores user-specific information.
#define | KCONF_FLAG_MACHINE 0x00000004
Indicates the configuration store which stores machine-specific information.
#define | KCONF_FLAG_SCHEMA 0x00000008
Indicates the configuration store which stores the schema.
#define | KCONF_FLAG_TRAILINGVALUE 0x00000020
Indicates that the last component of the given configuration path is to be considered to be a configuration value.
#define | KCONF_FLAG_WRITEIFMOD 0x00000040
Only write values back there is a change.
#define | KCONF_FLAG_IFMODCI 0x00000080
Use case-insensitive comparison for KCONF_FLAG_WRITEIFMOD.
#define | KCONF_FLAG_NOPARSENAME 0x00000040
Do not parse the configuration space name.
#define | KCONF_MAXCCH_NAME 256
Maximum number of allowed characters (including terminating NULL) in a name.
#define | KCONF_MAXCB_NAME (KCONF_MAXCCH_NAME * sizeof(wchar_t))
Maximum number of allowed bytes (including terminating NULL) in a name.
#define | KCONF_MAX_DEPTH 16
Maximum level of nesting for configuration spaces.
#define | KCONF_MAXCCH_PATH (KCONF_MAXCCH_NAME * KCONF_MAX_DEPTH)
Maximum number of allowed characters (including terminating NULL) in a configuration path.
#define | KCONF_MAXCB_PATH (KCONF_MAXCCH_PATH * sizeof(wchar_t))
Maximum number of allowed bytes (including terminating NULL) in a configuration path.
#define | KCONF_MAXCCH_STRING KHM_MAXCCH_STRING
Maximum number of allowed characters (including terminating NULL) in a string.
#define | KCONF_MAXCB_STRING (KCONF_MAXCCH_STRING * sizeof(wchar_t))
Maximum number of allowed bytes (including terminating NULL) in a string.

Functions

KHMEXP khm_int32 KHMAPI | khc_open_space (khm_handle parent, const wchar_t *cspace, khm_int32 flags, khm_handle *result)
Open a configuration space.
KHMEXP khm_int32 KHMAPI | khc_shadow_space (khm_handle upper, khm_handle lower)
Set the shadow space for a configuration handle.
KHMEXP khm_int32 KHMAPI | khc_close_space (khm_handle conf)
Close a handle opened with khc_open_space().
KHMEXP khm_int32 KHMAPI | khc_read_string (khm_handle conf, const wchar_t *value_name, wchar_t *buf, khm_size *bufsize)
Read a string value from a configuration space.
KHMEXP khm_int32 KHMAPI | khc_read_multi_string (khm_handle conf, const wchar_t *value_name, wchar_t *buf, khm_size *bufsize)
Read a multi-string value from a configuration space.
KHMEXP khm_int32 KHMAPI | khc_read_int32 (khm_handle conf, const wchar_t *value_name, khm_int32 *buf)
Read a 32 bit integer value from a configuration space.
KHMEXP khm_int32 KHMAPI | khc_read_int64 (khm_handle conf, const wchar_t *value_name, khm_int64 *buf)
Read a 64 bit integer value from a configuration space.
KHMEXP khm_int32 KHMAPI | khc_read_binary (khm_handle conf, const wchar_t *value_name, void *buf, khm_size *bufsize)
Read a binary value from a configuration space.
KHMEXP khm_int32 KHMAPI | khc_write_string (khm_handle conf, const wchar_t *value_name, wchar_t *buf)
Write a string value to a configuration space.
KHMEXP khm_int32 KHMAPI | khc_write_multi_string (khm_handle conf, const wchar_t *value_name, wchar_t *buf)
Write a multi-string value to a configuration space.
KHMEXP khm_int32 KHMAPI | khc_write_int32 (khm_handle conf, const wchar_t *value_name, khm_int32 buf)
Write a 32 bit integer value to a configuration space.
KHMEXP khm_int32 KHMAPI | khc_write_int64 (khm_handle conf, const wchar_t *value_name, khm_int64 buf)
Write a 64 bit integer value to a configuration space.
KHMEXP khm_int32 KHMAPI | khc_write_binary (khm_handle conf, const wchar_t *value_name, void *buf, khm_size bufsize)
Write a binary value to a configuration space.
KHMEXP khm_int32 KHMAPI | khc_get_type (khm_handle conf, const wchar_t *value_name)
Get the type of a value in a configuration space.
KHMEXP khm_int32 KHMAPI | khc_value_exists (khm_handle conf, const wchar_t *value)
Check which configuration stores contain a specific value.
KHMEXP khm_int32 KHMAPI | khc_remove_value (khm_handle conf, const wchar_t *value_name, khm_int32 flags)
Remove a value from a configuration space.
KHMEXP khm_int32 KHMAPI | khc_get_config_space_name (khm_handle conf, wchar_t *buf, khm_size *bufsize)
Get the name of a configuration space.
KHMEXP khm_int32 KHMAPI | khc_get_config_space_parent (khm_handle conf, khm_handle *parent)
Get a handle to the parent space.
KHMEXP khm_int32 KHMAPI | khc_load_schema (khm_handle conf, const kconf_schema *schema)
Load a configuration schema into the specified configuration space.
KHMEXP khm_int32 KHMAPI | khc_unload_schema (khm_handle conf, const kconf_schema *schema)
Unload a schema from a configuration space.
KHMEXP khm_int32 KHMAPI | khc_enum_subspaces (khm_handle conf, khm_handle prev, khm_handle *next)
Enumerate the subspaces of a configuration space.
KHMEXP khm_int32 KHMAPI | khc_remove_space (khm_handle conf)
Remove a configuration space.

Define Documentation

#define KC_BINARY 6

An unparsed binary stream.

Specifies a configuration parameter named name which is of this type. Use description to provide an optional description of the value.

Default values are not supported for binary streams. value is ignored.

#define KC_INT32 3

A 32 bit integer.

Specifies a configuration parameter named name which is of this type. Use description to provide an optional description of the value.

value specifies a default value for this parameter in the lower 32 bits.

#define KC_INT64 4

A 64 bit integer.

Specifies a configuration parameter named name which is of this type. Use description to provide an optional description of the value.

value specifies a default value for this parameter.

#define KC_SPACE 1

When used as kconf_schema type, defines the start of a configuration space.

There should be a subsequent KC_ENDSPACE record in the schema which defines the end of this configuration space.

name specifies the name of the configuration space. Optionally use description to provide a description.

#define KC_STRING 5

A unicode string.

Specifies a configuration parameter named name which is of this type. Use description to provide an optional description of the value.

value specifies a default value for this parameter which should be a pointer to a NULL terminated unicode string of no more than KCONF_MAXCCH_STRING characters.

#define KCONF_FLAG_IFMODCI 0x00000080

Use case-insensitive comparison for KCONF_FLAG_WRITEIFMOD.

When used in combination with KCONF_FLAG_WRITEIFMOD , the string comparison used when determining whether the string read from the configuration handle is the same as the string being written will be case insensitive. If this flag is not set, the comparison will be case sensitive.

#define KCONF_FLAG_NOPARSENAME 0x00000040

Do not parse the configuration space name.

If set, disables the parsing of the configuration space for subspaces. The space name is taken verbatim to be a configuration space name. This can be used when there can be forward slashes or backslahes in the name which are not escaped.

By default, the configuration space name,

    L"foo\\bar"

is taken to mean the configuration space bar which is a subspace of foo. If KCONF_FLAG_NOPARSENAME is set, then this is taken to mean configuration space foo\bar.

#define KCONF_FLAG_WRITEIFMOD 0x00000040

Only write values back there is a change.

Any write operations using the handle with check if the value being written is different from the value being read from the handle. It will only be written if the value is different.

Note:
Note that the value being read from a handle takes schema and shadowed configuration handles into consideration while the value being written is only written to the topmost layer of configuration that can be written to.

Note also that this flag does not affect binary values.

#define KCONF_MAXCCH_NAME 256

Maximum number of allowed characters (including terminating NULL) in a name.

Note:
This is a hard limit in Windows, since we are mapping configuration spaces to registry keys.

Function Documentation

KHMEXP khm_int32 KHMAPI khc_enum_subspaces | ( | khm_handle | conf,
 |  | khm_handle | prev,
 |  | khm_handle * | next
 | ) |  |

Enumerate the subspaces of a configuration space.

Prepares a configuration space for enumeration and returns the child spaces in no particular order.

Parameters:
[in] | conf | The configuration space to enumerate child spaces
[in] | prev | The previous configuration space returned by khc_enum_subspaces() or NULL if this is the first call. If this is not NULL, then the handle passed in prev will be freed.
[out] | next | If prev was NULL, receives the first sub space found in conf. You must either call khc_enum_subspaces() again with the returned handle or call khc_close_space() to free the returned handle if no more subspaces are required. next can point to the same handle specified in prev.
Return values:
KHM_ERROR_SUCCESS | The call succeeded. There is a valid handle to a configuration space in first_subspace.
KHM_ERROR_INVALID_PARAM | Either conf or prev was not a valid configuration space handle or first_subspace is NULL. Note that prev can be NULL.
KHM_ERROR_NOT_FOUND | There were no subspaces in the configuration space pointed to by conf.
Note:
The configuration spaces that are enumerated directly belong to the configuration space given by conf. This function does not enumerate subspaces of shadowed configuration spaces (see khc_shadow_space()). Even if conf was obtained on a restricted domain (i.e. you specified one or more configuration stores when you openend the handle and didn't include all the configuration stores. See khc_open_space()), the subspaces that are returned are the union of all configuration spaces in all the configuration stores. This is not a bug. This is a feature. In NetIDMgr, a configuartion space exists if some configuration store defines it (or it was created with a call to khc_open_space() even if no configuration store defines it yet). This is the tradeoff you make when using a layered configuration system.
However, the returned handle has the same domain restrictions as conf.

KHMEXP khm_int32 KHMAPI khc_get_config_space_name | ( | khm_handle | conf,
 |  | wchar_t * | buf,
 |  | khm_size * | bufsize
 | ) |  |

Get the name of a configuration space.

Parameters:
[in] | conf | Handle to a configuration space
[out] | buf | The buffer to receive the name. Set to NULL if only the size of the buffer is required.
[in,out] | bufsize | On entry, holds the size of the buffer pointed to by buf. On exit, holds the number of bytes copied into the buffer including the NULL terminator.

KHMEXP khm_int32 KHMAPI khc_get_config_space_parent | ( | khm_handle | conf,
 |  | khm_handle * | parent
 | ) |  |

Get a handle to the parent space.

Parameters:
[in] | conf | Handle to a configuration space
[out] | parent | Handle to the parent configuration space if the call succeeds. Receives NULL otherwise. The returned handle must be closed using khc_close_space()

KHMEXP khm_int32 KHMAPI khc_get_type | ( | khm_handle | conf,
 |  | const wchar_t * | value_name
 | ) |  |

Get the type of a value in a configuration space.

Returns:
The return value is the type of the specified value, or KC_NONE if the value does not exist.

KHMEXP khm_int32 KHMAPI khc_load_schema | ( | khm_handle | conf,
 |  | const kconf_schema * | schema
 | ) |  |

Load a configuration schema into the specified configuration space.

Parameters:
[in] | conf | Handle to a configuration space or NULL to use the root configuration space.
[in] | schema | The schema to load. The schema is assumed to be well formed.
See also:
khc_unload_schema()

KHMEXP khm_int32 KHMAPI khc_open_space | ( | khm_handle | parent,
 |  | const wchar_t * | cspace,
 |  | khm_int32 | flags,
 |  | khm_handle * | result
 | ) |  |

Open a configuration space.

Opens the configuration space specified by cspace. By default, the opened space includes user,machine and schema configuration stores. However, you can specify a subset of these.

If the configuration space does not exist and the flags specify KHM_FLAG_CREATE, then the configuration space is created. The stores that are affected by the create operation depend on flags. If the flags only specifies KCONF_FLAG_MACHINE, then the configuration space is created in the machine store. If flags specifies any combination of stores including KCONF_FLAG_USER, then the configuration space is created in the user store. Note that KCONF_FLAG_SCHEMA is readonly.

Once opened, use khc_close_space() to close the configuration space.

Parameters:
[in] | parent | The parent configuration space. The path specified in cspace is relative to the parent. Set this to NULL to indicate the root configuration space.
[in] | cspace | The configuration path. This can be up to KCONF_MAXCCH_PATH characters in length. Use backslashes to specify hiearchy. Set this to NULL to reopen the parent configuration space.
[in] | flags | Flags. This can be a combination of KCONF_FLAG_* constants and KHM_FLAG_CREATE. If none of KCONF_FLAG_USER, KCONF_FLAG_MACHINE or KCONF_FLAG_SCHEMA is specified, then it defaults to all three.
[out] | result | Pointer to a handle which receives the handle to the opened configuration space if the call succeeds.
Note:
You can re-open a configuration space with different flags such as KCONF_FLAG_MACHINE by specifying NULL for cspace and settings flags to the required flags.

KHMEXP khm_int32 KHMAPI khc_read_binary | ( | khm_handle | conf,
 |  | const wchar_t * | value_name,
 |  | void * | buf,
 |  | khm_size * | bufsize
 | ) |  |

Read a binary value from a configuration space.

The value_name parameter specifies the value to read from the configuration space. This can be either a value name or a value path consisting of a series nested configuration space names followed by the value name all separated by backslashes or forward slashes.

For example: If conf is a handle to the configuration space 'A/B/C', then the value name 'D/E/v' refers to the value named 'v' in the configuration space 'A/B/C/D/E'.

The specific configuration store that is used to access the value depends on the flags that were specified in the call to khc_open_space(). The precedence of configuration stores are as follows:

  • If KCONF_FLAG_USER was specified, then the user configuration space.

  • Otherwise, if KCONF_FLAG_MACHINE was specified, then the machine configuration space.

Note that not specifying any of the configuration store specifiers in the call to khc_open_space() is equivalent to specifying all three. Also note that the schema store (KCONF_FLAG_SCHEMA) does not support binary values.

If the value is not found in the configuration space and any shadowed configuration spaces, the function returns KHM_ERROR_NOT_FOUND. In this case, the buffer is left unmodified.

Parameters:
[in] | buf | Buffer to copy the string to. Specify NULL to just retrieve the number of required bytes.
[in,out] | bufsize | On entry, specifies the number of bytes of space available at the location specified by buf. On exit specifies the number of bytes actually copied or the size of the required buffer if buf is NULL or insufficient.
Return values:
KHM_ERROR_SUCCESS | Success. The data was copied to buf. The number of bytes copied is stored in bufsize
KHM_ERROR_NOT_FOUND | The specified value was not found
KHM_ERROR_INVALID_PARAM | One or more parameters were invalid.
See also:
khc_open_space()

KHMEXP khm_int32 KHMAPI khc_read_int32 | ( | khm_handle | conf,
 |  | const wchar_t * | value_name,
 |  | khm_int32 * | buf
 | ) |  |

Read a 32 bit integer value from a configuration space.

The value_name parameter specifies the value to read from the configuration space. This can be either a value name or a value path consisting of a series nested configuration space names followed by the value name all separated by backslashes or forward slashes.

For example: If conf is a handle to the configuration space 'A/B/C', then the value name 'D/E/v' refers to the value named 'v' in the configuration space 'A/B/C/D/E'.

The specific configuration store that is used to access the value depends on the flags that were specified in the call to khc_open_space(). The precedence of configuration stores are as follows:

  • If KCONF_FLAG_USER was specified, then the user configuration space.

  • Otherwise, if KCONF_FLAG_MACHINE was specified, then the machine configuration space.

  • Otherwise, if KCONF_FLAG_SCHEMA was specified, the the schema store.

Note that not specifying any of the configuration store specifiers in the call to khc_open_space() is equivalent to specifying all three.

If the value is not found in the configuration space and any shadowed configuration spaces, the function returns KHM_ERROR_NOT_FOUND. In this case, the buffer is left unmodified.

Parameters:
[in] | conf | Handle to a configuration space
[in] | value | The value to query
[out] | buf | The buffer to receive the value
Return values:
KHM_ERROR_NOT_READY | The configuration provider has not started.
KHM_ERROR_SUCCESS | Success. The value that was read was placed in buf
KHM_ERROR_NOT_FOUND | The specified value was not found
KHM_ERROR_INVALID_PARAM | One or more parameters were invalid
KHM_ERROR_TYPE_MISMATCH | The specified value was found but was not of the correct type.
See also:
khc_open_space()

KHMEXP khm_int32 KHMAPI khc_read_int64 | ( | khm_handle | conf,
 |  | const wchar_t * | value_name,
 |  | khm_int64 * | buf
 | ) |  |

Read a 64 bit integer value from a configuration space.

The value_name parameter specifies the value to read from the configuration space. This can be either a value name or a value path consisting of a series nested configuration space names followed by the value name all separated by backslashes or forward slashes.

For example: If conf is a handle to the configuration space 'A/B/C', then the value name 'D/E/v' refers to the value named 'v' in the configuration space 'A/B/C/D/E'.

The specific configuration store that is used to access the value depends on the flags that were specified in the call to khc_open_space(). The precedence of configuration stores are as follows:

  • If KCONF_FLAG_USER was specified, then the user configuration space.

  • Otherwise, if KCONF_FLAG_MACHINE was specified, then the machine configuration space.

  • Otherwise, if KCONF_FLAG_SCHEMA was specified, the the schema store.

Note that not specifying any of the configuration store specifiers in the call to khc_open_space() is equivalent to specifying all three.

If the value is not found in the configuration space and any shadowed configuration spaces, the function returns KHM_ERROR_NOT_FOUND. In this case, the buffer is left unmodified.

Parameters:
[in] | conf | Handle to a configuration space
[in] | value_name | The value to query
[out] | buf | The buffer to receive the value
Return values:
KHM_ERROR_NOT_READY | The configuration provider has not started
KHM_ERROR_SUCCESS | Success. The value that was read was placed in buf
KHM_ERROR_NOT_FOUND | The specified value was not found
KHM_ERROR_INVALID_PARAM | One or more parameters were invalid
KHM_ERROR_TYPE_MISMATCH | The specified value was found but was not the correct data type.
See also:
khc_open_space()

KHMEXP khm_int32 KHMAPI khc_read_multi_string | ( | khm_handle | conf,
 |  | const wchar_t * | value_name,
 |  | wchar_t * | buf,
 |  | khm_size * | bufsize
 | ) |  |

Read a multi-string value from a configuration space.

The value_name parameter specifies the value to read from the configuration space. This can be either a value name or a value path consisting of a series nested configuration space names followed by the value name all separated by backslashes or forward slashes.

For example: If conf is a handle to the configuration space 'A/B/C', then the value name 'D/E/v' refers to the value named 'v' in the configuration space 'A/B/C/D/E'.

The specific configuration store that is used to access the value depends on the flags that were specified in the call to khc_open_space(). The precedence of configuration stores are as follows:

  • If KCONF_FLAG_USER was specified, then the user configuration space.

  • Otherwise, if KCONF_FLAG_MACHINE was specified, then the machine configuration space.

  • Otherwise, if KCONF_FLAG_SCHEMA was specified, the the schema store.

A multi-string is a pseudo data type. The value in the configuration store should contain a CSV string. Each comma separated value in the CSV string is considered to be a separate value. Empty values are not allowed. The buffer pointed to by buf will receive these values in the form of a series of NULL terminated strings terminated by an empty string (or equivalently, the last string will be terminated by a double NULL).

Note that not specifying any of the configuration store specifiers in the call to khc_open_space() is equivalent to specifying all three.

If the value is not found in the configuration space and any shadowed configuration spaces, the function returns KHM_ERROR_NOT_FOUND. In this case, the buffer is left unmodified.

Parameters:
[in] | buf | Buffer to copy the multi-string to. Specify NULL to just retrieve the number of required bytes.
[in,out] | bufsize | On entry, specifies the number of bytes of space available at the location specified by buf. On exit specifies the number of bytes actually copied or the size of the required buffer if buf is NULL or insufficient.
Return values:
KHM_ERROR_NOT_READY | The configuration provider has not started
KHM_ERROR_INVALID_PARAM | One or more of the supplied parameters are not valid
KHM_ERROR_TYPE_MISMATCH | The specified value is not a string
KHM_ERROR_TOO_LONG | buf was NULL or the size of the buffer was insufficient. The required size is in bufsize.
KHM_ERROR_SUCCESS | Success. The number of bytes copied is in bufsize.
KHM_ERROR_NOT_FOUND | The value was not found.
See also:
khc_open_space()

KHMEXP khm_int32 KHMAPI khc_read_string | ( | khm_handle | conf,
 |  | const wchar_t * | value_name,
 |  | wchar_t * | buf,
 |  | khm_size * | bufsize
 | ) |  |

Read a string value from a configuration space.

The value_name parameter specifies the value to read from the configuration space. This can be either a value name or a value path consisting of a series nested configuration space names followed by the value name all separated by backslashes or forward slashes.

For example: If conf is a handle to the configuration space 'A/B/C', then the value name 'D/E/v' refers to the value named 'v' in the configuration space 'A/B/C/D/E'.

The specific configuration store that is used to access the value depends on the flags that were specified in the call to khc_open_space(). The precedence of configuration stores are as follows:

  • If KCONF_FLAG_USER was specified, then the user configuration space.

  • Otherwise, if KCONF_FLAG_MACHINE was specified, then the machine configuration space.

  • Otherwise, if KCONF_FLAG_SCHEMA was specified, the the schema store.

Note that not specifying any of the configuration store specifiers in the call to khc_open_space() is equivalent to specifying all three.

If the value is not found in the configuration space and any shadowed configuration spaces, the function returns KHM_ERROR_NOT_FOUND. In this case, the buffer is left unmodified.

Parameters:
[in] | buf | Buffer to copy the string to. Specify NULL to just retrieve the number of required bytes.
[in,out] | bufsize | On entry, specifies the number of bytes of space available at the location specified by buf. On exit specifies the number of bytes actually copied or the size of the required buffer if buf is NULL or insufficient.
Return values:
KHM_ERROR_NOT_READY | The configuration provider has not started
KHM_ERROR_INVALID_PARAM | One or more of the supplied parameters are not valid
KHM_ERROR_TYPE_MISMATCH | The specified value is not a string
KHM_ERROR_TOO_LONG | buf was NULL or the size of the buffer was insufficient. The required size is in bufsize.
KHM_ERROR_SUCCESS | Success. The number of bytes copied is in bufsize.
KHM_ERROR_NOT_FOUND | The value was not found.
See also:
khc_open_space()

KHMEXP khm_int32 KHMAPI khc_remove_space ( khm_handle conf )

Remove a configuration space.

The configuration space will be marked for removal. Once all the handles for the space have been released, it will be deleted. The configuration stores that will be affected are the write enabled configuration stores for the handle.

KHMEXP khm_int32 KHMAPI khc_remove_value | ( | khm_handle | conf,
 |  | const wchar_t * | value_name,
 |  | khm_int32 | flags
 | ) |  |

Remove a value from a configuration space.

Removes a value from one or more configuration stores.

A value can exist in multiple configuration stores. Only the values that are stored in writable stores can be removed. When the function searches for values to remove, it will only look in configuration stores that are specified in the handle. In addition, the configuration stores affected can be further narrowed by specifying them in the flags parameter. If flags is zero, then all the stores visible to the handle are searched. If flags specifies KCONF_FLAG_USER or KCONF_FLAG_MACHINE or both, then only the specified stores are searched, provided that the stores are visible to the handle.

This function only operates on the topmost configuration space visible to the handle. If the configuration handle is shadowed, the shadowed configuration spaces are unaffected by the removal.

Parameters:
[in] | conf | Handle to configuration space to remove value from
[in] | value_name | Value to remove
[in] | flags | Specifies which configuration stores will be affected by the removal. See above.
Return values:
KHM_ERROR_SUCCESS | The value was removed from all the specified configuration stores.
KHM_ERROR_NOT_FOUND | The value was not found.
KHM_ERROR_UNKNOWN | An unknown error occurred while trying to remove the value.
KHM_ERROR_PARTIAL | The value was successfully removed from one or more stores, but the operation failed on one or more other stores.

KHMEXP khm_int32 KHMAPI khc_shadow_space | ( | khm_handle | upper,
 |  | khm_handle | lower
 | ) |  |

Set the shadow space for a configuration handle.

The handle specified by lower becomes a shadow for the handle specified by upper. Any configuration value that is queried in upper that does not exist in upper will be queried in lower.

If upper already had a shadow handle, that handle will be replaced by lower. The handle lower still needs to be closed by a call to khc_close_space(). However, closing lower will not affect upper which will still treat the configuration space pointed to by lower to be it's shadow.

Shadows are specific to handles and not configuration spaces. Shadowing a configuration space using one handle does not affect any other handles which may be obtained for the same configuration space.

Specify NULL for lower to remove any prior shadow.

KHMEXP khm_int32 KHMAPI khc_value_exists | ( | khm_handle | conf,
 |  | const wchar_t * | value
 | ) |  |

Check which configuration stores contain a specific value.

Each value in a configuration space can be contained in zero or more configuration stores. Use this function to determine which configuration stores contain the specific value.

The returned bitmask always indicates a subset of the configuration stores that were specified when opening the configuration space corresponding to conf.

If the specified handle is shadowed (see khc_shadow_space()) and the value is not found in any of the visible stores for the topmost handle, each of the shadowed handles will be tried in turn until the value is found. The return value will correspond to the handle where the value is first found.

Returns:
A combination of KCONF_FLAG_MACHINE, KCONF_FLAG_USER and KCONF_FLAG_SCHEMA indicating which stores contain the value.

KHMEXP khm_int32 KHMAPI khc_write_binary | ( | khm_handle | conf,
 |  | const wchar_t * | value_name,
 |  | void * | buf,
 |  | khm_size | bufsize
 | ) |  |

Write a binary value to a configuration space.

The value_name parameter specifies the value to write to the configuration space. This can be either a value name or a value path consisting of a series nested configuration space names followed by the value name all separated by backslashes or forward slashes.

For example: If conf is a handle to the configuration space 'A/B/C', then the value name 'D/E/v' refers to the value named 'v' in the configuration space 'A/B/C/D/E'.

The specific configuration store that is used to write the value depends on the flags that were specified in the call to khc_open_space(). The precedence of configuration stores are as follows:

  • If KCONF_FLAG_USER was specified, then the user configuration space.

  • Otherwise, if KCONF_FLAG_MACHINE was specified, then the machine configuration space.

Note that not specifying any of the configuration store specifiers in the call to khc_open_space() is equivalent to specifying all three. Also note that the schema store (KCONF_FLAG_SCHEMA) is readonly.

See also:
khc_open_space()

KHMEXP khm_int32 KHMAPI khc_write_int32 | ( | khm_handle | conf,
 |  | const wchar_t * | value_name,
 |  | khm_int32 | buf
 | ) |  |

Write a 32 bit integer value to a configuration space.

The value_name parameter specifies the value to write to the configuration space. This can be either a value name or a value path consisting of a series nested configuration space names followed by the value name all separated by backslashes or forward slashes.

For example: If conf is a handle to the configuration space 'A/B/C', then the value name 'D/E/v' refers to the value named 'v' in the configuration space 'A/B/C/D/E'.

The specific configuration store that is used to write the value depends on the flags that were specified in the call to khc_open_space(). The precedence of configuration stores are as follows:

  • If KCONF_FLAG_USER was specified, then the user configuration space.

  • Otherwise, if KCONF_FLAG_MACHINE was specified, then the machine configuration space.

Note that not specifying any of the configuration store specifiers in the call to khc_open_space() is equivalent to specifying all three. Also note that the schema store (KCONF_FLAG_SCHEMA) is readonly.

If the KCONF_FLAG_WRITEIFMOD flag is specified in the call to khc_open_space() for obtaining the configuration handle, the specified string will only be written if it is different from the value being read from the handle.

See also:
khc_open_space()

KHMEXP khm_int32 KHMAPI khc_write_int64 | ( | khm_handle | conf,
 |  | const wchar_t * | value_name,
 |  | khm_int64 | buf
 | ) |  |

Write a 64 bit integer value to a configuration space.

The value_name parameter specifies the value to write to the configuration space. This can be either a value name or a value path consisting of a series nested configuration space names followed by the value name all separated by backslashes or forward slashes.

For example: If conf is a handle to the configuration space 'A/B/C', then the value name 'D/E/v' refers to the value named 'v' in the configuration space 'A/B/C/D/E'.

The specific configuration store that is used to write the value depends on the flags that were specified in the call to khc_open_space(). The precedence of configuration stores are as follows:

  • If KCONF_FLAG_USER was specified, then the user configuration space.

  • Otherwise, if KCONF_FLAG_MACHINE was specified, then the machine configuration space.

Note that not specifying any of the configuration store specifiers in the call to khc_open_space() is equivalent to specifying all three. Also note that the schema store (KCONF_FLAG_SCHEMA) is readonly.

If the KCONF_FLAG_WRITEIFMOD flag is specified in the call to khc_open_space() for obtaining the configuration handle, the specified string will only be written if it is different from the value being read from the handle.

See also:
khc_open_space()

KHMEXP khm_int32 KHMAPI khc_write_multi_string | ( | khm_handle | conf,
 |  | const wchar_t * | value_name,
 |  | wchar_t * | buf
 | ) |  |

Write a multi-string value to a configuration space.

The value_name parameter specifies the value to write to the configuration space. This can be either a value name or a value path consisting of a series nested configuration space names followed by the value name all separated by backslashes or forward slashes.

For example: If conf is a handle to the configuration space 'A/B/C', then the value name 'D/E/v' refers to the value named 'v' in the configuration space 'A/B/C/D/E'.

The specific configuration store that is used to write the value depends on the flags that were specified in the call to khc_open_space(). The precedence of configuration stores are as follows:

A multi-string is a pseudo data type. The buffer pointed to by buf should contain a sequence of NULL terminated strings terminated by an empty string (or equivalently, the last string should terminate with a double NULL). This will be stored in the value as a CSV string.

  • If KCONF_FLAG_USER was specified, then the user configuration space.

  • Otherwise, if KCONF_FLAG_MACHINE was specified, then the machine configuration space.

Note that not specifying any of the configuration store specifiers in the call to khc_open_space() is equivalent to specifying all three. Also note that the schema store (KCONF_FLAG_SCHEMA) is readonly.

If the KCONF_FLAG_WRITEIFMOD flag is specified in the call to khc_open_space() for obtaining the configuration handle, the specified string will only be written if it is different from the value being read from the handle.

If the KCONF_FLAG_IFMODCI flag is specified along with the KCONF_FLAG_WRITEIFMOD flag, then the string comparison used will be case insensitive.

See also:
khc_open_space()

KHMEXP khm_int32 KHMAPI khc_write_string | ( | khm_handle | conf,
 |  | const wchar_t * | value_name,
 |  | wchar_t * | buf
 | ) |  |

Write a string value to a configuration space.

The value_name parameter specifies the value to write to the configuration space. This can be either a value name or a value path consisting of a series nested configuration space names followed by the value name all separated by backslashes or forward slashes.

For example: If conf is a handle to the configuration space 'A/B/C', then the value name 'D/E/v' refers to the value named 'v' in the configuration space 'A/B/C/D/E'.

The specific configuration store that is used to write the value depends on the flags that were specified in the call to khc_open_space(). The precedence of configuration stores are as follows:

  • If KCONF_FLAG_USER was specified, then the user configuration space.

  • Otherwise, if KCONF_FLAG_MACHINE was specified, then the machine configuration space.

Note that not specifying any of the configuration store specifiers in the call to khc_open_space() is equivalent to specifying all three. Also note that the schema store (KCONF_FLAG_SCHEMA) is readonly.

If the KCONF_FLAG_WRITEIFMOD flag is specified in the call to khc_open_space() for obtaining the configuration handle, the specified string will only be written if it is different from the value being read from the handle.

If the KCONF_FLAG_IFMODCI flag is specified along with the KCONF_FLAG_WRITEIFMOD flag, then the string comparison used will be case insensitive.

Parameters:
[in] | conf | Handle to a configuration space
[in] | value_name | Name of value to write
[in] | buf | A NULL terminated unicode string not exceeding KCONF_MAXCCH_STRING in characters including terminating NULL
See also:
khc_open_space()

Generated on Mon Oct 22 22:56:45 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: kconf_schema Struct Reference

  • Data Fields

kconf_schema Struct Reference
[NetIDMgr Configuration Provider]

#include <kconfig.h>

Detailed Description

Configuration schema descriptor record.

The schema descriptor is a convenient way to provide a default set of configuration options for a part of an application. It describes the configuration spaces and the values and subspaces contained in each space.

See also:
kconf_load_schema()

Data Fields

wchar_t * | name
khm_int32 type
khm_ui_8 value
wchar_t * | description

Field Documentation

wchar_t* kconf_schema::name

name of the object being described. Optional for KC_ENDSPACE type object, but required for everything else. Names can be upto KCONF_MAXCCH_NAME characters in length.

khm_int32 kconf_schema::type

type of the object. Can be one of KC_SPACE, KC_ENDSPACE, KC_INT32, KC_INT64, KC_STRING or KC_BINARY

khm_ui_8 kconf_schema::value

the value of the object. It is not used for KC_SPACE and KC_ENDSPACE typed objects. For a KC_STRING, this contains a pointer to the string value. The string should not be longer than KCONF_MAXCCH_STRING characters. KC_INT32 and KC_INT64 objects store the value directly in this field, while KC_BINARY objects do not support defining a default value here.

wchar_t* kconf_schema::description

a friendly description of the value or configuration space.

The documentation for this struct was generated from the following file:
  • kconfig.h
Generated on Mon Oct 22 22:56:48 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: NetIDMgr Credentials Database

NetIDMgr Credentials Database

Detailed Description

Modules

Identities
Credential sets and individual credentials
Credential attribute types
Credential attributes
Credential types
Generic access to buffer

Data Structures

struct | kcdb_credtype
Credential type descriptor. More...

Defines

#define | KCDB_MAXCCH_SHORT_DESC 256
Maximum length in characters of short description.
#define | KCDB_MAXCB_SHORT_DESC (sizeof(wchar_t) * KCDB_MAXCCH_SHORT_DESC)
Maximum length in bytes of short description.
#define | KCDB_MAXCCH_LONG_DESC 8192
Maximum length in characters of long description.
#define | KCDB_MAXCB_LONG_DESC (sizeof(wchar_t) * KCDB_MAXCCH_LONG_DESC)
Maximum length in characters of long description.
#define | KCDB_MAXCCH_NAME 256
Maximum length in characters of name.
#define | KCDB_MAXCB_NAME (sizeof(wchar_t) * KCDB_MAXCCH_NAME)
Maximum length in bytes of short description.
#define | KCDB_CBSIZE_AUTO ((khm_size) -1)
Automatically determine the number of bytes required.
#define | KCDB_OP_INSERT 1
#define | KCDB_OP_DELETE 2
#define | KCDB_OP_MODIFY 3
#define | KCDB_OP_ACTIVATE 4
#define | KCDB_OP_DEACTIVATE 5
#define | KCDB_OP_HIDE 6
#define | KCDB_OP_UNHIDE 7
#define | KCDB_OP_SETSEARCH 8
#define | KCDB_OP_UNSETSEARCH 9
#define | KCDB_OP_NEW_DEFAULT 10
#define | KCDB_OP_DELCONFIG 11

Define Documentation

#define KCDB_CBSIZE_AUTO ((khm_size) -1)

Automatically determine the number of bytes required.

Can be used in most places where a count of bytes is required. For many objects, the number of bytes that are required can be determined through context and may be ommited. In such cases you can use the KCDB_CBSIZE_AUTO value to specify that the function is to determine the size automatically.

Note:
Not all functions that take a count of bytes support the KCDB_CBSIZE_AUTO value.

#define KCDB_MAXCB_LONG_DESC (sizeof(wchar_t) * KCDB_MAXCCH_LONG_DESC)

Maximum length in characters of long description.

The length includes the terminating NULL character.

#define KCDB_MAXCB_NAME (sizeof(wchar_t) * KCDB_MAXCCH_NAME)

Maximum length in bytes of short description.

The length includes the terminating NULL character.

#define KCDB_MAXCB_SHORT_DESC (sizeof(wchar_t) * KCDB_MAXCCH_SHORT_DESC)

Maximum length in bytes of short description.

The length includes the terminating NULL character.

#define KCDB_MAXCCH_LONG_DESC 8192

Maximum length in characters of long description.

The length includes the terminating NULL character.

#define KCDB_MAXCCH_NAME 256

Maximum length in characters of name.

The length includes the terminating NULL character.

#define KCDB_MAXCCH_SHORT_DESC 256

Maximum length in characters of short description.

The length includes the terminating NULL character.

Generated on Mon Oct 22 22:56:45 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Identities

Identities
[NetIDMgr Credentials Database]

Detailed Description

Functions, macros etc. for manipulating identities.

Data Structures

struct | kcdb_ident_name_xfer
Name transfer structure. More...
struct | kcdb_ident_info

Identity provider interface functions

These functions encapsulate safe calls to the current identity provider. While these functions are exported, applications should not call these functions directly. They are provided for use by the NetIDMgr core application.

KHMEXP khm_int32 KHMAPI | kcdb_identpro_validate_name (const wchar_t *name)
Validate an identity name.
KHMEXP khm_int32 KHMAPI | kcdb_identpro_validate_identity (khm_handle identity)
Validate an identity.
KHMEXP khm_int32 KHMAPI | kcdb_identpro_canon_name (const wchar_t *name_in, wchar_t *name_out, khm_size *cb_name_out)
Canonicalize the name.
KHMEXP khm_int32 KHMAPI | kcdb_identpro_compare_name (const wchar_t *name1, const wchar_t *name2)
Compare two identity names.
KHMEXP khm_int32 KHMAPI | kcdb_identpro_set_default (khm_handle identity)
Set the specified identity as the default.
KHMEXP khm_int32 KHMAPI | kcdb_identpro_set_searchable (khm_handle identity, khm_boolean searchable)
Set the specified identity as searchable.
KHMEXP khm_int32 KHMAPI | kcdb_identpro_update (khm_handle identity)
Update the specified identity.
KHMEXP khm_int32 KHMAPI | kcdb_identpro_get_ui_cb (void *rock)
Obtain the UI callback.
KHMEXP khm_int32 KHMAPI | kcdb_identpro_notify_create (khm_handle identity)
Notify an identity provider of the creation of a new identity.

Flags for identities

#define | KCDB_IDENT_FLAG_CREATE 0x10000000L
Create the identity if it doesn't already exist.
#define | KCDB_IDENT_FLAG_CONFIG 0x00800000L
Has configuration information.
#define | KCDB_IDENT_FLAG_ACTIVE 0x02000000L
Marks the identity as active.
#define | KCDB_IDENT_FLAG_ATTRIBS 0x08000000L
The identity has custom attributes assigned.
#define | KCDB_IDENT_FLAG_DEFAULT 0x00000001L
This is the default identity.
#define | KCDB_IDENT_FLAG_SEARCHABLE 0x00000002L
This identity can be searched.
#define | KCDB_IDENT_FLAG_HIDDEN 0x00000004L
Hidden identity.
#define | KCDB_IDENT_FLAG_INVALID 0x00000008L
Invalid identity.
#define | KCDB_IDENT_FLAG_VALID 0x00000010L
Valid identity.
#define | KCDB_IDENT_FLAG_EXPIRED 0x00000020L
Expired identity.
#define | KCDB_IDENT_FLAG_EMPTY 0x00000040L
Empty identity.
#define | KCDB_IDENT_FLAG_RENEWABLE 0x00000080L
Renewable identity.
#define | KCDB_IDENT_FLAG_INTERACT 0x00000100L
Required user interaction.
#define | KCDB_IDENT_FLAG_CRED_EXP 0x00000200L
Has expired credentials.
#define | KCDB_IDENT_FLAG_CRED_RENEW 0x00000400L
Has renewable credentials.
#define | KCDB_IDENT_FLAG_STICKY 0x00000800L
Sticky identity.
#define | KCDB_IDENT_FLAG_UNKNOWN 0x00001000L
Unknown state.
#define | KCDB_IDENT_FLAGMASK_RDWR 0x00001fffL
Read/write flags mask.

Defines

#define | KCDB_IDENT_MAXCCH_NAME 256
The maximum number of characters (including terminator) that can be specified as an identity name.
#define | KCDB_IDENT_MAXCB_NAME (sizeof(wchar_t) * KCDB_IDENT_MAXCCH_NAME)
The maximum number of bytes that can be specified as an identity name.
#define | KCDB_IDENT_VALID_CHARS L"0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ._@-/"
Valid characters in an identity name.

Functions

KHMEXP khm_boolean KHMAPI | kcdb_identity_is_valid_name (const wchar_t *name)
Check if the given name is a valid identity name.
KHMEXP khm_int32 KHMAPI | kcdb_identity_create (const wchar_t *name, khm_int32 flags, khm_handle *result)
Create or open an identity.
KHMEXP khm_int32 KHMAPI | kcdb_identity_delete (khm_handle id)
Mark an identity for deletion.
KHMEXP khm_int32 KHMAPI | kcdb_identity_set_flags (khm_handle id, khm_int32 flags, khm_int32 mask)
Set or unset the specified flags in the specified identity.
KHMEXP khm_int32 KHMAPI | kcdb_identity_get_flags (khm_handle id, khm_int32 *flags)
Return all the flags for the identity.
KHMEXP khm_int32 KHMAPI | kcdb_identity_get_name (khm_handle id, wchar_t *buffer, khm_size *pcbsize)
Return the name of the identity.
KHMEXP khm_int32 KHMAPI | kcdb_identity_set_default (khm_handle id)
Set the specified identity as the default.
KHMEXP khm_int32 KHMAPI | kcdb_identity_set_default_int (khm_handle id)
Mark the specified identity as the default.
KHMEXP khm_int32 KHMAPI | kcdb_identity_get_default (khm_handle *pvid)
Get the default identity.
KHMEXP khm_int32 KHMAPI | kcdb_identity_get_config (khm_handle id, khm_int32 flags, khm_handle *result)
Get the configuration space for the identity.
KHMEXP khm_int32 KHMAPI | kcdb_identity_hold (khm_handle id)
Hold a reference to an identity.
KHMEXP khm_int32 KHMAPI | kcdb_identity_release (khm_handle id)
Release a reference to an identity.
KHMEXP khm_int32 KHMAPI | kcdb_identity_set_provider (khm_handle sub)
Set the identity provider subscription.
KHMEXP khm_int32 KHMAPI | kcdb_identity_set_type (khm_int32 cred_type)
Set the primary credentials type.
KHMEXP khm_int32 KHMAPI | kcdb_identity_get_provider (khm_handle *sub)
Retrieve the identity provider subscription.
KHMEXP khm_int32 KHMAPI | kcdb_identity_get_type (khm_int32 *ptype)
Retrieve the identity provider credentials type.
KHMEXP khm_boolean KHMAPI | kcdb_identity_is_equal (khm_handle identity1, khm_handle identity2)
Returns TRUE if the two identities are equal.
KHMEXP khm_int32 KHMAPI | kcdb_identity_set_attr (khm_handle identity, khm_int32 attr_id, void *buffer, khm_size cbbuf)
Set an attribute in an identity by attribute id.
KHMEXP khm_int32 KHMAPI | kcdb_identity_set_attrib (khm_handle identity, const wchar_t *attr_name, void *buffer, khm_size cbbuf)
Set an attribute in an identity by name.
KHMEXP khm_int32 KHMAPI | kcdb_identity_get_attr (khm_handle identity, khm_int32 attr_id, khm_int32 *attr_type, void *buffer, khm_size *pcbbuf)
Get an attribute from an identity by attribute id.
KHMEXP khm_int32 KHMAPI | kcdb_identity_get_attrib (khm_handle identity, const wchar_t *attr_name, khm_int32 *attr_type, void *buffer, khm_size *pcbbuf)
Get an attribute from an identity by name.
KHMEXP khm_int32 KHMAPI | kcdb_identity_get_attr_string (khm_handle identity, khm_int32 attr_id, wchar_t *buffer, khm_size *pcbbuf, khm_int32 flags)
Get the string representation of an identity attribute.
KHMEXP khm_int32 KHMAPI | kcdb_identity_get_attrib_string (khm_handle identity, const wchar_t *attr_name, wchar_t *buffer, khm_size *pcbbuf, khm_int32 flags)
Get the string representation of an identity attribute by name.
KHMEXP khm_int32 KHMAPI | kcdb_identity_enum (khm_int32 and_flags, khm_int32 eq_flags, wchar_t *name_buf, khm_size *pcb_buf, khm_size *pn_idents)
Enumerate identities.
KHMEXP khm_int32 KHMAPI | kcdb_identity_refresh (khm_handle vid)
Refresh identity attributes based on root credential set.
KHMEXP khm_int32 KHMAPI | kcdb_identity_refresh_all (void)
Refresh all identities.

Define Documentation

#define KCDB_IDENT_FLAG_ACTIVE 0x02000000L

Marks the identity as active.

An active identity is one that is in active use within NetIDMgr.

Note:
This flag is readonly and cannot be specified when creating or modifying an identity. Once an identity is deleted, it will no longer have this flag.

#define KCDB_IDENT_FLAG_CONFIG 0x00800000L

Has configuration information.

Indicates that the identity has persistent configuration information associated with it.

#define KCDB_IDENT_FLAG_CREATE 0x10000000L

Create the identity if it doesn't already exist.

Note:
Only to be used with kcdb_identity_create()

#define KCDB_IDENT_FLAG_CRED_EXP 0x00000200L

Has expired credentials.

The identity has expired credentials associated with it.

#define KCDB_IDENT_FLAG_CRED_RENEW 0x00000400L

Has renewable credentials.

The identity has renewable credentials associated with it. If the initial credentials of the identity are renewable, then identity is renewable. Hence the KCDB_IDENT_FLAG_RENEWABLE should also be set.

#define KCDB_IDENT_FLAG_DEFAULT 0x00000001L

This is the default identity.

At most one identity will have this flag set at any given time. To set or reset the flag, use kcdb_identity_set_default()

#define KCDB_IDENT_FLAG_EMPTY 0x00000040L

Empty identity.

The identity does not have actual credentials associated with it.

#define KCDB_IDENT_FLAG_EXPIRED 0x00000020L

Expired identity.

This identity has expired and can not be actively used to obtain credentials. This determination is made based on the input of some external entity. This flag may only be set by an identity provider.

#define KCDB_IDENT_FLAG_HIDDEN 0x00000004L

Hidden identity.

The identity will not show up in the identity list window. Once the hidden is switched off, the identity (and all associated credentials) will re-appear in the window

#define KCDB_IDENT_FLAG_INTERACT 0x00000100L

Required user interaction.

The identity is in a state which requires user interaction to activate. Currently, the identity may not be in a state where it can be used to obtain credentials.

A typical example of this is when the primary password for an identity has expired.

#define KCDB_IDENT_FLAG_INVALID 0x00000008L

Invalid identity.

For one reason or another, this identity is invalid. This flag can be set by an identity provider to indicate that this identity does not correspond to an actual identity because an external entity (such as a KDC) has denied it's existence.

The absence of this flag does not imply that the identity is valid. The KCDB_IDENT_FLAG_VALID bit must be set for that to be the case. If neither flag is set, then the status of the identity is not known.

#define KCDB_IDENT_FLAG_RENEWABLE 0x00000080L

Renewable identity.

The initial credentials associated with this identity are renewable. Thus making the whole identity renewable.

#define KCDB_IDENT_FLAG_SEARCHABLE 0x00000002L

This identity can be searched.

The meaning of this flag is left to be interpreted by individual plugins.

#define KCDB_IDENT_FLAG_STICKY 0x00000800L

Sticky identity.

Sticky identities are identities that are always visible in the credentials display even if no credentials are associated with it.

#define KCDB_IDENT_FLAG_UNKNOWN 0x00001000L

Unknown state.

The validity of the identity cannot be determined. This usually means that an authority could not be contacted. This flag is to be treated as transient. If KCDB_IDENT_FLAG_INVALID or KCDB_IDENT_FLAG_VALID is set for the identity, this flag is to be ignored.

#define KCDB_IDENT_FLAG_VALID 0x00000010L

Valid identity.

The identity has been validated through an external entity, or it's validity implied through the existence of credentials for the identity.

The absence of this flag does not imply that the identity is invalid. The KCDB_IDENT_FLAG_INVALID bit must be set for that to be the case. If neither flag is set, then the status of the identity is not known.

#define KCDB_IDENT_FLAGMASK_RDWR 0x00001fffL

Read/write flags mask.

A bitmask that correspond to all the read/write flags in the mask.

Function Documentation

KHMEXP khm_int32 KHMAPI kcdb_identity_create | ( | const wchar_t * | name,
 |  | khm_int32 | flags,
 |  | khm_handle * | result
 | ) |  |

Create or open an identity.

If the KCDB_IDENT_FLAG_CREATE flag is specified in the flags parameter a new identity will be created if one does not already exist with the given name. If an identity by that name already exists, then the existing identity will be opened. The result parameter will receive a held reference to the opened identity. Use kcdb_identity_release() to release the handle.

Parameters:
[in] | name | Name of identity to create
[in] | flags | If KCDB_IDENT_FLAG_CREATE is specified, then the identity will be created if it doesn't already exist. Additional flags can be set here which will be assigned to the identity if it is created. Additional flags have no effect if an existing identity is opened.
[out] | result | If the call is successful, this receives a held reference to the identity. The caller should call kcdb_identity_release() to release the identity once it is no longer needed.

KHMEXP khm_int32 KHMAPI kcdb_identity_delete ( khm_handle id )

Mark an identity for deletion.

The identity will be marked for deletion. The KCDB_IDENT_FLAG_ACTIVE will no longer be present for this identity. Once all references to the identity are released, it will be removed from memory. All associated credentials will also be removed.

KHMEXP khm_int32 KHMAPI kcdb_identity_enum | ( | khm_int32 | and_flags,
 |  | khm_int32 | eq_flags,
 |  | wchar_t * | name_buf,
 |  | khm_size * | pcb_buf,
 |  | khm_size * | pn_idents
 | ) |  |

Enumerate identities.

Enumerates all the active identities that match the criteria specified using and_flags and eq_flags. The condition is applied to all active identities as follows:

    (identity->flags & and_flags) == (eq_flags & and_flags)

Essentially, if a flag is set in and_flags, then that flag in the identity should equal the setting in eq_flags.

Parameters:
[in] | and_flags | See above
[in] | eq_flags | See above
[out] | name_buf | Buffer to receive the list of identity names. Can be NULL if only the required size of the buffer or the number of matching identities is required. The list is returned as a multi string.
[in,out] | pcb_buf | Number of bytes in buffer pointed to by name_buf on entry. On exit, will receive the number of bytes copied. Can be NULL only if name_buf is also NULL. If name_buf is NULL or if pcb_buf indicates that the buffer is insufficient, this will receive the number of bytes required and the return value of the function will be KHM_ERROR_TOO_LONG
[out] | pn_idents | Receives the number of identities that match the given criteria.
Return values:
KHM_ERROR_SUCCESS | If name_buf was valid, the buffer now contains a multi string of identities that matched. If pn_idents was valid, it contains the number of identities matched.
KHM_ERROR_TOO_LONG | No buffer was supplied or the supplied buffer was insufficient. If pn_idents was valid, it contains the number of identities.
KHM_ERROR_INVALID_PARAM | None of the parameters name_buf, pcb_buf and pn_idents were supplied, or pcb_buf was NULL when name_buf was not.
Note:
Calling this function to obtain the required size of the buffer and then calling it with a that sized buffer is not guaranteed to work since the list of identities may change between the two calls.

KHMEXP khm_int32 KHMAPI kcdb_identity_get_attr | ( | khm_handle | identity,
 |  | khm_int32 | attr_id,
 |  | khm_int32 * | attr_type,
 |  | void * | buffer,
 |  | khm_size * | pcbbuf
 | ) |  |

Get an attribute from an identity by attribute id.

Parameters:
[in] | buffer | The buffer that is to receive the attribute value. Set this to NULL if only the required buffer size is to be returned.
[in,out] | cbbuf | The number of bytes available in buffer. If buffer is not sufficient, returns KHM_ERROR_TOO_LONG and sets this to the required buffer size.
[out] | attr_type | Receives the data type of the attribute. Set this to NULL if the type is not required.
Note:
Set both buffer and cbbuf to NULL if only the existence of the attribute is to be checked. If the attribute exists in this identity then the function will return KHM_ERROR_SUCCESS, otherwise it returns KHM_ERROR_NOT_FOUND.

KHMEXP khm_int32 KHMAPI kcdb_identity_get_attr_string | ( | khm_handle | identity,
 |  | khm_int32 | attr_id,
 |  | wchar_t * | buffer,
 |  | khm_size * | pcbbuf,
 |  | khm_int32 | flags
 | ) |  |

Get the string representation of an identity attribute.

A shortcut function which generates the string representation of an identity attribute directly.

Parameters:
[in] | identity | A handle to an identity
[in] | attr_id | The attribute to retrieve
[out] | buffer | A pointer to a string buffer which receives the string form of the attribute. Set this to NULL if you only want to determine the size of the required buffer.
[in,out] | pcbbuf | A pointer to a khm_int32 that, on entry, holds the size of the buffer pointed to by buffer, and on exit, receives the actual number of bytes that were copied.
[in] | flags | Flags for the string conversion. Can be set to one of KCDB_TS_LONG or KCDB_TS_SHORT. The default is KCDB_TS_LONG.
Return values:
KHM_ERROR_SUCCESS | Success
KHM_ERROR_NOT_FOUND | The given attribute was either invalid or was not defined for this identity
KHM_ERROR_INVALID_PARAM | One or more parameters were invalid
KHM_ERROR_TOO_LONG | Either buffer was NULL or the supplied buffer was insufficient

KHMEXP khm_int32 KHMAPI kcdb_identity_get_attrib | ( | khm_handle | identity,
 |  | const wchar_t * | attr_name,
 |  | khm_int32 * | attr_type,
 |  | void * | buffer,
 |  | khm_size * | pcbbuf
 | ) |  |

Get an attribute from an identity by name.

Parameters:
[in] | buffer | The buffer that is to receive the attribute value. Set this to NULL if only the required buffer size is to be returned.
[in,out] | cbbuf | The number of bytes available in buffer. If buffer is not sufficient, returns KHM_ERROR_TOO_LONG and sets this to the required buffer size.
Note:
Set both buffer and cbbuf to NULL if only the existence of the attribute is to be checked. If the attribute exists in this identity then the function will return KHM_ERROR_SUCCESS, otherwise it returns KHM_ERROR_NOT_FOUND.

KHMEXP khm_int32 KHMAPI kcdb_identity_get_attrib_string | ( | khm_handle | identity,
 |  | const wchar_t * | attr_name,
 |  | wchar_t * | buffer,
 |  | khm_size * | pcbbuf,
 |  | khm_int32 | flags
 | ) |  |

Get the string representation of an identity attribute by name.

A shortcut function which generates the string representation of an identity attribute directly.

Parameters:
[in] | identity | A handle to an identity
[in] | attrib | The name of the attribute to retrieve
[out] | buffer | A pointer to a string buffer which receives the string form of the attribute. Set this to NULL if you only want to determine the size of the required buffer.
[in,out] | pcbbuf | A pointer to a khm_int32 that, on entry, holds the size of the buffer pointed to by buffer, and on exit, receives the actual number of bytes that were copied.
[in] | flags | Flags for the string conversion. Can be set to one of KCDB_TS_LONG or KCDB_TS_SHORT. The default is KCDB_TS_LONG.
See also:
kcdb_identity_get_attr_string()

KHMEXP khm_int32 KHMAPI kcdb_identity_get_config | ( | khm_handle | id,
 |  | khm_int32 | flags,
 |  | khm_handle * | result
 | ) |  |

Get the configuration space for the identity.

If the configuration space for the identity does not exist and the flags parameter does not specify KHM_FLAG_CREATE, then the function will return a failure code as specified in khc_open_space(). Depending on whether or not a configuration space was found, the KCDB_IDENT_FLAG_CONFIG flag will be set or reset for the identity.

Parameters:
[in] | id | Identity for which the configuraiton space is requested
[in] | flags | Flags used when calling khc_open_space(). If flags specifies KHM_FLAG_CREATE, then the configuration space is created.
[out] | result | The resulting handle. If the call is successful, this receives a handle to the configuration space. Use khc_close_space() to close the handle.

KHMEXP khm_int32 KHMAPI kcdb_identity_get_default ( khm_handle * pvid )

Get the default identity.

Obtain a held handle to the default identity if there is one. The handle must be freed using kcdb_identity_release().

If there is no default identity, then the handle pointed to by pvid is set to NULL and the function returns KHM_ERROR_NOT_FOUND.

KHMEXP khm_int32 KHMAPI kcdb_identity_get_flags | ( | khm_handle | id,
 |  | khm_int32 * | flags
 | ) |  |

Return all the flags for the identity.

The returned flags may include internal flags.

KHMEXP khm_int32 KHMAPI kcdb_identity_get_name | ( | khm_handle | id,
 |  | wchar_t * | buffer,
 |  | khm_size * | pcbsize
 | ) |  |

Return the name of the identity.

Parameters:
[out] | buffer | Buffer to copy the identity name into. The maximum size of an identity name is KCDB_IDENT_MAXCB_NAME. If buffer is NULL, then the required size of the buffer is returned in pcbsize.
[in,out] | pcbsize | Size of buffer in bytes.

KHMEXP khm_int32 KHMAPI kcdb_identity_get_provider ( khm_handle * sub )

Retrieve the identity provider subscription.

Parameters:
[out] sub Receives the current identity provider subscription. Set to NULL if only the existence of an identity provider needs to be checked.
Return values:
KHM_ERROR_SUCCESS | An identity provider exists. If sub was not NULL, the subscription has been copied there.
KHM_ERROR_NOT_FOUND | There is currently no registered identity provider. If sub was not NULL, the handle it points to has been set to NULL.

KHMEXP khm_int32 KHMAPI kcdb_identity_get_type ( khm_int32 * ptype )

Retrieve the identity provider credentials type.

This is the credentials type that the identity provider has designated as the primary credentials type.

KHMEXP khm_int32 KHMAPI kcdb_identity_hold ( khm_handle vid )

Hold a reference to an identity.

A reference to an identity (a handle) is only valid while it is held.

Note:
Once the handle is released, it can not be revalidated by calling kcdb_identity_hold(). Doing so would lead to unpredictable consequences.

cs_ident must be available.

KHMEXP khm_boolean KHMAPI kcdb_identity_is_equal | ( | khm_handle | identity1,
 |  | khm_handle | identity2
 | ) |  |

Returns TRUE if the two identities are equal.

Also returns TRUE if both identities are NULL.

KHMEXP khm_boolean KHMAPI kcdb_identity_is_valid_name ( const wchar_t * name )

Check if the given name is a valid identity name.

Returns:
TRUE or FALSE to the question, is this valid?

KHMEXP khm_int32 KHMAPI kcdb_identity_refresh ( khm_handle vid )

Refresh identity attributes based on root credential set.

Several flags in an identity are dependent on the credentials that are associated with it in the root credential set. In addition, other flags in an identity depend on external factors that need to be verfied once in a while. This API goes through the root credential set as well as consulting the identity provider to update an identity.

See also:
kcdb_identity_refresh()

KHMEXP khm_int32 KHMAPI kcdb_identity_refresh_all ( void )

Refresh all identities.

Equivalent to calling kcdb_identity_refresh() for all active identities.

See also:
kcdb_identityt_refresh()

KHMEXP khm_int32 KHMAPI kcdb_identity_release ( khm_handle vid )

Release a reference to an identity.

See also:
kcdb_identity_hold()
Note:
cs_ident must be available.

KHMEXP khm_int32 KHMAPI kcdb_identity_set_attr | ( | khm_handle | identity,
 |  | khm_int32 | attr_id,
 |  | void * | buffer,
 |  | khm_size | cbbuf
 | ) |  |

Set an attribute in an identity by attribute id.

Parameters:
[in] | buffer | A pointer to a buffer containing the data to assign to the attribute. Setting buffer to NULL has the effect of removing any data that is already assigned to the attribute. If buffer is non-NULL, then cbbuf should specify the number of bytes in buffer.
[in] | cbbuf | Number of bytes of data in buffer. The individual data type handlers may copy in less than this many bytes in to the credential.

KHMEXP khm_int32 KHMAPI kcdb_identity_set_attrib | ( | khm_handle | identity,
 |  | const wchar_t * | attr_name,
 |  | void * | buffer,
 |  | khm_size | cbbuf
 | ) |  |

Set an attribute in an identity by name.

The attribute name has to be a KCDB registered attribute or property.

Parameters:
[in] cbbuf Number of bytes of data in buffer. The individual data type handlers may copy in less than this many bytes in to the credential.

KHMEXP khm_int32 KHMAPI kcdb_identity_set_default ( khm_handle id )

Set the specified identity as the default.

Specifying NULL effectively makes none of the identities the default.

See also:
kcdb_identity_set_flags()

KHMEXP khm_int32 KHMAPI kcdb_identity_set_default_int ( khm_handle id )

Mark the specified identity as the default.

This API is reserved for use by identity providers as a means of specifying which identity is default. The difference between kcdb_identity_set_default() and kcdb_identity_set_default_int() is in semantics.

  • kcdb_identity_set_default() is used to request the KCDB to designate the specified identity as the default. When processing the request, the KCDB invokes the identity provider to do the necessary work to make the identity the default.

  • kcdb_identity_set_default_int() is used by the identity provider to notify the KCDB that the specified identity is the default. This does not result in the invocation of any other semantics to make the identity the default other than releasing the previous defualt identity and making the specified one the default.

KHMEXP khm_int32 KHMAPI kcdb_identity_set_flags | ( | khm_handle | id,
 |  | khm_int32 | flags,
 |  | khm_int32 | mask
 | ) |  |

Set or unset the specified flags in the specified identity.

Only flags that are in KCDB_IDENT_FLAGMASK_RDWR can be specifed in the flags parameter or the mask parameter. The flags set in the mask parameter of the identity will be set to the corresponding values in the flags parameter.

If KCDB_IDENT_FLAG_INVALID is set using this function, then the KCDB_IDENT_FLAG_VALID will be automatically reset, and vice versa. Resetting either bit does not undo this change, and will leave the identity's validity unspecified. Setting either of KCDB_IDENT_FLAG_INVALID or KCDB_IDENT_FLAG_VALID will automatically reset KCDB_IDENT_FLAG_UNKNOWN.

Note that setting or resetting certain flags have other semantic side-effects:

  • KCDB_IDENT_FLAG_DEFAULT : Setting this is equivalent to calling kcdb_identity_set_default() with id. Resetting this is equivalent to calling kcdb_identity_set_default() with NULL.

  • KCDB_IDENT_FLAG_SEARCHABLE : Setting this will result in the identity provider getting notified of the change. If the identity provider indicates that searchable flag should not be set or reset on the identity, then kcdb_identity_set_flags() will return an error.

Note:
kcdb_identity_set_flags() is not atomic. Even if the function returns a failure code, some flags in the identity may have been set. When calling kcdb_identity_set_flags() always check the flags in the identity using kcdb_identity_get_flags() to check which flags have been set and which have failed.

KHMEXP khm_int32 KHMAPI kcdb_identity_set_provider ( khm_handle sub )

Set the identity provider subscription.

If there was a previous subscription, that subscription will be automatically deleted.

Parameters:
[in] sub New identity provider subscription

KHMEXP khm_int32 KHMAPI kcdb_identity_set_type ( khm_int32 cred_type )

Set the primary credentials type.

The primary credentials type is designated by the identity provider. As such, this function should only be called by an identity provider.

KHMEXP khm_int32 KHMAPI kcdb_identpro_canon_name | ( | const wchar_t * | name_in,
 |  | wchar_t * | name_out,
 |  | khm_size * | cb_name_out
 | ) |  |

Canonicalize the name.

See also:
KMSG_IDENT_CANON_NAME

KHMEXP khm_int32 KHMAPI kcdb_identpro_compare_name | ( | const wchar_t * | name1,
 |  | const wchar_t * | name2
 | ) |  |

Compare two identity names.

See also:
KMSG_IDENT_COMPARE_NAME

KHMEXP khm_int32 KHMAPI kcdb_identpro_get_ui_cb ( void * rock )

Obtain the UI callback.

rock is actually a pointer to a khui_ident_new_creds_cb which is to receive the callback.

See also:
KMSG_IDENT_GET_UI_CALLBACK

KHMEXP khm_int32 KHMAPI kcdb_identpro_notify_create ( khm_handle identity )

Notify an identity provider of the creation of a new identity.

See also:
KMSG_IDENT_NOTIFY_CREATE

KHMEXP khm_int32 KHMAPI kcdb_identpro_set_default ( khm_handle identity )

Set the specified identity as the default.

See also:
KMSG_IDENT_SET_DEFAULT

KHMEXP khm_int32 KHMAPI kcdb_identpro_set_searchable | ( | khm_handle | identity,
 |  | khm_boolean | searchable
 | ) |  |

Set the specified identity as searchable.

See also:
KMSG_IDENT_SET_SEARCHABLE

KHMEXP khm_int32 KHMAPI kcdb_identpro_update ( khm_handle identity )

Update the specified identity.

See also:
KMSG_IDENT_UPDATE

KHMEXP khm_int32 KHMAPI kcdb_identpro_validate_identity ( khm_handle identity )

Validate an identity.

The identity itself needs to be validated. This may involve communicating with an external entity.

See also:
KMSG_IDENT_VALIDATE_IDENTITY

KHMEXP khm_int32 KHMAPI kcdb_identpro_validate_name ( const wchar_t * name )

Validate an identity name.

The name that is provided will be passed through sets of validations. One set, which doesn't depend on the identity provider checks whether the length of the identity name and whether there are any invalid characters in the identity name. If the name passes those tests, then the name is passed down to the identity provider's name validation handler.

Return values:
KHM_ERROR_SUCCESS | The name is valid
KHM_ERROR_TOO_LONG | Too many characters in name
KHM_ERROR_INVALID_NAME | There were invalid characters in the name.
KHM_ERROR_NO_PROVIDER | There is no identity provider; however the name passed the length and character tests.
KHM_ERROR_NOT_IMPLEMENTED | The identity provider doesn't implement a name validation handler; however the name passed the length and character tests.
See also:
KMSG_IDENT_VALIDATE_NAME

Generated on Mon Oct 22 22:56:45 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: kcdb_ident_name_xfer Struct Reference

kcdb_ident_name_xfer Struct Reference
[Identities]

#include <kcreddb.h>

Detailed Description

Name transfer structure.

Used when the KCDB is communicating with the identity provider to exchange string names of identities. See individual KMSG_IDENT message subtypes for the usage of this structure.

Data Fields

const wchar_t * | name_src
const wchar_t * | name_alt
wchar_t * | name_dest
khm_size cb_name_dest
khm_int32 result

Field Documentation

const wchar_t* kcdb_ident_name_xfer::name_src

An identity name. Does not exceed KCDB_IDENT_MAXCCH_NAME characters including terminating NULL.

const wchar_t* kcdb_ident_name_xfer::name_alt

An identity name. Does not exceed KCDB_IDENT_MAXCCH_NAME characters including terminating NULL.

wchar_t* kcdb_ident_name_xfer::name_dest

Pointer to a buffer that is to receive a response string. The size of the buffer in bytes is specified in cb_name_dest.

khm_size kcdb_ident_name_xfer::cb_name_dest

Size of buffer pointed to by name_dest in bytes.

khm_int32 kcdb_ident_name_xfer::result

Receives a result value, which is usually an error code defined in kherror.h, though it is not always.

The documentation for this struct was generated from the following file:
  • kcreddb.h
Generated on Mon Oct 22 22:56:48 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Credential sets and individual credentials

Credential sets and individual credentials
[NetIDMgr Credentials Database]

Modules

Credential sets
Credentials

Typedefs

typedef khm_int32(KHMAPI * | kcdb_cred_apply_func )(khm_handle cred, void *rock)
Credentials process function.
typedef khm_int32(KHMAPI * | kcdb_cred_filter_func )(khm_handle cred, khm_int32 flags, void *rock)
Credentials filter function.
typedef khm_int32(KHMAPI * | kcdb_cred_comp_func )(khm_handle cred1, khm_handle cred2, void *rock)
Credentials compare function.

Typedef Documentation

typedef khm_int32(KHMAPI * kcdb_cred_apply_func)(khm_handle cred, void *rock)

Credentials process function.

This function is called for each credential in a credential set when supplied to kcdb_credset_apply(). It should return KHM_ERROR_SUCCESS to continue the operation, or any other value to terminate the processing.

See also:
kcdb_credset_apply()

typedef khm_int32(KHMAPI * kcdb_cred_comp_func)(khm_handle cred1, khm_handle cred2, void *rock)

Credentials compare function.

Asserts a weak ordering on the credentials that are passed in as cred1 and cred2. It should return:

  • a negative value if cred1 < cred2
  • zero if cred1 == cred2
  • a postive value if cred1 > cred2
    See also:
    kcdb_credset_sort()

    kcdb_credtype

typedef khm_int32(KHMAPI * kcdb_cred_filter_func)(khm_handle cred, khm_int32 flags, void *rock)

Credentials filter function.

Should return non-zero if the credential passed as cred is to be "accepted". The precise consequence of a non-zero return value is determined by the individual function that this call back is passed into.

This function should not call any other function which may modify cred.

See also:
kcdb_credset_collect_filtered()

kcdb_credset_extract_filtered()

Generated on Mon Oct 22 22:56:45 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Credential sets

Credential sets
[Credential sets and individual credentials]

Detailed Description

Data Structures

struct | kcdb_cred_comp_field
Defines a sort criterion for kcdb_cred_comp_generic(). More...
struct | kcdb_cred_comp_order
Defines the sort criteria for kcdb_cred_comp_generic(). More...

Defines

#define | KCDB_DELTA_ADD 1
Credentials were added.
#define | KCDB_DELTA_DEL 2
Credentials were deleted.
#define | KCDB_DELTA_MODIFY 4
Credentials were modified.
#define | KCDB_CREDCOLL_FILTER_ROOT 1
Indicates that the credential to be filtered is from the root store.
#define | KCDB_CREDCOLL_FILTER_SRC 2
Indicates that the credential to be filtered is from the source credential set.
#define | KCDB_CREDCOLL_FILTER_DEST 4
Indicates that the credential to be filtered is from the destination credential set.
#define | KCDB_CRED_COMP_INCREASING 0
Defines the sort order for a field in kcdb_cred_comp_field.
#define | KCDB_CRED_COMP_DECREASING 1
Defines the sort order for a field in kcdb_cred_comp_field.
#define | KCDB_CRED_COMP_INITIAL_FIRST 2
Defines the sort order for a field in kcdb_cred_comp_field.

Functions

KHMEXP khm_int32 KHMAPI | kcdb_credset_create (khm_handle *result)
Create a credential set.
KHMEXP khm_int32 KHMAPI | kcdb_credset_delete (khm_handle credset)
Delete a credential set.
KHMEXP khm_int32 KHMAPI | kcdb_credset_collect (khm_handle cs_dest, khm_handle cs_src, khm_handle identity, khm_int32 type, khm_int32 *delta)
Collect credentials from a credential set to another credential set.
KHMEXP khm_int32 KHMAPI | kcdb_credset_collect_filtered (khm_handle cs_dest, khm_handle cs_src, kcdb_cred_filter_func filter, void *rock, khm_int32 *delta)
Collect credentials from one credential set to another using a filter.
KHMEXP khm_int32 KHMAPI | kcdb_credset_flush (khm_handle credset)
Flush all credentials from a credential set.
KHMEXP khm_int32 KHMAPI | kcdb_credset_extract (khm_handle destcredset, khm_handle sourcecredset, khm_handle identity, khm_int32 type)
Extract credentials from one credential set to another.
KHMEXP khm_int32 KHMAPI | kcdb_credset_extract_filtered (khm_handle destcredset, khm_handle sourcecredset, kcdb_cred_filter_func filter, void *rock)
Extract credentials from one credential set to another using a filter.
KHMEXP khm_int32 KHMAPI | kcdb_credset_get_cred (khm_handle credset, khm_int32 idx, khm_handle *cred)
Retrieve a held reference to a credential in a credential set based on index.
KHMEXP khm_int32 KHMAPI | kcdb_credset_find_filtered (khm_handle credset, khm_int32 idx_start, kcdb_cred_filter_func f, void *rock, khm_handle *cred, khm_int32 *idx)
Search a credential set for a specific credential.
KHMEXP khm_int32 KHMAPI | kcdb_credset_find_cred (khm_handle credset, khm_handle cred_src, khm_handle *cred_dest)
Find matching credential.
KHMEXP khm_int32 KHMAPI | kcdb_credset_del_cred (khm_handle credset, khm_int32 idx)
Delete a credential from a credential set.
KHMEXP khm_int32 KHMAPI | kcdb_credset_del_cred_ref (khm_handle credset, khm_handle cred)
Delete a credential from a credential set by reference.
KHMEXP khm_int32 KHMAPI | kcdb_credset_add_cred (khm_handle credset, khm_handle cred, khm_int32 idx)
Add a credential to a credential set.
KHMEXP khm_int32 KHMAPI | kcdb_credset_get_size (khm_handle credset, khm_size *size)
Get the number of credentials in a credential set.
KHMEXP khm_int32 KHMAPI | kcdb_credset_purge (khm_handle credset)
Removes credentials that have been marked as deleted from a credential set.
KHMEXP khm_int32 KHMAPI | kcdb_credset_apply (khm_handle credset, kcdb_cred_apply_func f, void *rock)
Applies a function to all the credentials in a credentials set.
KHMEXP khm_int32 KHMAPI | kcdb_credset_sort (khm_handle credset, kcdb_cred_comp_func comp, void *rock)
Sort the contents of a credential set.
KHMEXP khm_int32 KHMAPI | kcdb_credset_seal (khm_handle credset)
Seal a credential set.
KHMEXP khm_int32 KHMAPI | kcdb_credset_unseal (khm_handle credset)
Unseal a credential set.
KHMEXP khm_int32 KHMAPI | kcdb_cred_comp_generic (khm_handle cred1, khm_handle cred2, void *rock)
A generic compare function for comparing credentials.

Define Documentation

#define KCDB_CRED_COMP_DECREASING 1

Defines the sort order for a field in kcdb_cred_comp_field.

Sorts lexicographically descending by string representation of field.

#define KCDB_CRED_COMP_INCREASING 0

Defines the sort order for a field in kcdb_cred_comp_field.

Sorts lexicographically ascending by string representation of field.

#define KCDB_CRED_COMP_INITIAL_FIRST 2

Defines the sort order for a field in kcdb_cred_comp_field.

Any credentials which have the KCDB_CRED_FLAG_INITIAL will be grouped above any that don't.

If that does not apply, then credentials from the primary credentials type will be sorted before others.

#define KCDB_CREDCOLL_FILTER_DEST 4

Indicates that the credential to be filtered is from the destination credential set.

See also:
kcdb_credset_collect_filtered()

#define KCDB_CREDCOLL_FILTER_ROOT 1

Indicates that the credential to be filtered is from the root store.

See also:
kcdb_credset_collect_filtered()

#define KCDB_CREDCOLL_FILTER_SRC 2

Indicates that the credential to be filtered is from the source credential set.

See also:
kcdb_credset_collect_filtered()

#define KCDB_DELTA_ADD 1

Credentials were added.

See also:
kcdb_credset_collect()

#define KCDB_DELTA_DEL 2

Credentials were deleted.

See also:
kcdb_credset_collect()

#define KCDB_DELTA_MODIFY 4

Credentials were modified.

See also:
kcdb_credset_collect()

Function Documentation

KHMEXP khm_int32 KHMAPI kcdb_cred_comp_generic | ( | khm_handle | cred1,
 |  | khm_handle | cred2,
 |  | void * | rock
 | ) |  |

A generic compare function for comparing credentials.

This function can be passed as a parameter to kcdb_credset_sort().

The rock parameter to this function should be a pointer to a kcdb_cred_comp_order object. The fields member of the kcdb_cred_comp_order object should point to an array of kcdb_cred_comp_field objects, each of which specifies the sort order in decreasing order of priority. The number of kcdb_cred_comp_field objects in the array should correspond to the nFields member in the kcdb_cred_comp_order object.

The array of kcdb_cred_comp_field objects define the sort criteria, in order. The attrib member should be a valid attribute ID, while the order member determines whether the sort order is increasing or decreasing. The exact meaning or increasing or decreasing depends on the data type of the attribute.

Parameters:
[in] rock a pointer to a kcdb_cred_comp_order object

KHMEXP khm_int32 KHMAPI kcdb_credset_add_cred | ( | khm_handle | credset,
 |  | khm_handle | cred,
 |  | khm_int32 | idx
 | ) |  |

Add a credential to a credential set.

The credential is added by reference. In other words, no copy of the credential is made.

Parameters:
[in] idx Index of the new credential. This must be a value in the range 0..(previous size of credential set) or -1. If -1 is specifed, then the credential is appended at the end of the set.
Note:
The credential set cannot be sealed.

KHMEXP khm_int32 KHMAPI kcdb_credset_apply | ( | khm_handle | credset,
 |  | kcdb_cred_apply_func | f,
 |  | void * | rock
 | ) |  |

Applies a function to all the credentials in a credentials set.

The given function is called for each credential in a credential set. With each iteration, the function is called with a handle to the credential and the user defined parameter rock. If the function returns anything other than KHM_ERROR_SUCCESS, the processing stops.

Parameters:
[in] | credset | The credential set to apply the function to, or NULL if you want to apply this to the root credential set.
[in] | f | Function to call for each credential
[in] | rock | An opaque parameter which is to be passed to 'f' as the second argument.
Return values:
KHM_ERROR_SUCCESS | All the credentials were processed.
KHM_ERROR_EXIT | The supplied function signalled the processing to be aborted.
KHM_ERROR_INVALID_PARAM | One or more parameters were invalid.

KHMEXP khm_int32 KHMAPI kcdb_credset_collect | ( | khm_handle | cs_dest,
 |  | khm_handle | cs_src,
 |  | khm_handle | identity,
 |  | khm_int32 | type,
 |  | khm_int32 * | delta
 | ) |  |

Collect credentials from a credential set to another credential set.

Collecting a subset of credentials from credential set cs_src into credential set cs_dest involves the following steps:

  • Select all credentials from cs_src that matches the identity and type specified in the function call and add them to the cs_dest credential set if they are not there already. Note that if neither credential set is not the root credential store, then the credentials will be added by reference, while if it is the root credential store, the credentials will be duplicated, and the copies will be added to cs_dest.

  • If a selected credential in cs_src already exists in cs_dest, then update the credential in cs_dest with the credential fields in cs_src. In other words, once a credential is found to exist in both cs_src and cs_dest, all the non-null fields from the credential in cs_src will be copied to the credential in cs_dest. Fields which are null (undefined) in cs_src and are non-null in cs_dest will be left unmodified in cs_dest.

One notable exception is the credentials' flags. All flags in cs_src which are not included in KCDB_CRED_FLAGMASK_ADDITIVE will be copied to the corresponding bits in the flags of cs_dest. However, flags that are included in KCDB_CRED_FLAGMASK_ADDITIVE will be added to the corresponding bits in cs_dest.

(See notes below)

  • Remove all credentials from cs_dest that match the identity and type that do not appear in cs_src. (see notes below)

For performance reasons, plugins should use kcdb_credset_collect() to update the root credentials store instead of adding and removing individual credentials from the root store.

Only credentials that are associated with active identities are affected by kcdb_credset_collect().

Parameters:
[in] | cs_dest | A handle to the destination credential set. If this is NULL, then it is assumed to refer to the root credential store.
[in] | cs_src | A handle to the source credential set. If this is NULL, then it is assumed to refer to the root credential store.
[in] | identity | A handle to an identity. Setting this to NULL collects all identities in the credential set.
[in] | type | A credentials type. Setting this to KCDB_CREDTYPE_ALL collects all credential types in the set.
[out] | delta | A bit mask that indicates the modifications that were made to cs_dest as a result of the collect operation. This is a combination of KCDB_DELTA_* values. This parameter can be NULL if the value is not required.
Warning:
If identity and type is set to a wildcard, all credentials in the root store that are not in this credentials set will be deleted.
Note:
Two credentials A and B are considered equal if:
  • They refer to the same identity
  • Both have the same credential type
  • Both have the same name

This is the only supported way of modifying the root credential store.

cs_src and cs_dest can not refer to the same credentials set.

The destination credential set cannot be sealed.

KHMEXP khm_int32 KHMAPI kcdb_credset_collect_filtered | ( | khm_handle | cs_dest,
 |  | khm_handle | cs_src,
 |  | kcdb_cred_filter_func | filter,
 |  | void * | rock,
 |  | khm_int32 * | delta
 | ) |  |

Collect credentials from one credential set to another using a filter.

Similar to kcdb_credset_collect() except instead of selecting credentials by matching against an identity and/or type, a filter function is called. If the filter function returns non-zero for a credential, that credential is selected.

Credentials in the source and destination credential sets are passed into the filter function. Depending on whether the credential is in the source credential set or destination credential set, the flag parameter may have either KCDB_CREDCOLL_FILTER_SRC or KCDB_CREDCOLL_FILTER_DEST bits set. Also, if either one of the credential sets is the root credential store, then additionally KCDB_CREDCOLL_FILTER_ROOT would also be set.

See the kcdb_credset_collect() documentation for explanations of the cs_src, cs_dest and delta parameters which perform identical functions.

Parameters:
[in] | filter | The filter of type kcdb_cred_filter_func
[in] | rock | A custom argument to be passed to the filter function.
See also:
kcdb_credset_collect()

KHMEXP khm_int32 KHMAPI kcdb_credset_create ( khm_handle * result )

Create a credential set.

Credential sets are temporary containers for credentials. These can be used by plug-ins to store credentials while they are being enumerated from an external source. Once all the credentials have been collected into the credential set, the plug-in may call kcdb_credset_collect() to collect the credentials into the root credential store.

The user interface will only display credentials that are in the root credential store. No notifications are generated for changes to a non-root credential set.

Use kcdb_credset_delete() to delete the credential set once it is created.

See also:
kcdb_credset_delete()

kcdb_credset_collect()

KHMEXP khm_int32 KHMAPI kcdb_credset_del_cred | ( | khm_handle | credset,
 |  | khm_int32 | idx
 | ) |  |

Delete a credential from a credential set.

The credential at index idx will be deleted. All the credentials that are at indices idx + 1 and above will be moved down to fill the gap and the size of the credential set will decrease by one.

Use kcdb_credset_del_cred_ref() to delete a credential by reference. Using kcdb_credset_del_cred() is faster than kcdb_credset_del_cred_ref().

If you call kcdb_credset_del_cred() or kcdb_credset_del_cred_ref() from within kcdb_credset_apply(), the credential will only be marked as deleted. They will not be removed. This means that the size of the credential set will not decrease. To purge the deleted credentials from the set, call kcdb_credset_purge() after kcdb_credset_apply() completes.

Note:
The credential set cannot be sealed.
See also:
kcdb_credset_del_cred_ref()

KHMEXP khm_int32 KHMAPI kcdb_credset_del_cred_ref | ( | khm_handle | credset,
 |  | khm_handle | cred
 | ) |  |

Delete a credential from a credential set by reference.

See kcdb_credset_del_cred() for description of what happens when a credential is deleted from a credential set.

Note:
The credential set cannot be sealed.
See also:
kcdb_credset_del_cred()

KHMEXP khm_int32 KHMAPI kcdb_credset_delete ( khm_handle credset )

Delete a credential set.

See also:
kcdb_credset_create()

KHMEXP khm_int32 KHMAPI kcdb_credset_extract | ( | khm_handle | destcredset,
 |  | khm_handle | sourcecredset,
 |  | khm_handle | identity,
 |  | khm_int32 | type
 | ) |  |

Extract credentials from one credential set to another.

Credentials from the source credential set are selected based on the identity and type arguements. If a credential is matched, then it is added to the destcredset.

If the sourcecredset is the root credential set, the added credentials are copies of the actual credentials in the root credential set. Otherwise the credentials are references to the original credentials in the sourcecredset .

Parameters:
[in] | destcredset | Destination credential set. Must be valid.
[in] | sourcecredset | The source credential set. If set to NULL, extracts from the root credential set.
[in] | identity | The identity to match in the source credential set. If set to NULL, matches all identities.
[in] | type | The credential type to match in the source credential set. If set to KCDB_CREDTYPE_INVALID, matches all types.
Note:
This function does not check for duplicate credentials.

The destination credential set cannot be sealed.

KHMEXP khm_int32 KHMAPI kcdb_credset_extract_filtered | ( | khm_handle | destcredset,
 |  | khm_handle | sourcecredset,
 |  | kcdb_cred_filter_func | filter,
 |  | void * | rock
 | ) |  |

Extract credentials from one credential set to another using a filter.

Similar to kcdb_credset_extract() except a filter function is used to determine which credentials should be selected.

Parameters:
[in] rock A custom argument to be passed in to the filter function.
Note:
The destination credential set cannot be sealed.

KHMEXP khm_int32 KHMAPI kcdb_credset_find_cred | ( | khm_handle | credset,
 |  | khm_handle | cred_src,
 |  | khm_handle * | cred_dest
 | ) |  |

Find matching credential.

Searches a credential set for a credential that matches the specified credential. For a credential to be a match, it must have the same identity, credential type and name.

Parameters:
[in] | credset | Credential set to search
[in] | cred_src | Credetial to search on
[out] | cred_dest | receieves the matching credential if the search is successful. If a handle is returend, the kcdb_cred_release() must be used to release the handle. If the matching credential is not required, you can pass in NULL.
Return values:
KHM_ERROR_SUCCESS | The search was successful. A credential was assigned to cred_dest
KHM_ERROR_NOT_FOUND | A matching credential was not found.

KHMEXP khm_int32 KHMAPI kcdb_credset_find_filtered | ( | khm_handle | credset,
 |  | khm_int32 | idx_start,
 |  | kcdb_cred_filter_func | f,
 |  | void * | rock,
 |  | khm_handle * | cred,
 |  | khm_int32 * | idx
 | ) |  |

Search a credential set for a specific credential.

The credential set indicated by credset is searched for a credential that satisfies the predicate function f. Each credential starting at idx_start is passed into the predicate function until it returns a non-zero value. At this point, that credential is passed in to the cred parameter, and the index of the credential is passed into the idx parameter.

Parameters:
[in] | credset | The credential set to search on. Specify NULL if you want to search teh root credential set.
[in] | idx_start | The index at which to start the search after. The first credential passed to the predicate function will be at idx_start + 1. Specify -1 to start from the beginning of the credential set.
[in] | f | The predicate function. The flags parameter of the predicate function will always receive 0.
[in] | rock | An opaque parameter to be passed to the predicate function f.
[out] | cred | A held reference to the credential that satisfied the predicate function or NULL if no such credential was found. Note that if a valid credential is returned, the calling function must release the credential using kcdb_cred_release().
[out] | idx | The index of the credential passed in cred. Specify NULL if the index is not required.
Return values:
KHM_ERROR_SUCCESS | A credential that satisfied the predicate function was found and was assigned to cred.
KHM_ERROR_NOT_FOUND | No credential was found that matched the predicate function.
Note:
When querying credential sets that are shared between threads, it is possible that another thread modifies the credential set between successive calls to kcdb_credset_find_filtered(). Therefore a continued sequences of searches are not guaranteed to exhastively cover the credential set nor to not return duplicate matches. Duplicate matches are possible if the order of the credentials in the set was changed.

KHMEXP khm_int32 KHMAPI kcdb_credset_flush ( khm_handle credset )

Flush all credentials from a credential set.

Deletes all the crednetials from the credential set.

Parameters:
[in] credset A handle to a credential set. Cannot be NULL.
Note:
The credential set cannot be sealed

KHMEXP khm_int32 KHMAPI kcdb_credset_get_cred | ( | khm_handle | credset,
 |  | khm_int32 | idx,
 |  | khm_handle * | cred
 | ) |  |

Retrieve a held reference to a credential in a credential set based on index.

Parameters:
[in] | idx | The index of the credential to retrieve. This is a zero based index which goes from 0 ... (size of credset - 1).
[out] | cred | The held reference to a credential. Call kcdb_cred_release() to release the credential.
Return values:
KHM_ERROR_SUCCESS | Success. cred has a held reference to the credential.
KHM_ERROR_OUT_OF_BOUNDS | The index specified in idx is out of bounds.
KHM_ERROR_DELETED | The credential at index idx has been marked as deleted.
See also:
kcdb_cred_release()

KHMEXP khm_int32 KHMAPI kcdb_credset_get_size | ( | khm_handle | credset,
 |  | khm_size * | size
 | ) |  |

Get the number of credentials in a credential set.

Credentials in a credential set may be volatile. When kcdb_credeset_get_size() is called, the credential set is compacted to only include credentials that are active at the time. However, when you are iterating through the credential set, it might be the case that some credentials would get marked as deleted. These credentials will remain in the credential set until the credential set is discarded or another call to kcdb_credset_get_size() or kdcb_credset_purge() is made.

If the credential set is sealed, then it will not be compacted and will include deleted credentials as well.

See also:
kcdb_credset_purge()

kcdb_credset_get_cred()

KHMEXP khm_int32 KHMAPI kcdb_credset_purge ( khm_handle credset )

Removes credentials that have been marked as deleted from a credential set.

See description of kcdb_credset_purge() for a description of what happens when credntials that are contained in a credential set are deleted by an external entity.

Note:
The credential set cannot be sealed.
See also:
kcdb_credset_get_size()

kcdb_credset_get_cred()

KHMEXP khm_int32 KHMAPI kcdb_credset_seal ( khm_handle credset )

Seal a credential set.

Sealing a credential set makes it read-only. To unseal a credential set, call kcdb_credset_unseal().

Sealing is an additive operation. kcdb_credset_seal() can be called muliple times. However, for every call to kcdb_credset_seal() a call to kcdb_credset_unseal() must be made to undo the seal. The credential set will become unsealed when all the seals are released.

Once sealed, the credential set will not allow any operation that might change its contents. However, a selaed credential set can still be delted.

See also:
kcdb_credset_unseal()

KHMEXP khm_int32 KHMAPI kcdb_credset_sort | ( | khm_handle | credset,
 |  | kcdb_cred_comp_func | comp,
 |  | void * | rock
 | ) |  |

Sort the contents of a credential set.

Parameters:
[in] rock A custom argument to be passed in to the comp function.
Note:
The credential set cannot be sealed.
See also:
kcdb_cred_comp_generic()

KHMEXP khm_int32 KHMAPI kcdb_credset_unseal ( khm_handle credset )

Unseal a credential set.

Undoes what kcdb_credset_seal() did. This does not guarantee that the credential set is unsealed since there may be other seals.

See also:
kcdb_credset_seal()

Generated on Mon Oct 22 22:56:45 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: kcdb_cred_comp_field Struct Reference

kcdb_cred_comp_field Struct Reference
[Credential sets]

#include <kcreddb.h>

Detailed Description

Defines a sort criterion for kcdb_cred_comp_generic().

See also:
kcdb_cred_comp_generic()

Data Fields

khm_int32 attrib
khm_int32 order

Field Documentation

khm_int32 kcdb_cred_comp_field::attrib

a valid attribute ID

khm_int32 kcdb_cred_comp_field::order

one of KCDB_CRED_COMP_INCREASING or KCDB_CRED_COMP_DECREASING. Optionally, KCDB_CRED_COMP_INITIAL_FIRST may be combined with either.

The documentation for this struct was generated from the following file:
  • kcreddb.h
Generated on Mon Oct 22 22:56:48 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: kcdb_cred_comp_order Struct Reference

kcdb_cred_comp_order Struct Reference
[Credential sets]

#include <kcreddb.h>

Detailed Description

Defines the sort criteria for kcdb_cred_comp_generic().

See also:
kcdb_cred_comp_generic()

Data Fields

khm_int32 | nFields
kcdb_cred_comp_field * | fields
The documentation for this struct was generated from the following file:
  • kcreddb.h
Generated on Mon Oct 22 22:56:48 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Credentials

Credentials
[Credential sets and individual credentials]

Detailed Description

Data Structures

struct | kcdb_cred_request
Generic credentials request. More...

Defines

#define | KCDB_CRED_MAXCCH_NAME 256
Maximum number of characters in a credential name.
#define | KCDB_CRED_MAXCB_NAME (sizeof(wchar_t) * KCDB_CRED_MAXCCH_NAME)
Maximum number of bytes in a credential name.
#define | KCDB_CRED_FLAG_DELETED 0x00000008
Marked as deleted.
#define | KCDB_CRED_FLAG_RENEWABLE 0x00000010
Renewable.
#define | KCDB_CRED_FLAG_INITIAL 0x00000020
Initial.
#define | KCDB_CRED_FLAG_EXPIRED 0x00000040
Expired.
#define | KCDB_CRED_FLAG_INVALID 0x00000080
Invalid.
#define | KCDB_CRED_FLAG_SELECTED 0x00000100
Credential is selected.
#define | KCDB_CRED_FLAGMASK_ALL 0x0000ffff
Bitmask indicating all known credential flags.
#define | KCDB_CRED_FLAGMASK_EXT (KCDB_CRED_FLAG_INITIAL | KCDB_CRED_FLAG_EXPIRED | KCDB_CRED_FLAG_INVALID | KCDB_CRED_FLAG_RENEWABLE)
External flags.
#define | KCDB_CRED_FLAGMASK_ADDITIVE KCDB_CRED_FLAG_SELECTED
Bitmask indicating dditive flags.

Functions

KHMEXP khm_int32 KHMAPI | kcdb_cred_create (const wchar_t *name, khm_handle identity, khm_int32 cred_type, khm_handle *result)
Create a new credential.
KHMEXP khm_int32 KHMAPI | kcdb_cred_dup (khm_handle cred, khm_handle *newcred)
Duplicate an existing credential.
KHMEXP khm_int32 KHMAPI | kcdb_cred_update (khm_handle vdest, khm_handle vsrc)
Updates one credential using field values from another.
KHMEXP khm_int32 KHMAPI | kcdb_cred_set_attrib (khm_handle cred, const wchar_t *name, void *buffer, khm_size cbbuf)
Set an attribute in a credential by name.
KHMEXP khm_int32 KHMAPI | kcdb_cred_set_attr (khm_handle cred, khm_int32 attr_id, void *buffer, khm_size cbbuf)
Set an attribute in a credential by attribute id.
KHMEXP khm_int32 KHMAPI | kcdb_cred_get_attrib (khm_handle cred, const wchar_t *name, khm_int32 *attr_type, void *buffer, khm_size *cbbuf)
Get an attribute from a credential by name.
KHMEXP khm_int32 KHMAPI | kcdb_cred_get_attr (khm_handle cred, khm_int32 attr_id, khm_int32 *attr_type, void *buffer, khm_size *cbbuf)
Get an attribute from a credential by attribute id.
KHMEXP khm_int32 KHMAPI | kcdb_cred_get_name (khm_handle cred, wchar_t *buffer, khm_size *cbbuf)
Get the name of a credential.
KHMEXP khm_int32 KHMAPI | kcdb_cred_get_attr_string (khm_handle vcred, khm_int32 attr_id, wchar_t *buffer, khm_size *pcbbuf, khm_int32 flags)
Get the string representation of a credential attribute.
KHMEXP khm_int32 KHMAPI | kcdb_cred_get_attrib_string (khm_handle cred, const wchar_t *name, wchar_t *buffer, khm_size *cbbuf, khm_int32 flags)
Get the string representation of a credential attribute by name.
KHMEXP khm_int32 KHMAPI | kcdb_cred_get_identity (khm_handle cred, khm_handle *identity)
Get a held reference to the identity associated with a credential.
KHMEXP khm_int32 KHMAPI | kcdb_cred_set_identity (khm_handle vcred, khm_handle id)
Set the identity of a credential.
KHMEXP khm_int32 KHMAPI | kcdb_cred_get_serial (khm_handle cred, khm_ui_8 *pserial)
Get the serial number for the credential.
KHMEXP khm_int32 KHMAPI | kcdb_cred_get_type (khm_handle cred, khm_int32 *type)
Get the type of the credential.
KHMEXP khm_int32 KHMAPI | kcdb_cred_get_flags (khm_handle cred, khm_int32 *flags)
Retrieve flags from a credential.
KHMEXP khm_int32 KHMAPI | kcdb_cred_set_flags (khm_handle cred, khm_int32 flags, khm_int32 mask)
Set the flags of a credential.
KHMEXP khm_int32 KHMAPI | kcdb_cred_hold (khm_handle cred)
Hold a reference to a credential.
KHMEXP khm_int32 KHMAPI | kcdb_cred_release (khm_handle cred)
Release a held reference to a credential.
KHMEXP khm_int32 KHMAPI | kcdb_cred_delete (khm_handle cred)
Delete a credential.
KHMEXP khm_int32 KHMAPI | kcdb_creds_comp_attrib (khm_handle cred1, khm_handle cred2, const wchar_t *name)
Compare an attribute of two credentials by name.
KHMEXP khm_int32 KHMAPI | kcdb_creds_comp_attr (khm_handle cred1, khm_handle cred2, khm_int32 attr_id)
Compare an attribute of two credentials by attribute id.
KHMEXP khm_int32 KHMAPI | kcdb_creds_is_equal (khm_handle cred1, khm_handle cred2)
Compare two credentials for equivalence.

Define Documentation

#define KCDB_CRED_FLAG_EXPIRED 0x00000040

Expired.

The credential's lifetime has ended.

#define KCDB_CRED_FLAG_INITIAL 0x00000020

Initial.

Initial credentials form the basis of an identity. Some properties of an initial credential, such as being renewable, are directly inherited by the identity. An identity is also automatically considered valid if it contains a valid initial credential.

#define KCDB_CRED_FLAG_INVALID 0x00000080

Invalid.

The credential can no longer serve its intended function. This may be because it is expired and is not renewable, or its renewable time period has also expired, or for some other reason.

#define KCDB_CRED_FLAG_SELECTED 0x00000100

Credential is selected.

Indicates that the credential is selected. Note that using this flag may be subject to race conditions.

#define KCDB_CRED_FLAGMASK_ADDITIVE KCDB_CRED_FLAG_SELECTED

Bitmask indicating dditive flags.

Additive flags are special flags which are added to exiting credentials based on new credentials when doing a collect operation. See details on kcdb_credset_collect()

See also:
kcdb_credset_collect()

#define KCDB_CRED_FLAGMASK_EXT (KCDB_CRED_FLAG_INITIAL | KCDB_CRED_FLAG_EXPIRED | KCDB_CRED_FLAG_INVALID | KCDB_CRED_FLAG_RENEWABLE)

External flags.

These are flags that are provided by the credentials providers. The other flags are internal to KCDB and should not be modified.

Function Documentation

KHMEXP khm_int32 KHMAPI kcdb_cred_create | ( | const wchar_t * | name,
 |  | khm_handle | identity,
 |  | khm_int32 | cred_type,
 |  | khm_handle * | result
 | ) |  |

Create a new credential.

Parameters:
[in] | name | Name of credential. name cannot be NULL and cannot exceed KCDB_CRED_MAXCCH_NAME unicode characters including the NULL terminator.
[in] | identity | A reference to an identity.
[in] | cred_type | A credentials type identifier for the credential.
[out] | result | Gets a held reference to the newly created credential. Call kcdb_cred_release() or kcdb_cred_delete() to release the reference.
See also:
kcdb_cred_release()

KHMEXP khm_int32 KHMAPI kcdb_cred_delete ( khm_handle cred )

Delete a credential.

The credential will be marked for deletion and will continue to exist until all held references are released. If the credential is bound to a credential set or the root credential store, it will be removed from the respective container.

KHMEXP khm_int32 KHMAPI kcdb_cred_dup | ( | khm_handle | cred,
 |  | khm_handle * | newcred
 | ) |  |

Duplicate an existing credential.

Parameters:
[out] newcred A held reference to the new credential if the call succeeds.

KHMEXP khm_int32 KHMAPI kcdb_cred_get_attr | ( | khm_handle | cred,
 |  | khm_int32 | attr_id,
 |  | khm_int32 * | attr_type,
 |  | void * | buffer,
 |  | khm_size * | cbbuf
 | ) |  |

Get an attribute from a credential by attribute id.

Parameters:
[in] | buffer | The buffer that is to receive the attribute value. Set this to NULL if only the required buffer size is to be returned.
[in,out] | cbbuf | The number of bytes available in buffer. If buffer is not sufficient, returns KHM_ERROR_TOO_LONG and sets this to the required buffer size.
[out] | attr_type | Receives the data type of the attribute. Set this to NULL if the type is not required.
Note:
Set both buffer and cbbuf to NULL if only the existence of the attribute is to be checked. If the attribute exists in this credential then the function will return KHM_ERROR_SUCCESS, otherwise it returns KHM_ERROR_NOT_FOUND.

KHMEXP khm_int32 KHMAPI kcdb_cred_get_attr_string | ( | khm_handle | vcred,
 |  | khm_int32 | attr_id,
 |  | wchar_t * | buffer,
 |  | khm_size * | pcbbuf,
 |  | khm_int32 | flags
 | ) |  |

Get the string representation of a credential attribute.

A shortcut function which generates the string representation of a credential attribute directly.

Parameters:
[in] | vcred | A handle to a credential
[in] | attr_id | The attribute to retrieve
[out] | buffer | A pointer to a string buffer which receives the string form of the attribute. Set this to NULL if you only want to determine the size of the required buffer.
[in,out] | pcbbuf | A pointer to a khm_int32 that, on entry, holds the size of the buffer pointed to by buffer, and on exit, receives the actual number of bytes that were copied.
[in] | flags | Flags for the string conversion. Can be set to one of KCDB_TS_LONG or KCDB_TS_SHORT. The default is KCDB_TS_LONG.
Return values:
KHM_ERROR_SUCCESS | Success
KHM_ERROR_NOT_FOUND | The given attribute was either invalid or was not defined for this credential
KHM_ERROR_INVALID_PARAM | One or more parameters were invalid
KHM_ERROR_TOO_LONG | Either buffer was NULL or the supplied buffer was insufficient

KHMEXP khm_int32 KHMAPI kcdb_cred_get_attrib | ( | khm_handle | cred,
 |  | const wchar_t * | name,
 |  | khm_int32 * | attr_type,
 |  | void * | buffer,
 |  | khm_size * | cbbuf
 | ) |  |

Get an attribute from a credential by name.

Parameters:
[in] | buffer | The buffer that is to receive the attribute value. Set this to NULL if only the required buffer size is to be returned.
[in,out] | cbbuf | The number of bytes available in buffer. If buffer is not sufficient, returns KHM_ERROR_TOO_LONG and sets this to the required buffer size.
Note:
Set both buffer and cbbuf to NULL if only the existence of the attribute is to be checked. If the attribute exists in this credential then the function will return KHM_ERROR_SUCCESS, otherwise it returns KHM_ERROR_NOT_FOUND.

KHMEXP khm_int32 KHMAPI kcdb_cred_get_attrib_string | ( | khm_handle | cred,
 |  | const wchar_t * | name,
 |  | wchar_t * | buffer,
 |  | khm_size * | cbbuf,
 |  | khm_int32 | flags
 | ) |  |

Get the string representation of a credential attribute by name.

A shortcut function which generates the string representation of a credential attribute directly.

Parameters:
[in] | vcred | A handle to a credential
[in] | attrib | The name of the attribute to retrieve
[out] | buffer | A pointer to a string buffer which receives the string form of the attribute. Set this to NULL if you only want to determine the size of the required buffer.
[in,out] | pcbbuf | A pointer to a khm_int32 that, on entry, holds the size of the buffer pointed to by buffer, and on exit, receives the actual number of bytes that were copied.
[in] | flags | Flags for the string conversion. Can be set to one of KCDB_TS_LONG or KCDB_TS_SHORT. The default is KCDB_TS_LONG.
See also:
kcdb_cred_get_attr_string()

KHMEXP khm_int32 KHMAPI kcdb_cred_get_flags | ( | khm_handle | cred,
 |  | khm_int32 * | flags
 | ) |  |

Retrieve flags from a credential.

The flags returned will be place in the location pointed to by flags. Note that the specified credential must be an active credential for the operation to succeed. This means the KCDB_CRED_FLAG_DELETED will never be retured by this function.

KHMEXP khm_int32 KHMAPI kcdb_cred_get_identity | ( | khm_handle | cred,
 |  | khm_handle * | identity
 | ) |  |

Get a held reference to the identity associated with a credential.

Use kcdb_identity_release() to release the reference that is returned.

See also:
kcdb_identity_relase()

KHMEXP khm_int32 KHMAPI kcdb_cred_get_name | ( | khm_handle | cred,
 |  | wchar_t * | buffer,
 |  | khm_size * | cbbuf
 | ) |  |

Get the name of a credential.

Parameters:
[in] | buffer | The buffer that is to receive the credential name. Set this to NULL if only the required buffer size is to be returned.
[in,out] | cbbuf | The number of bytes available in buffer. If buffer is not sufficient, returns KHM_ERROR_TOO_LONG and sets this to the required buffer size.

KHMEXP khm_int32 KHMAPI kcdb_cred_get_serial | ( | khm_handle | cred,
 |  | khm_ui_8 * | pserial
 | ) |  |

Get the serial number for the credential.

Each credential gets assigned a serial number at the time it is created. This will stay with the credential for its lifetime.

Parameters:
[out] pserial Receives the serial number. Cannot be NULL.

KHMEXP khm_int32 KHMAPI kcdb_cred_get_type | ( | khm_handle | cred,
 |  | khm_int32 * | type
 | ) |  |

Get the type of the credential.

The returned type is a credential type. Doh.

Parameters:
[out] type Receives the type. Cannot be NULL.

KHMEXP khm_int32 KHMAPI kcdb_cred_hold ( khm_handle cred )

Hold a reference to a credential.

Use kcdb_cred_release() to release the reference.

See also:
kcdb_cred_release()

KHMEXP khm_int32 KHMAPI kcdb_cred_set_attr | ( | khm_handle | cred,
 |  | khm_int32 | attr_id,
 |  | void * | buffer,
 |  | khm_size | cbbuf
 | ) |  |

Set an attribute in a credential by attribute id.

Parameters:
[in] | buffer | A pointer to a buffer containing the data to assign to the attribute. Setting this to NULL has the effect of removing any data that is already assigned to the attribute. If buffer is non-NULL, then cbbuf should specify the number of bytes in buffer.
[in] | cbbuf | Number of bytes of data in buffer. The individual data type handlers may copy in less than this many bytes in to the credential.

KHMEXP khm_int32 KHMAPI kcdb_cred_set_attrib | ( | khm_handle | cred,
 |  | const wchar_t * | name,
 |  | void * | buffer,
 |  | khm_size | cbbuf
 | ) |  |

Set an attribute in a credential by name.

Parameters:
[in] cbbuf Number of bytes of data in buffer. The individual data type handlers may copy in less than this many bytes in to the credential. For some data types where the size of the buffer is fixed or can be determined from its contents, you can specify KCDB_CBSIZE_AUTO for this parameter.

KHMEXP khm_int32 KHMAPI kcdb_cred_set_flags | ( | khm_handle | cred,
 |  | khm_int32 | flags,
 |  | khm_int32 | mask
 | ) |  |

Set the flags of a credential.

The flags specified in the mask parameter will be set to the values specified in the flags parameter. The flags that are not included in mask will not be modified.

This function can not be used to set the KCDB_CRED_FLAG_DELETED flag. If this bit is specified in either flags or mask, it will be ignored.

See also:
KCDB_CRED_FLAGMASK_ALL

KHMEXP khm_int32 KHMAPI kcdb_cred_set_identity | ( | khm_handle | vcred,
 |  | khm_handle | id
 | ) |  |

Set the identity of a credential.

While it is ill-advised to change the identity of a credential that has been placed in one or more credential sets, there can be legitimate reasons for doing so. Only change the identity of a credential that is not placed in a credential set or placed in a credential set that is only used by a single entity.

KHMEXP khm_int32 KHMAPI kcdb_cred_update | ( | khm_handle | vdest,
 |  | khm_handle | vsrc
 | ) |  |

Updates one credential using field values from another.

All fields that exist in vsrc will get copied to vdest and will overwrite any values that are already there in vdest. However any values that exist in vdest taht do not exist in vsrc will not be modified.

Return values:
KHM_ERROR_SUCCESS | vdest was successfully updated
KHM_ERROR_EQUIVALENT | all fields in vsrc were present and equivalent in vdest

KHMEXP khm_int32 KHMAPI kcdb_creds_comp_attr | ( | khm_handle | cred1,
 |  | khm_handle | cred2,
 |  | khm_int32 | attr_id
 | ) |  |

Compare an attribute of two credentials by attribute id.

Returns:
The return value is dependent on the type of the attribute and indicate a weak ordering of the attribute values of the two credentials. If one or both credentials do not contain the attribute, the return value is 0, which signifies that no ordering can be determined.

KHMEXP khm_int32 KHMAPI kcdb_creds_comp_attrib | ( | khm_handle | cred1,
 |  | khm_handle | cred2,
 |  | const wchar_t * | name
 | ) |  |

Compare an attribute of two credentials by name.

Returns:
The return value is dependent on the type of the attribute and indicate a weak ordering of the attribute values of the two credentials. If one or both credentials do not contain the attribute, the return value is 0, which signifies that no ordering can be determined.

KHMEXP khm_int32 KHMAPI kcdb_creds_is_equal | ( | khm_handle | cred1,
 |  | khm_handle | cred2
 | ) |  |

Compare two credentials for equivalence.

Returns:
Non-zero if the two credentials are equal. Zero otherwise.
Note:
Two credentials are considered equal if all the following hold:
  • Both refer to the same identity.
  • Both have the same name.
  • Both have the same type.

Generated on Mon Oct 22 22:56:45 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: kcdb_cred_request Struct Reference

kcdb_cred_request Struct Reference
[Credentials]

#include <kcreddb.h>

Detailed Description

Generic credentials request.

This data structure is used as the format for a generic credentials reqeust for a KMSG_KCDB_REQUEST message. A plugin typically publishes this message so that a credentials provider may handle it and in response, obtain the specified credential.

While the identity, type and name members of the structure are all optional, typically one would specify all three or at least two for a credential provider to be able to provide the credential unambigously.

Credential providers do not need to respond to KMSG_KCDB_REQUEST messages. However, if they do, they should make sure that they are the only credential provider that is responding by setting the semaphore member to a non-zero value. The semaphore is set to zero when a request is initially sent out. When incrementing the semaphore, the plugin should use a thread safe mechanism to ensure that there are no race conditions that would allow more than one provider to respond to the message.

Data Fields

khm_handle identity
khm_int32 type
wchar_t * | name
khm_handle dest_credset
void * | vparam
long | semaphore

Field Documentation

khm_handle kcdb_cred_request::identity

Identity of the credential. Set to NULL if not specified.

khm_int32 kcdb_cred_request::type

Type of the credential. Set to KCDB_CREDTYPE_INVALID if not specified.

wchar_t* kcdb_cred_request::name

Name of the credential. Set to NULL if not specified.

khm_handle kcdb_cred_request::dest_credset

If non-NULL, instructs whoever is handling the request that the credential thus obtained be placed in this credential set in addition to whereever it may place newly acquired credentials. Note that while this can be NULL if the new credential does not need to be placed in a credential set, it can not equal the root credential set.

void* kcdb_cred_request::vparam

An unspecified parameter. Specific credential types may specify how this field is to be used.

long kcdb_cred_request::semaphore

Incremented by one when this request is answered. Only one credential provider is allowed to answer a KMSG_KCDB_REQUEST message. Initially, when the message is sent out, this member should be set to zero.

The documentation for this struct was generated from the following file:
  • kcreddb.h
Generated on Mon Oct 22 22:56:48 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Credential attribute types

Credential attribute types
[NetIDMgr Credentials Database]

Data Structures

struct | kcdb_type
A data type descriptor. More...

Conversion functions

KHMEXP void KHMAPI | TimetToFileTime (time_t t, LPFILETIME pft)
Convert a time_t value to FILETIME.
KHMEXP void KHMAPI | TimetToFileTimeInterval (time_t t, LPFILETIME pft)
Convert a time_t interval to a FILETIME interval.
KHMEXP long KHMAPI | FtIntervalToSeconds (LPFILETIME pft)
Convert a FILETIME interval to seconds.
KHMEXP long KHMAPI | FtIntervalToMilliseconds (LPFILETIME pft)
Convert a FILETIME interval to milliseconds.
KHMEXP long KHMAPI | FtCompare (LPFILETIME pft1, LPFILETIME pft2)
Compare two FILETIME values.
KHMEXP khm_int64 KHMAPI | FtToInt (LPFILETIME pft)
Convert a FILETIME to a 64 bit int.
KHMEXP FILETIME KHMAPI | IntToFt (khm_int64 i)
Convert a 64 bit int to a FILETIME.
KHMEXP FILETIME KHMAPI | FtSub (LPFILETIME ft1, LPFILETIME ft2)
Calculate the difference between two FILETIMEs.
KHMEXP FILETIME KHMAPI | FtAdd (LPFILETIME ft1, LPFILETIME ft2)
Calculate the sum of two FILETIMEs.
KHMEXP khm_int32 KHMAPI | FtIntervalToString (LPFILETIME data, wchar_t *buffer, khm_size *cb_buf)
Convert a FILETIME inverval to a string.
KHMEXP khm_int32 KHMAPI | IntervalStringToFt (FILETIME *pft, wchar_t *str)
Parse a string representing an interval into a FILETIME interval.
KHMEXP long KHMAPI | FtIntervalMsToRepChange (LPFILETIME pft)
Return number of milliseconds till next representation change.
KHMEXP int KHMAPI | AnsiStrToUnicode (wchar_t *wstr, size_t cbwstr, const char *astr)
Convert a safe ANSI string to a Unicode string.
KHMEXP int KHMAPI | UnicodeStrToAnsi (char *dest, size_t cbdest, const wchar_t *src)
Convert a Unicode string to ANSI.

Flags for kcdb_type::toString

#define | KCDB_TS_SHORT 1
Specify that the short form of the string representation should be returned.
#define | KCDB_TS_LONG 0
Specify that the long form of the string representation should be returned.

Flags for kcdb_type

#define | KCDB_TYPE_FLAG_CB_AUTO 16
The type supports KCDB_CBSIZE_AUTO.
#define | KCDB_TYPE_FLAG_CB_MIN 128
The cb_min member is valid.
#define | KCDB_TYPE_FLAG_CB_MAX 256
The cb_max member is valid.
#define | KCDB_TYPE_FLAG_CB_FIXED (KCDB_TYPE_FLAG_CB_AUTO|KCDB_TYPE_FLAG_CB_MIN|KCDB_TYPE_FLAG_CB_MAX)
Denotes that objects of this type have a fixed size.

Standard type identifiers and names

#define | KCDB_TYPE_MAX_ID 255
#define | KCDB_TYPE_INVALID (-1)
Invalid type.
#define | KCDB_TYPE_ALL KCDB_TYPE_INVALID
All types.
#define | KCDB_TYPE_VOID 0
Void.
#define | KCDB_TYPE_STRING 1
String.
#define | KCDB_TYPE_DATE 2
Data.
#define | KCDB_TYPE_INTERVAL 3
Interval.
#define | KCDB_TYPE_INT32 4
32-bit integer
#define | KCDB_TYPE_INT64 5
64-bit integer
#define | KCDB_TYPE_DATA 6
Raw data.
#define | KCDB_TYPENAME_VOID L"Void"
#define | KCDB_TYPENAME_STRING L"String"
#define | KCDB_TYPENAME_DATE L"Date"
#define | KCDB_TYPENAME_INTERVAL L"Interval"
#define | KCDB_TYPENAME_INT32 L"Int32"
#define | KCDB_TYPENAME_INT64 L"Int64"
#define | KCDB_TYPENAME_DATA L"Data"

Defines

#define | KCDB_TYPE_MAXCB 16384
The maximum number of bytes allowed for a value of any type.

Typedefs

typedef khm_int32(KHMAPI * | kcdb_dtf_toString )(const void *data, khm_size cb_data, wchar_t *s_buf, khm_size *pcb_s_buf, khm_int32 flags)
Convert a field to a string.
typedef khm_boolean(KHMAPI * | kcdb_dtf_isValid )(const void *data, khm_size cb_data)
Verifies whetehr the given buffer contains valid data.
typedef khm_int32(KHMAPI * | kcdb_dtf_comp )(const void *data_l, khm_size cb_data_l, const void *data_r, khm_size cb_data_r)
Compare two fields.
typedef khm_int32(KHMAPI * | kcdb_dtf_dup )(const void *data_src, khm_size cb_data_src, void *data_dst, khm_size *pcb_data_dst)
Duplicate a data field.

Functions

KHMEXP khm_int32 KHMAPI | kcdb_type_get_id (const wchar_t *name, khm_int32 *id)
KHMEXP khm_int32 KHMAPI | kcdb_type_get_info (khm_int32 id, kcdb_type **info)
Return the type descriptor for a given type id.
KHMEXP khm_int32 KHMAPI | kcdb_type_release_info (kcdb_type *info)
Release a reference to a type info structure.
KHMEXP khm_int32 KHMAPI | kcdb_type_get_name (khm_int32 id, wchar_t *buffer, khm_size *cbbuf)
Get the name of a type.
KHMEXP khm_int32 KHMAPI | kcdb_type_register (const kcdb_type *type, khm_int32 *new_id)
Register a credentials attribute type.
KHMEXP khm_int32 KHMAPI | kcdb_type_unregister (khm_int32 id)
Unregister a credential attribute type.
KHMEXP khm_int32 KHMAPI | kcdb_type_get_next_free (khm_int32 *id)

Define Documentation

#define KCDB_TS_LONG 0

Specify that the long form of the string representation should be returned.

Flags for kcdb_type::toString. The flag specifies how long the string representation should be. The specific length of a short or long description is not restricted and it is up to the implementation to choose how to interpret the flags.

#define KCDB_TS_SHORT 1

Specify that the short form of the string representation should be returned.

Flags for kcdb_type::toString. The flag specifies how long the string representation should be. The specific length of a short or long description is not restricted and it is up to the implementation to choose how to interpret the flags.

Usually, KCDB_TS_SHORT is specified when the amount of space that is available to display the string is very restricted. It may be the case that the string is truncated to facilitate displaying in a constrainted space.

#define KCDB_TYPE_ALL KCDB_TYPE_INVALID

All types.

Used by filters to indicate that all types are allowed.

#define KCDB_TYPE_DATA 6

Raw data.

A raw data buffer.

#define KCDB_TYPE_DATE 2

Data.

A date/time represented in FILETIME format.

#define KCDB_TYPE_FLAG_CB_AUTO 16

The type supports KCDB_CBSIZE_AUTO.

Used for types where the size of the object can be determined through context or by the object content. Such as for objects that have a fixed size or unicode strings that have a terminator.

This implies that ALL the object manipulation callbacks that are defined in this type definition support the KCDB_CBSIZE_AUTO value.

#define KCDB_TYPE_FLAG_CB_FIXED (KCDB_TYPE_FLAG_CB_AUTO|KCDB_TYPE_FLAG_CB_MIN|KCDB_TYPE_FLAG_CB_MAX)

Denotes that objects of this type have a fixed size.

If this flags is specified, then the type definition must also specify cb_min and cb_max, which must both be the same value.

Note:
Implies KCDB_TYPE_FLAG_CB_AUTO, KCDB_TYPE_FLAG_CB_MIN and KCDB_TYPE_FLAG_CB_MAX. Pay special attention to the implication of KCDB_TYPE_FLAG_AUTO.

#define KCDB_TYPE_FLAG_CB_MAX 256

The cb_max member is valid.

The cb_max member defines the maximum number of bytes that an object of this type will consume.

Note:
If this flag is used in conjunction with KCDB_TYPE_FLAG_CB_MIN then, cb_min must be less than or equal to cb_max.

#define KCDB_TYPE_FLAG_CB_MIN 128

The cb_min member is valid.

The cb_min member defines the minimum number of bytes that an object of this type will consume.

Note:
If this flag is used in conjunction with KCDB_TYPE_FLAG_CB_MAX then, cb_min must be less than or equal to cb_max.

#define KCDB_TYPE_INT32 4

32-bit integer

A 32-bit signed integer.

#define KCDB_TYPE_INT64 5

64-bit integer

A 64-bit integer.

#define KCDB_TYPE_INTERVAL 3

Interval.

An interval of time represented as the difference between two FILETIME values.

#define KCDB_TYPE_INVALID (-1)

Invalid type.

Used by functions that return a type identifier to indicate that the returned type identifier is invalid. Also used to indicate that a type identifier is not available

#define KCDB_TYPE_MAX_ID 255

Maximum identifier number

#define KCDB_TYPE_STRING 1

String.

NULL terminated Unicode string. The byte count for a string attribute always includes the terminating NULL.

#define KCDB_TYPE_VOID 0

Void.

No data. This is not an actual data type.

Typedef Documentation

typedef khm_int32(KHMAPI * kcdb_dtf_comp)(const void *data_l, khm_size cb_data_l, const void *data_r, khm_size cb_data_r)

Compare two fields.

Compare the two data fields and return a value indicating their relative ordering. The return value follows the same specification as strcmp().

Both data buffers that are passed in can be assumed to be valid.

None of the data buffers should be modified in any way.

Parameters:
[in] | data_l | Valid pointer to first data buffer
[in] | cb_data_l | Number of bytes in data_l. If the data type flags has KCDB_TYPE_FLAG_CB_AUTO, then this parameter could be set to KCDB_CBSIZE_AUTO. In this case, the function should compute the size of the input buffer assuming that the input buffer is valid.
[in] | data_r | Valid pointer to second data buffer
[in] | cb_data_r | Number of bytes in data_r. If the data type flags has KCDB_TYPE_FLAG_CB_AUTO, then this parameter could be set to KCDB_CBSIZE_AUTO. In this case, the function should compute the size of the input buffer assuming that the input buffer is valid.
Returns:
The return value should be
  • Less than zero if data_l < data_r
  • Equal to zero if data_l == data_r or if this data type can not be compared
  • Greater than zero if data_l > data_r
Note:
This documents the expected behavior of this prototype function
See also:
kcdb_type

typedef khm_int32(KHMAPI * kcdb_dtf_dup)(const void *data_src, khm_size cb_data_src, void *data_dst, khm_size *pcb_data_dst)

Duplicate a data field.

Duplicates a data field. The buffer pointed to by data_src contains a valid field. The function should copy the field with appropriate adjustments to data_dst.

The data_dst parameter can be NULL if only the required size of the buffer is needed. In this case, teh function should set pcb_data_dst to the number of bytes required and then return KHM_ERROR_TOO_LONG.

Parameters:
[in] | data_src | Pointer to a valid data buffer
[in] | cb_data_src | Number of bytes in data_src. If the data type flags has KCDB_TYPE_FLAG_CB_AUTO, then this parameter could be set to KCDB_CBSIZE_AUTO. In this case, the function should compute the size of the input buffer assuming that the input buffer is valid.
[out] | data_dst | Poitner to destination buffer. Could be NULL if only the required size of the destination buffer is to be returned.
[in,out] | pcb_data_dst | On entry specifies the number of bytes in data_dst, and on exit should contain the number of bytes copied.
Return values:
KHM_ERROR_SUCCESS | The data was successfully copied. The number of bytes copied is in pcb_data_dst
KHM_ERROR_INVALID_PARAM | One or more parameters is incorrect.
KHM_ERROR_TOO_LONG | Either data_dst was NULL or the size of the buffer was insufficient. The required size is in pcb_data_dst
Note:
This documents the expected behavior of this prototype function
See also:
kcdb_type

typedef khm_boolean(KHMAPI * kcdb_dtf_isValid)(const void *data, khm_size cb_data)

Verifies whetehr the given buffer contains valid data.

The function should examine the buffer and the size of the buffer and determine whether or not the buffer contains valid data for this data type.

The data field pointed to by data should not be modified in any way.

Parameters:
[in] | data | A pointer to a data buffer
[in] | cb_data | The number of bytes in the data buffer. If the data type flags has KCDB_TYPE_FLAG_CB_AUTO, then this parameter could be set to KCDB_CBSIZE_AUTO. In this case, the function should compute the size of the input buffer assuming that the input buffer is valid.
Returns:
TRUE if the data is valid, FALSE otherwise.
Note:
This documents the expected behavior of this prototype function
See also:
kcdb_type

typedef khm_int32(KHMAPI * kcdb_dtf_toString)(const void *data, khm_size cb_data, wchar_t *s_buf, khm_size *pcb_s_buf, khm_int32 flags)

Convert a field to a string.

Provides a string representation of a field in a credential. The data buffer can be assumed to be valid.

On entry, s_buf can be NULL if only the required size of the buffer is to be returned. pcb_s_buf should be non-NULL and should point to a valid variable of type khm_size that will, on entry, contain the size of the buffer pointed to by s_buf if s_buf is not NULL, and on exit will contain the number of bytes consumed in s_buf, or the required size of the buffer if s_buf was NULL or the size of the buffer was insufficient.

The implementation should verify the parameters that are passed in to the function.

The data pointed to by data should not be modified in any way.

Parameters:
[in] | data | Valid pointer to a block of data
[in] | cb_data | Number of bytes in data block pointed to by data
[out] | s_buf | Buffer to receive the string representation of data. If the data type flags has KCDB_TYPE_FLAG_CB_AUTO, then this parameter could be set to KCDB_CBSIZE_AUTO. In this case, the function should compute the size of the input buffer assuming that the input buffer is valid.
[in,out] | pcb_s_buf | On entry, contains the size of the buffer pointed to by s_buf, and on exit, contains the number of bytes used by the string representation of the data including the NULL terminator
[in] | flags | Flags for formatting the string
Return values:
KHM_ERROR_SUCCESS | The string representation of the data field was successfully copied to s_buf and the size of the buffer used was copied to pcb_s_buf.
KHM_ERROR_INVALID_PARAM | One or more parameters were invalid
KHM_ERROR_TOO_LONG | Either s_buf was NULL or the size indicated by pcb_s_buf was too small to contain the string representation of the value. The required size of the buffer is in pcb_s_buf.
Note:
This documents the expected behavior of this prototype function
See also:
kcdb_type

Function Documentation

KHMEXP int KHMAPI AnsiStrToUnicode | ( | wchar_t * | wstr,
 |  | size_t | cbwstr,
 |  | const char * | astr
 | ) |  |

Convert a safe ANSI string to a Unicode string.

The resulting string is guaranteed to be NULL terminated and within the size limit set by cbwstr.

If the whole string cannot be converted, wstr is set to an empty string.

Returns:
the number of characters converted. This is always either the length of the string astr or 0.

KHMEXP FILETIME KHMAPI FtAdd | ( | LPFILETIME | ft1,
 |  | LPFILETIME | ft2
 | ) |  |

Calculate the sum of two FILETIMEs.

Return the value of ft1 + ft2

KHMEXP long KHMAPI FtCompare | ( | LPFILETIME | pft1,
 |  | LPFILETIME | pft2
 | ) |  |

Compare two FILETIME values.

The return value is similar to the return value of strcmp(), based on the comparison of the two FILETIME values.

KHMEXP long KHMAPI FtIntervalMsToRepChange ( LPFILETIME pft )

Return number of milliseconds till next representation change.

Returns the number of milliseconds that must elapse away from the interval specified in pft for the representation of pft to change from whatever it is right now.

Returns 0 if the representation is not expected to change.

KHMEXP FILETIME KHMAPI FtSub | ( | LPFILETIME | ft1,
 |  | LPFILETIME | ft2
 | ) |  |

Calculate the difference between two FILETIMEs.

Returns the value of ft1 - ft2

KHMEXP khm_int32 KHMAPI IntervalStringToFt | ( | FILETIME * | pft,
 |  | wchar_t * | str
 | ) |  |

Parse a string representing an interval into a FILETIME interval.

The string is a localized string which should look like the following:

    [number unit] [number unit]...

where number is an integer while unit is a localized (possibly abbreviated) unit specification. The value of the described interval is calculated as the sum of each number in units. For example :

    1 hour 36 minutes

would result in an interval specification that's equivalent to 1 hour and 36 minutes. Of course there is no restriction on the order in which the number unit specifications are given and the same unit may be repeated multiple times.

Return values:
KHM_ERROR_INVALID_PARAM | The given string was invalid or had a token that could not be parsed. It can also mean that pft was NULL or str was NULL.
KHM_ERROR_SUCCESS | The string was successfully parsed and the result was placed in pft.

KHMEXP khm_int32 KHMAPI kcdb_type_get_info | ( | khm_int32 | id,
 |  | kcdb_type ** | info
 | ) |  |

Return the type descriptor for a given type id.

Parameters:
[out] info Receives a held reference to a type descriptor. Use kcdb_type_release_info() to release the handle. If the info parameter is NULL, the function returns KHM_ERROR_SUCCESS if id is a valid type id, and returns KHM_ERROR_NOT_FOUND otherwise.
See also:
kcdb_type_release_info()

KHMEXP khm_int32 KHMAPI kcdb_type_get_name | ( | khm_int32 | id,
 |  | wchar_t * | buffer,
 |  | khm_size * | cbbuf
 | ) |  |

Get the name of a type.

Retrieves the non-localized name of the specified type.

KHMEXP khm_int32 KHMAPI kcdb_type_register | ( | const kcdb_type * | type,
 |  | khm_int32 * | new_id
 | ) |  |

Register a credentials attribute type.

The credentials type record pointed to by type defines a new credential attribute type. The id member of type may be set to KCDB_TYPE_INVALID to indicate that an attribute ID is to be generated automatically.

Parameters:
[in] | type | The type descriptor
[out] | new_id | Receives the identifier for the credential attribute type.

KHMEXP khm_int32 KHMAPI kcdb_type_release_info ( kcdb_type * info )

Release a reference to a type info structure.

Releases the reference to the type information obtained with a prior call to kcdb_type_get_info().

KHMEXP khm_int32 KHMAPI kcdb_type_unregister ( khm_int32 id )

Unregister a credential attribute type.

Removes the registration for the specified credentials attribute type.

KHMEXP int KHMAPI UnicodeStrToAnsi | ( | char * | dest,
 |  | size_t | cbdest,
 |  | const wchar_t * | src
 | ) |  |

Convert a Unicode string to ANSI.

The resulting string is guaranteed to be NULL terminated and within the size limit set by cbdest.

Returns:
the number of characters converted. This is always either the length of the string src or 0.

Generated on Mon Oct 22 22:56:45 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: kcdb_type Struct Reference

kcdb_type Struct Reference
[Credential attribute types]

#include <kcreddb.h>

Detailed Description

A data type descriptor.

Handles basic operation for a specific data type.

See also:
Data types in Network Identity Manager

Data Fields

wchar_t * | name
khm_int32 | id
khm_int32 | flags
khm_size | cb_min
khm_size | cb_max
kcdb_dtf_toString toString
kcdb_dtf_isValid isValid
kcdb_dtf_comp comp
kcdb_dtf_dup dup

Field Documentation

kcdb_dtf_toString kcdb_type::toString

Provides a string representation for a value.

kcdb_dtf_isValid kcdb_type::isValid

Returns true of the value is valid for this data type

kcdb_dtf_comp kcdb_type::comp

Compare two values and return strcmp style return value

kcdb_dtf_dup kcdb_type::dup

Duplicate a value into a secondary buffer

The documentation for this struct was generated from the following file:
  • kcreddb.h
Generated on Mon Oct 22 22:56:48 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Credential attributes

Credential attributes
[NetIDMgr Credentials Database]

Detailed Description

Modules

Attribute flags
Standard attribute IDs and names

Data Structures

struct | kcdb_attrib
Credential attribute descriptor. More...

Typedefs

typedef khm_int32(KHMAPI * | kcdb_attrib_compute_cb )(khm_handle cred, khm_int32 id, void *buffer, khm_size *cbsize)
Prototype callback function for computed data types.

Functions

KHMEXP khm_int32 KHMAPI | kcdb_attrib_get_id (const wchar_t *name, khm_int32 *id)
Retrieve the ID of a named attribute.
KHMEXP khm_int32 KHMAPI | kcdb_attrib_register (const kcdb_attrib *attrib, khm_int32 *new_id)
Register an attribute.
KHMEXP khm_int32 KHMAPI | kcdb_attrib_get_info (khm_int32 id, kcdb_attrib **attrib)
Retrieve the attribute descriptor for an attribute.
KHMEXP khm_int32 KHMAPI | kcdb_attrib_release_info (kcdb_attrib *attrib)
Release an attribute descriptor.
KHMEXP khm_int32 KHMAPI | kcdb_attrib_unregister (khm_int32 id)
Unregister an attribute.
KHMEXP khm_int32 KHMAPI | kcdb_attrib_describe (khm_int32 id, wchar_t *buffer, khm_size *cbsize, khm_int32 flags)
Retrieve the description of an attribute.
KHMEXP khm_int32 KHMAPI | kcdb_attrib_get_count (khm_int32 and_flags, khm_int32 eq_flags, khm_size *pcount)
Count attributes.
KHMEXP khm_int32 KHMAPI | kcdb_attrib_get_ids (khm_int32 and_flags, khm_int32 eq_flags, khm_int32 *plist, khm_size *pcsize)
List attribute identifiers.

Typedef Documentation

typedef khm_int32(KHMAPI * kcdb_attrib_compute_cb)(khm_handle cred, khm_int32 id, void *buffer, khm_size *cbsize)

Prototype callback function for computed data types.

If the flags for a particular attribute specifies that the value is computed, then a callback function should be specified. The callback function will be called with a handle to a credential along with the attribute ID for the requested attribute. The function should place the computed value in buffer. The size of the buffer in bytes is specifed in cbsize. However, if buffer is NULL, then the required buffer size should be placed in cbsize.

Function Documentation

KHMEXP khm_int32 KHMAPI kcdb_attrib_describe | ( | khm_int32 | id,
 |  | wchar_t * | buffer,
 |  | khm_size * | cbsize,
 |  | khm_int32 | flags
 | ) |  |

Retrieve the description of an attribute.

Parameters:
[in] flags Specify KCDB_TS_SHORT to retrieve the short description.

KHMEXP khm_int32 KHMAPI kcdb_attrib_get_count | ( | khm_int32 | and_flags,
 |  | khm_int32 | eq_flags,
 |  | khm_size * | pcount
 | ) |  |

Count attributes.

Counts the number of attributes that match the given criteria. The criteria is specified against the flags of the attribute. An attribute is a match if its flags satisfy the condition below:

    (attrib.flags & and_flags) == (eq_flags & and_flags)

The number of attributes that match are returned in pcount.

KHMEXP khm_int32 KHMAPI kcdb_attrib_get_ids | ( | khm_int32 | and_flags,
 |  | khm_int32 | eq_flags,
 |  | khm_int32 * | plist,
 |  | khm_size * | pcsize
 | ) |  |

List attribute identifiers.

Lists the identifiers of the attributes that match the given criteria. The criteria is specified against the flags of the attribute. An attribute is a match if the following condition is satisfied:

    (attrib.flags & and_flags) == (eq_flags & and_flags)

The list of attributes found are copied to the khm_int32 array specified in plist. The number of elements available in the buffer plist is specified in pcsize. On exit, pcsize will hold the actual number of attribute identifiers copied to the array.

Parameters:
[in] | and_flags | See above
[in] | eq_flags | See above
[in] | plist | A khm_int32 array
[in,out] | pcsize | On entry, holds the number of elements available in the array pointed to by plist. On exit, holds the number of elements copied to the array.
Return values:
KHM_ERROR_SUCCESS | The list of attribute identifiers have been copied.
KHM_ERROR_TOO_LONG | The list was too long to fit in the supplied buffer. As many elements as possible have been copied to the plist array and the required number of elements has been written to pcsize.
Note:
The pcsize parameter specifies the number of khm_int32 elements in the array and not the number of bytes in the array. This is different from the usual size parameters used in the NetIDMgr API.

KHMEXP khm_int32 KHMAPI kcdb_attrib_get_info | ( | khm_int32 | id,
 |  | kcdb_attrib ** | attrib
 | ) |  |

Retrieve the attribute descriptor for an attribute.

The descriptor that is returned must be released through a call to kcdb_attrib_release_info()

If only the validity of the attribute identifier needs to be checked, you can pass in NULL for attrib. In this case, if the identifier is valid, then the funciton will return KHM_ERROR_SUCCESS, otherwise it will return KHM_ERROR_NOT_FOUND.

See also:
kcdb_attrib_release_info()

KHMEXP khm_int32 KHMAPI kcdb_attrib_register | ( | const kcdb_attrib * | attrib,
 |  | khm_int32 * | new_id
 | ) |  |

Register an attribute.

Parameters:
[out] new_id Receives the ID of the newly registered attribute. If the id member of the kcdb_attrib object is set to KCDB_ATTR_INVALID, then a unique ID is generated.

KHMEXP khm_int32 KHMAPI kcdb_attrib_release_info ( kcdb_attrib * attrib )

Release an attribute descriptor.

See also:
kcdb_attrib_get_info()

KHMEXP khm_int32 KHMAPI kcdb_attrib_unregister ( khm_int32 id )

Unregister an attribute.

Once an attribute ID has been unregistered, it may be reclaimed by a subsequent call to kcdb_attrib_register().

Generated on Mon Oct 22 22:56:45 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Attribute flags

Attribute flags
[Credential attributes]

Detailed Description

Defines

#define | KCDB_ATTR_FLAG_REQUIRED 0x00000008
The attribute is required.
#define | KCDB_ATTR_FLAG_COMPUTED 0x00000010
The attribute is computed.
#define | KCDB_ATTR_FLAG_SYSTEM 0x00000020
System attribute.
#define | KCDB_ATTR_FLAG_HIDDEN 0x00000040
Hidden.
#define | KCDB_ATTR_FLAG_PROPERTY 0x00000080
Property.
#define | KCDB_ATTR_FLAG_VOLATILE 0x00000100
Volatile.
#define | KCDB_ATTR_FLAG_ALTVIEW 0x00000200
Alternate view.
#define | KCDB_ATTR_FLAG_TRANSIENT 0x00000400
Transient attribute.

Define Documentation

#define KCDB_ATTR_FLAG_ALTVIEW 0x00000200

Alternate view.

The attribute is actually an alternate representation of another attribute. The Canonical attribute name is specified in alt_id.

Sometimes a certain attribute may need to be represented in different ways. You can register multiple attributes for each view. However, you should also provide a canonical attribute for whenever the canonical set of attributes of the credential is required.

#define KCDB_ATTR_FLAG_COMPUTED 0x00000010

The attribute is computed.

If this flag is set, the compute_cb, compute_min_cbsize and compute_max_cbsize members of the kcdb_attrib attribute descriptor must be assigned valid values.

#define KCDB_ATTR_FLAG_HIDDEN 0x00000040

Hidden.

The attribute is not meant to be displayed to the user. Setting this flag prevents this attribute from being listed in the list of available data fields in the UI.

#define KCDB_ATTR_FLAG_PROPERTY 0x00000080

Property.

The attribute is a property. The main difference between regular attributes and properties are that properties are not allocated off the credentials record. Hence, a property can not be used as a credentials field. Other objects such as identities can hold property sets. A property set can hold both regular attributes as well as properties.

#define KCDB_ATTR_FLAG_SYSTEM 0x00000020

System attribute.

This cannot be specified for a custom attribute. Implies that the value of the attribute is given by the credentials database itself.

#define KCDB_ATTR_FLAG_TRANSIENT 0x00000400

Transient attribute.

A transient attribute is one whose absence is meaningful. When updating one record using another, if a transient attribute is absent in the source but present in the destination, then the attribute is removed from the destination.

#define KCDB_ATTR_FLAG_VOLATILE 0x00000100

Volatile.

A volatile property is one whose value changes often, such as KCDB_ATTR_TIMELEFT. Some controls will make use of additional logic to deal with such values, or not display them at all.

Generated on Mon Oct 22 22:56:45 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Standard attribute IDs and names

Standard attribute IDs and names
[Credential attributes]

Detailed Description

Attribute related constants

#define | KCDB_ATTR_MAX_ID 255
Maximum valid attribute ID.
#define | KCDB_ATTR_MIN_PROP_ID 4096
Minimum valid property ID.
#define | KCDB_ATTR_MAX_PROPS 128
Maximum number of properties.
#define | KCDB_ATTR_MAX_PROP_ID (KCDB_ATTR_MIN_PROP_ID + KCDB_ATTR_MAX_PROPS - 1)
Maximum valid property ID.
#define | KCDB_ATTR_INVALID (-1)
Invalid ID.
#define | KCDB_ATTRID_USER 20
First custom attribute ID.

Attribute identifiers

#define | KCDB_ATTR_NAME 0
Name of the credential.
#define | KCDB_ATTR_ID 1
The identity handle for the credential.
#define | KCDB_ATTR_ID_NAME 2
The name of the identity.
#define | KCDB_ATTR_TYPE 3
The type of the credential.
#define | KCDB_ATTR_TYPE_NAME 4
Type name for the credential.
#define | KCDB_ATTR_PARENT_NAME 5
Name of the parent credential.
#define | KCDB_ATTR_ISSUE 6
Issed on.
#define | KCDB_ATTR_EXPIRE 7
Expires on.
#define | KCDB_ATTR_RENEW_EXPIRE 8
Renewable period expires on.
#define | KCDB_ATTR_TIMELEFT 9
Time left till expiration.
#define | KCDB_ATTR_RENEW_TIMELEFT 10
#define | KCDB_ATTR_LOCATION 11
Location of the credential.
#define | KCDB_ATTR_LIFETIME 12
Lifetime of the credential.
#define | KCDB_ATTR_RENEW_LIFETIME 13
#define | KCDB_ATTR_FLAGS 14
Flags for the credential.

Attribute names

#define | KCDB_ATTRNAME_NAME L"Name"
#define | KCDB_ATTRNAME_ID L"Identity"
#define | KCDB_ATTRNAME_ID_NAME L"IdentityName"
#define | KCDB_ATTRNAME_TYPE L"TypeId"
#define | KCDB_ATTRNAME_TYPE_NAME L"TypeName"
#define | KCDB_ATTRNAME_FLAGS L"Flags"
#define | KCDB_ATTRNAME_PARENT_NAME L"Parent"
#define | KCDB_ATTRNAME_ISSUE L"Issued"
#define | KCDB_ATTRNAME_EXPIRE L"Expires"
#define | KCDB_ATTRNAME_RENEW_EXPIRE L"RenewExpires"
#define | KCDB_ATTRNAME_TIMELEFT L"TimeLeft"
#define | KCDB_ATTRNAME_RENEW_TIMELEFT L"RenewTimeLeft"
#define | KCDB_ATTRNAME_LOCATION L"Location"
#define | KCDB_ATTRNAME_LIFETIME L"Lifetime"
#define | KCDB_ATTRNAME_RENEW_LIFETIME L"RenewLifetime"

Define Documentation

#define KCDB_ATTR_EXPIRE 7

Expires on.

  • Type: DATE
  • Flags: SYSTEM

#define KCDB_ATTR_FLAGS 14

Flags for the credential.

  • Type: INT32
  • Flags: REQUIRED, COMPUTED, SYSTEM, HIDDEN

#define KCDB_ATTR_ID 1

The identity handle for the credential.

  • Type: INT64
  • Flags: REQUIRED, COMPUTED, SYSTEM, HIDDEN

Note:
The handle returned in by specifying this attribute to kcdb_cred_get_attr() or kcdb_cred_get_attrib() is not held. While the identity is implicitly held for the duration that the credential is held, it is not recommended to obtain a handle to the identity using this method. Use kcdb_cred_get_identity() instead.

#define KCDB_ATTR_ID_NAME 2

The name of the identity.

  • Type: STRING
  • Flags: REQUIRED, COMPUTED, SYSTEM

#define KCDB_ATTR_ISSUE 6

Issed on.

  • Type: DATE
  • Flags: SYSTEM

#define KCDB_ATTR_LIFETIME 12

Lifetime of the credential.

  • Type: INTERVAL
  • Flags: SYSTEM

#define KCDB_ATTR_LOCATION 11

Location of the credential.

  • Type: STRING
  • Flags: SYSTEM

#define KCDB_ATTR_NAME 0

Name of the credential.

  • Type: STRING
  • Flags: REQUIRED, COMPUTED, SYSTEM

#define KCDB_ATTR_PARENT_NAME 5

Name of the parent credential.

  • Type: STRING
  • Flags: SYSTEM

#define KCDB_ATTR_RENEW_EXPIRE 8

Renewable period expires on.

  • Type: DATE
  • Flags: SYSTEM

#define KCDB_ATTR_TIMELEFT 9

Time left till expiration.

  • Type: INTERVAL
  • Flags: SYSTEM, COMPUTED, VOLATILE

#define KCDB_ATTR_TYPE 3

The type of the credential.

  • Type: INT32
  • Flags: REQUIRED, COMPUTED, SYSTEM, HIDDEN

#define KCDB_ATTR_TYPE_NAME 4

Type name for the credential.

  • Type: STRING
  • Flags: REQUIRED, COMPUTED, SYSTEM

Generated on Mon Oct 22 22:56:45 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: kcdb_attrib Struct Reference

kcdb_attrib Struct Reference
[Credential attributes]

#include <kcreddb.h>

Detailed Description

Credential attribute descriptor.

See also:
kcdb_attrib_register()

Data Fields

wchar_t * | name
khm_int32 id
khm_int32 alt_id
khm_int32 flags
khm_int32 type
wchar_t * | short_desc
wchar_t * | long_desc
kcdb_attrib_compute_cb compute_cb
khm_size compute_min_cbsize
khm_size compute_max_cbsize

Field Documentation

wchar_t* kcdb_attrib::name

Name. (Not localized, required)

khm_int32 kcdb_attrib::id

Identifier. When registering, this can be set to KCDB_ATTR_INVALID if a unique identifier is to be generated.

khm_int32 kcdb_attrib::alt_id

Alternate identifier. If the flags specify KCDB_ATTR_FLAG_ALTVIEW, then this field should specify the identifier of the canonical attribute from which this attribute is derived.

khm_int32 kcdb_attrib::flags

Flags. Combination of attribute flags"

khm_int32 kcdb_attrib::type

Type of the attribute. Must be valid.

wchar_t* kcdb_attrib::short_desc

Short description. (Localized, optional)

wchar_t* kcdb_attrib::long_desc

Long description. (Localized, optional)

kcdb_attrib_compute_cb kcdb_attrib::compute_cb

Callback. Required if flags specify KCDB_ATTR_FLAG_COMPUTED.

khm_size kcdb_attrib::compute_min_cbsize

Minimum number of bytes required to store this attribute. Required if KCDB_ATTR_FLAG_COMPUTED is specified.

khm_size kcdb_attrib::compute_max_cbsize

Maximum number of bytes required to store this attribute. Required if KCDB_ATTR_FLAG_COMPUTED is specified.

The documentation for this struct was generated from the following file:
  • kcreddb.h
Generated on Mon Oct 22 22:56:48 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Credential types

Credential types
[NetIDMgr Credentials Database]

Detailed Description

Data Structures

struct | 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.

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 ) ((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 Mon Oct 22 22:56:46 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: kcdb_credtype Struct Reference

kcdb_credtype Struct Reference
[NetIDMgr Credentials Database, Credential types]

#include <kcreddb.h>

Detailed Description

Credential type descriptor.

Data Fields

wchar_t * | name
khm_int32 | id
wchar_t * | short_desc
wchar_t * | long_desc
khm_handle sub
kcdb_cred_comp_func is_equal
HICON | icon

Field Documentation

wchar_t* kcdb_credtype::name

name (less than KCDB_MAXCB_NAME bytes)

wchar_t* kcdb_credtype::short_desc

short localized description (less than KCDB_MAXCB_SHORT_DESC bytes)

wchar_t* kcdb_credtype::long_desc

long localized descriptionn (less than KCDB_MAXCB_LONG_DESC bytes)

khm_handle kcdb_credtype::sub

Subscription for credentials type hander. This should be a valid subscription constructed through a call to kmq_create_subscription() and must handle KMSG_CRED messages that are marked as being sent to type specific subscriptions.

The subscription will be automatically deleted with a call to kmq_delete_subscription() when the credentials type is unregistered.

kcdb_cred_comp_func kcdb_credtype::is_equal

Used as an additional clause when comparing two credentials for equality. The function this is actually a comparison function, it should return zero if the two credentials are equal and non-zero if they are not. The addtional rock parameter is always zero.

It can be assumed that the identity, name and credentials type have already been found to be equal among the credentials and the credential type is the type that is being registered.

The documentation for this struct was generated from the following file:
  • kcreddb.h
Generated on Mon Oct 22 22:56:48 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Generic access to buffer

Generic access to buffer
[NetIDMgr Credentials Database]

Detailed Description

Currently, credentials and identities both hold record data types. This set of API's allow an application to access fields in the records using a single interface. Note that credentials only accept regular attributes while identities can hold both attributes and properties.

Handles to credentials and identities are implicitly also handles to records. Thus they can be directly used as such.

Functions

KHMEXP khm_int32 KHMAPI | kcdb_buf_get_attr (khm_handle record, khm_int32 attr_id, khm_int32 *attr_type, void *buffer, khm_size *pcb_buf)
Get an attribute from a record by attribute id.
KHMEXP khm_int32 KHMAPI | kcdb_buf_get_attrib (khm_handle record, const wchar_t *attr_name, khm_int32 *attr_type, void *buffer, khm_size *pcb_buf)
Get an attribute from a record by name.
KHMEXP khm_int32 KHMAPI | kcdb_buf_get_attr_string (khm_handle record, khm_int32 attr_id, wchar_t *buffer, khm_size *pcbbuf, khm_int32 flags)
Get the string representation of a record attribute.
KHMEXP khm_int32 KHMAPI | kcdb_buf_get_attrib_string (khm_handle record, const wchar_t *attr_name, wchar_t *buffer, khm_size *pcbbuf, khm_int32 flags)
Get the string representation of a record attribute by name.
KHMEXP khm_int32 KHMAPI | kcdb_buf_set_attr (khm_handle record, khm_int32 attr_id, void *buffer, khm_size cbbuf)
Set an attribute in a record by attribute id.
KHMEXP khm_int32 KHMAPI | kcdb_buf_set_attrib (khm_handle record, const wchar_t *attr_name, void *buffer, khm_size cbbuf)
Set an attribute in a record by name.
KHMEXP khm_int32 KHMAPI | kcdb_buf_hold (khm_handle record)
KHMEXP khm_int32 KHMAPI | kcdb_buf_release (khm_handle record)

Function Documentation

KHMEXP khm_int32 KHMAPI kcdb_buf_get_attr | ( | khm_handle | record,
 |  | khm_int32 | attr_id,
 |  | khm_int32 * | attr_type,
 |  | void * | buffer,
 |  | khm_size * | pcb_buf
 | ) |  |

Get an attribute from a record by attribute id.

Parameters:
[in] | buffer | The buffer that is to receive the attribute value. Set this to NULL if only the required buffer size is to be returned.
[in,out] | cbbuf | The number of bytes available in buffer. If buffer is not sufficient, returns KHM_ERROR_TOO_LONG and sets this to the required buffer size.
[out] | attr_type | Receives the data type of the attribute. Set this to NULL if the type is not required.
Note:
Set both buffer and cbbuf to NULL if only the existence of the attribute is to be checked. If the attribute exists in this record then the function will return KHM_ERROR_SUCCESS, otherwise it returns KHM_ERROR_NOT_FOUND.

KHMEXP khm_int32 KHMAPI kcdb_buf_get_attr_string | ( | khm_handle | record,
 |  | khm_int32 | attr_id,
 |  | wchar_t * | buffer,
 |  | khm_size * | pcbbuf,
 |  | khm_int32 | flags
 | ) |  |

Get the string representation of a record attribute.

A shortcut function which generates the string representation of a record attribute directly.

Parameters:
[in] | record | A handle to a record
[in] | attr_id | The attribute to retrieve
[out] | buffer | A pointer to a string buffer which receives the string form of the attribute. Set this to NULL if you only want to determine the size of the required buffer.
[in,out] | pcbbuf | A pointer to a khm_int32 that, on entry, holds the size of the buffer pointed to by buffer, and on exit, receives the actual number of bytes that were copied.
[in] | flags | Flags for the string conversion. Can be set to one of KCDB_TS_LONG or KCDB_TS_SHORT. The default is KCDB_TS_LONG.
Return values:
KHM_ERROR_SUCCESS | Success
KHM_ERROR_NOT_FOUND | The given attribute was either invalid or was not defined for this record
KHM_ERROR_INVALID_PARAM | One or more parameters were invalid
KHM_ERROR_TOO_LONG | Either buffer was NULL or the supplied buffer was insufficient

KHMEXP khm_int32 KHMAPI kcdb_buf_get_attrib | ( | khm_handle | record,
 |  | const wchar_t * | attr_name,
 |  | khm_int32 * | attr_type,
 |  | void * | buffer,
 |  | khm_size * | pcb_buf
 | ) |  |

Get an attribute from a record by name.

Parameters:
[in] | buffer | The buffer that is to receive the attribute value. Set this to NULL if only the required buffer size is to be returned.
[in,out] | cbbuf | The number of bytes available in buffer. If buffer is not sufficient, returns KHM_ERROR_TOO_LONG and sets this to the required buffer size.
Note:
Set both buffer and cbbuf to NULL if only the existence of the attribute is to be checked. If the attribute exists in this record then the function will return KHM_ERROR_SUCCESS, otherwise it returns KHM_ERROR_NOT_FOUND.

KHMEXP khm_int32 KHMAPI kcdb_buf_get_attrib_string | ( | khm_handle | record,
 |  | const wchar_t * | attr_name,
 |  | wchar_t * | buffer,
 |  | khm_size * | pcbbuf,
 |  | khm_int32 | flags
 | ) |  |

Get the string representation of a record attribute by name.

A shortcut function which generates the string representation of a record attribute directly.

Parameters:
[in] | record | A handle to a record
[in] | attrib | The name of the attribute to retrieve
[out] | buffer | A pointer to a string buffer which receives the string form of the attribute. Set this to NULL if you only want to determine the size of the required buffer.
[in,out] | pcbbuf | A pointer to a khm_int32 that, on entry, holds the size of the buffer pointed to by buffer, and on exit, receives the actual number of bytes that were copied.
[in] | flags | Flags for the string conversion. Can be set to one of KCDB_TS_LONG or KCDB_TS_SHORT. The default is KCDB_TS_LONG.
See also:
kcdb_cred_get_attr_string()

KHMEXP khm_int32 KHMAPI kcdb_buf_set_attr | ( | khm_handle | record,
 |  | khm_int32 | attr_id,
 |  | void * | buffer,
 |  | khm_size | cbbuf
 | ) |  |

Set an attribute in a record by attribute id.

Parameters:
[in] cbbuf Number of bytes of data in buffer. The individual data type handlers may copy in less than this many bytes in to the record.

KHMEXP khm_int32 KHMAPI kcdb_buf_set_attrib | ( | khm_handle | record,
 |  | const wchar_t * | attr_name,
 |  | void * | buffer,
 |  | khm_size | cbbuf
 | ) |  |

Set an attribute in a record by name.

Parameters:
[in] cbbuf Number of bytes of data in buffer. The individual data type handlers may copy in less than this many bytes in to the record.

Generated on Mon Oct 22 22:56:46 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: NetIDMgr Message Queue

NetIDMgr Message Queue

Detailed Description

The Network Identity Manager Message Queue handles all the messaging within the application and all loaded plug-ins.

For information about the messaging system and how it is used, please see Messages and Message Queues .

Modules

Message Types

Data Structures

struct | kmq_response
A single response. More...
struct | kmq_message
A single message. More...

Defines

#define | KMQ_WM_DISPATCH (WM_APP+0x100)
Window message for kmq.

Typedefs

typedef DWORD | kmq_thread_id
typedef DWORD | kmq_timer
typedef khm_int32(KHMAPI * | kmq_callback_t )(khm_int32 msg_type, khm_int32 msg_sub_type, khm_ui_4 uparam, void *vparam)
A message callback.
typedef kmq_message * | kmq_call
A handle to a call.
typedef void(KHMAPI * | kmq_msg_completion_handler )(kmq_message *)
A completion handler for a message.

Functions

KHMEXP khm_int32 KHMAPI | kmq_register_type (wchar_t *name, khm_int32 *new_id)
Register a message type.
KHMEXP khm_int32 KHMAPI | kmq_find_type (wchar_t *name, khm_int32 *id)
Find a message type.
KHMEXP khm_int32 KHMAPI | kmq_unregister_type (khm_int32 id)
Unregister a message type.
KHMEXP khm_int32 KHMAPI | kmq_subscribe (khm_int32 type, kmq_callback_t cb)
Subscribte to a message type.
KHMEXP khm_int32 KHMAPI | kmq_subscribe_hwnd (khm_int32 type, HWND hwnd)
Subscribe a window to a message type.
KHMEXP LRESULT KHMAPI | kmq_wm_begin (LPARAM lparm, kmq_message **m)
Begins handling a KMQ_WM_DISPATCH message.
KHMEXP LRESULT KHMAPI | kmq_wm_end (kmq_message *m, khm_int32 rv)
Ends handling a KMQ_WM_DISPATCH message.
KHMEXP LRESULT KHMAPI | kmq_wm_dispatch (LPARAM lparm, kmq_callback_t cb)
Dispatches a KMQ_WM_DISPATCH message to a callback.
KHMEXP khm_int32 KHMAPI | kmq_unsubscribe (khm_int32 type, kmq_callback_t cb)
Unsubscribe a callback from a message type.
KHMEXP khm_int32 KHMAPI | kmq_unsubscribe_hwnd (khm_int32 type, HWND hwnd)
Unsubscribe a window from a message type.
KHMEXP khm_int32 KHMAPI | kmq_create_subscription (kmq_callback_t cb, khm_handle *result)
Create an ad-hoc subscription.
KHMEXP khm_int32 KHMAPI | kmq_create_hwnd_subscription (HWND hw, khm_handle *result)
Create an ad-hoc subscription for a window.
KHMEXP khm_int32 KHMAPI | kmq_delete_subscription (khm_handle sub)
Delete an ad-hoc subscription.
KHMEXP khm_int32 KHMAPI | kmq_post_sub_msg (khm_handle sub, khm_int32 type, khm_int32 subtype, khm_ui_4 uparam, void *vparam)
Post a message to a subscription.
KHMEXP khm_int32 KHMAPI | kmq_post_sub_msg_ex (khm_handle sub, khm_int32 type, khm_int32 subtype, khm_ui_4 uparam, void *vparam, kmq_call *call)
Post a message to a subscription and acquire a handle to the call.
KHMEXP khm_int32 KHMAPI | kmq_send_sub_msg (khm_handle sub, khm_int32 type, khm_int32 subtype, khm_ui_4 uparam, void *vparam)
Send a synchronous message to a subscription.
KHMEXP khm_int32 KHMAPI | kmq_post_subs_msg (khm_handle *subs, khm_size n_subs, khm_int32 type, khm_int32 subtype, khm_ui_4 uparam, void *vparam)
Post a message to a group of subscriptions.
KHMEXP khm_int32 KHMAPI | kmq_post_subs_msg_ex (khm_handle *subs, khm_int32 n_subs, khm_int32 type, khm_int32 subtype, khm_ui_4 uparam, void *vparam, kmq_call *call)
Post a message to a group of subscriptions and acquire a handle to the call.
KHMEXP khm_int32 KHMAPI | kmq_send_subs_msg (khm_handle *subs, khm_int32 n_subs, khm_int32 type, khm_int32 subtype, khm_ui_4 uparam, void *vparam)
Send a synchronous message to a group of subscriptions.
KHMEXP khm_int32 KHMAPI | kmq_dispatch (kmq_timer timeout)
Dispatch a message for the current thread.
KHMEXP khm_int32 KHMAPI | kmq_send_message (khm_int32 type, khm_int32 subtype, khm_ui_4 uparam, void *blob)
Send a message.
KHMEXP khm_int32 KHMAPI | kmq_post_message (khm_int32 type, khm_int32 subtype, khm_ui_4 uparam, void *blob)
Post a message.
KHMEXP khm_int32 KHMAPI | kmq_post_message_ex (khm_int32 type, khm_int32 subtype, khm_ui_4 uparam, void *blob, kmq_call *call)
Post a message and acquire a handle to the call.
KHMEXP khm_int32 KHMAPI | kmq_free_call (kmq_call call)
Free a handle to a call obtained through kmq_post_message_ex().
KHMEXP khm_int32 KHMAPI | kmq_send_thread_quit_message (kmq_thread_id thread, khm_ui_4 uparam)
Sends a <KMSG_SYSTEM,KMSG_SYSTEM_EXIT> message to the specified thread.
KHMEXP khm_int32 KHMAPI | kmq_post_thread_quit_message (kmq_thread_id thread, khm_ui_4 uparam, kmq_call *call)
Post a <KMSG_SYSTEM,KMSG_SYSTEM_EXIT> message to the specified thread.
KHMEXP khm_int32 KHMAPI | kmq_get_next_response (kmq_call call, void **resp)
KHMEXP khm_boolean KHMAPI | kmq_has_completed (kmq_call call)
Check if a specific call has completed.
KHMEXP khm_int32 KHMAPI | kmq_wait (kmq_call call, kmq_timer timeout)
Wait for a call to complete.
KHMEXP khm_int32 KHMAPI | kmq_abort_call (kmq_call call)
Abort a call.
KHMEXP khm_boolean KHMAPI | kmq_is_call_aborted (void)
Check if the last dispatched message was aborted.
KHMEXP khm_int32 KHMAPI | kmq_set_completion_handler (khm_int32 type, kmq_msg_completion_handler hander)
Sets the completion handler for a specified message type.

Define Documentation

#define KMQ_WM_DISPATCH (WM_APP+0x100)

Window message for kmq.

This message is sent to the window procedure of a window if that window is a subscriber to KMQ messages.

See also:
kmq_subscribe_hwnd() for more information about handling this window message

Typedef Documentation

typedef khm_int32(KHMAPI * kmq_callback_t)(khm_int32 msg_type, khm_int32 msg_sub_type, khm_ui_4 uparam, void *vparam)

A message callback.

Should return TRUE if the message is properly handled. Otherwise return FALSE

typedef void(KHMAPI * kmq_msg_completion_handler)(kmq_message *)

A completion handler for a message.

Each message type can have a completion handler. Once a message of this a specific type has been broadcast and handled by all the subscripbers, the message will be passed down to the completion handler before the associated data structures are freed. This allows applications that define message type to also define clean up for each message. For example, the completion handler can initiate another message if the messages form a sequence or free up blocks of memory that was passed as the parameter to the message.

Function Documentation

KHMEXP khm_int32 KHMAPI kmq_abort_call ( kmq_call call )

Abort a call.

Abort a pending call. The call handle should have been obtained using a prior call to kmq_post_message_ex().

Note that this function may not abort the call immediately. It merely marks the message as being in an aborted state. It is upto the individual handlers of the message to check if the message has been aborted and act accordingly.

The handlers are expected to call kmq_is_call_aborted() periodicially during the processing of specially lengthy operations during the course of handling a message. That function will return TRUE if the last dispatched message is now in an aborted state. In which case, the handler is expected to abort handling the message and return control to the dispatcher.

KHMEXP khm_int32 KHMAPI kmq_create_hwnd_subscription | ( | HWND | hw,
 |  | khm_handle * | result
 | ) |  |

Create an ad-hoc subscription for a window.

An ad-hoc subscription describes a window that will be dispatched messages individually without broadcasting.

See also:
kmq_post_sub_msg(), kmq_post_sub_msg_ex(), kmq_send_sub_msg(), kmq_post_subs_msg(), kmq_post_subs_msg_ex(), kmq_send_subs_msg(), kmq_delete_subscription()

KHMEXP khm_int32 KHMAPI kmq_create_subscription | ( | kmq_callback_t | cb,
 |  | khm_handle * | result
 | ) |  |

Create an ad-hoc subscription.

An ad-hoc subscription describes a callback point in a thread that can be dispatched messages to individually without broadcasting.

See also:
kmq_post_sub_msg(), kmq_post_sub_msg_ex(), kmq_send_sub_msg(), kmq_post_subs_msg(), kmq_post_subs_msg_ex(), kmq_send_subs_msg(), kmq_delete_subscription()

KHMEXP khm_int32 KHMAPI kmq_delete_subscription ( khm_handle sub )

Delete an ad-hoc subscription.

Deletes a subscriptoin that was created using kmq_create_subscription()

KHMEXP khm_int32 KHMAPI kmq_dispatch ( kmq_timer timeout )

Dispatch a message for the current thread.

This function opens the message list for the current thread and dispatches the first message instance that is found. Note that if multiple callbacks subscribe to the same message type in the same thread, then when a message of that type is received, multiple message instances are added to the message queue corresponding to each subscription.

If no message instances are waiting in the queue, kmq_dispatch() waits for the timeout period for a message.

Parameters:
[in] timeout The timeout period in milliseconds. Specify INFINITE for kmq_dispatch() to wait indefinitely.
Return values:
KHM_ERROR_SUCCESS | A message instance was dispatched
KHM_ERROR_TIMEOUT | The timeout period elapsed
KHM_ERROR_EXIT | The message found on the queue was <KMSG_SYSTEM,KMSG_SYSTEM_EXIT>

KHMEXP khm_int32 KHMAPI kmq_find_type | ( | wchar_t * | name,
 |  | khm_int32 * | id
 | ) |  |

Find a message type.

Find the message type with the given name. If found, the type ID is returned in id.

Return values:
KHM_ERROR_SUCCESS | A message type with the given name was found.
KHM_ERROR_NOT_FOUND | A message type with the given name was not found.

KHMEXP khm_int32 KHMAPI kmq_free_call ( kmq_call call )

Free a handle to a call obtained through kmq_post_message_ex().

All call handles obtained through kmq_post_message_ex() must be freed via a call to kmq_free_call().

KHMEXP khm_boolean KHMAPI kmq_has_completed ( kmq_call call )

Check if a specific call has completed.

Returns:
TRUE if the call has completed. FALSE otherwise.

KHMEXP khm_boolean KHMAPI kmq_is_call_aborted ( void )

Check if the last dispatched message was aborted.

The sender of a message may abort it using a call to kmq_abort_call(). This function checks if the last dispatched message was aborted.

A handler of a message is expected to call this function periodically if handling the message is going to take a specially long time (e.g. more than 5 or 10 seconds). If the message is found to be aborted, the handler is expected to abort handling the message, perform any necessary cleanup and return control to the dispatcher.

Doing this allows operations like new credentials acquisition to be cleanly aborted by the user if she so wishes. Otherwise, Network Identity Manager has to wait for the message to complete processing since it has no means of cleanly terminating an executing plug-in thread.

KHMEXP khm_int32 KHMAPI kmq_post_message | ( | khm_int32 | type,
 |  | khm_int32 | subtype,
 |  | khm_ui_4 | uparam,
 |  | void * | blob
 | ) |  |

Post a message.

The specified message will be posted to all the subscribers of the message type. The function returns immediately.

If you want to be able to wait for all the subscribers to finish processing the message, you should use kmq_post_message_ex() instead.

Parameters:
[in] | type | The type of the message
[in] | subtype | The subtype
[in] | uparam | The khm_ui_4 parameter for the message
[in] | blob | The parameter blob for the message

KHMEXP khm_int32 KHMAPI kmq_post_message_ex | ( | khm_int32 | type,
 |  | khm_int32 | subtype,
 |  | khm_ui_4 | uparam,
 |  | void * | blob,
 |  | kmq_call * | call
 | ) |  |

Post a message and acquire a handle to the call.

The specified message is posted to all the subscribers. In addition, a handle is obtained for the call which can be used in subsequent call to kmq_free_call() or kmq_wait().

Call kmq_free_call() to free the handle.

Parameters:
[in] | type | The type of the message
[in] | subtype | The subtype
[in] | uparam | The khm_ui_4 parameter for the message
[in] | blob | The parameter blob for the message
[out] | call | Receives the call handle. Set to NULL if the call handle is not required.
See also:
kmq_free_call()

KHMEXP khm_int32 KHMAPI kmq_post_sub_msg | ( | khm_handle | sub,
 |  | khm_int32 | type,
 |  | khm_int32 | subtype,
 |  | khm_ui_4 | uparam,
 |  | void * | vparam
 | ) |  |

Post a message to a subscription.

Equivalent of kmq_post_msg() but only posts the message to the specified subscription.

KHMEXP khm_int32 KHMAPI kmq_post_subs_msg | ( | khm_handle * | subs,
 |  | khm_size | n_subs,
 |  | khm_int32 | type,
 |  | khm_int32 | subtype,
 |  | khm_ui_4 | uparam,
 |  | void * | vparam
 | ) |  |

Post a message to a group of subscriptions.

The block of memory pointed to by subs should be an array of subscriptions. The number of elements in that array should be n_subs. A message as specified by the remaining parameters will be dispatched to all of the subscription points in the array.

KHMEXP khm_int32 KHMAPI kmq_post_subs_msg_ex | ( | khm_handle * | subs,
 |  | khm_int32 | n_subs,
 |  | khm_int32 | type,
 |  | khm_int32 | subtype,
 |  | khm_ui_4 | uparam,
 |  | void * | vparam,
 |  | kmq_call * | call
 | ) |  |

Post a message to a group of subscriptions and acquire a handle to the call.

The block of memory pointed to by subs should be an array of subscriptions. The number of elements in that array should be n_subs. A message as specified by the remaining parameters will be dispatched to all of the subscription points in the array, and a handle to the call will be returned in call.

The returned call will reference all of the dispatches that were made.

KHMEXP khm_int32 KHMAPI kmq_post_thread_quit_message | ( | kmq_thread_id | thread,
 |  | khm_ui_4 | uparam,
 |  | kmq_call * | call
 | ) |  |

Post a <KMSG_SYSTEM,KMSG_SYSTEM_EXIT> message to the specified thread.

The message itself will not be received by any callback function, however, any kmq_dispatch() function that is currently active of becomes active will exit with a KHM_ERROR_EXIT code. kmq_post_thread_quit_message() will return immediately.

KHMEXP khm_int32 KHMAPI kmq_register_type | ( | wchar_t * | name,
 |  | khm_int32 * | new_id
 | ) |  |

Register a message type.

Registers a custom message type. The name parameter specifies a language independent name for the message type and must be unique and must be less than KMQ_MAXCCH_TYPE_NAME characters.

Parameters:
[in] | name | Name of the message type. Upto KMQ_MAXCCH_TYPE_NAME characters including terminating NULL. The name cannot be a zero length string.
[out] | new_id | Receives the new message type ID. Specify NULL if the new message type is not required.
See also:
kmq_find_type() and kmq_unregister_type()
Return values:
KHM_ERROR_INVALID_PARAM | The name parameter was invalid.
KHM_ERROR_EXISTS | A message type with that name already exists.
KHM_ERROR_NO_RESOURCES | Can't register any more message types.
KHM_ERROR_SUCCESS | The operation succeeded.

KHMEXP khm_int32 KHMAPI kmq_send_message | ( | khm_int32 | type,
 |  | khm_int32 | subtype,
 |  | khm_ui_4 | uparam,
 |  | void * | blob
 | ) |  |

Send a message.

The specified message will be posted to all the subscribers of the message type. Then the function will wait for all the subscribers to finish processing the message before returning.

Parameters:
[in] | type | The type of the message
[in] | subtype | The subtype
[in] | uparam | The khm_ui_4 parameter for the message
[in] | blob | The parameter blob for the message
Note:
The internal timeout for this function is INFINITE. If you it is desirable to use a different timeout, use kmq_post_message_ex() and kmq_wait() functions.
Return values:
KHM_ERROR_SUCCESS | The call succeeded and no subscribers returned errors
KHM_ERROR_PARTIAL | The call succeeded but at least one subscriber returned an error

KHMEXP khm_int32 KHMAPI kmq_send_sub_msg | ( | khm_handle | sub,
 |  | khm_int32 | type,
 |  | khm_int32 | subtype,
 |  | khm_ui_4 | uparam,
 |  | void * | vparam
 | ) |  |

Send a synchronous message to a subscription.

Return values:
KHM_ERROR_SUCCESS | The call succeeded, and no subscribers reported errors
KHM_ERROR_PARTIAL | The call succeeded, but at least one subscriber reported errors

KHMEXP khm_int32 KHMAPI kmq_send_subs_msg | ( | khm_handle * | subs,
 |  | khm_int32 | n_subs,
 |  | khm_int32 | type,
 |  | khm_int32 | subtype,
 |  | khm_ui_4 | uparam,
 |  | void * | vparam
 | ) |  |

Send a synchronous message to a group of subscriptions.

The block of memory pointed to by subs should be an array of subscriptions. The number of elements in that array should be n_subs. A message as specified by the remaining parameters will be dispatched to all of the subscription points in the array. The function will not return until all of the calls have succeeded.

Return values:
KHM_ERROR_SUCCESS | The call succeeded, and no subscribers reported errors
KHM_ERROR_PARTIAL | The call succeeded, but at least one subscriber reported errors

KHMEXP khm_int32 KHMAPI kmq_send_thread_quit_message | ( | kmq_thread_id | thread,
 |  | khm_ui_4 | uparam
 | ) |  |

Sends a <KMSG_SYSTEM,KMSG_SYSTEM_EXIT> message to the specified thread.

The message itself will not be received by any callback function, however, any kmq_dispatch() function that is currently active of becomes active will exit with a KHM_ERROR_EXIT code. kmq_send_thread_quit_message() will wait for this to happen before returning.

This function should not be called by the thread identified by the thread parameter.

KHMEXP khm_int32 KHMAPI kmq_set_completion_handler | ( | khm_int32 | type,
 |  | kmq_msg_completion_handler | hander
 | ) |  |

Sets the completion handler for a specified message type.

Note:
Only one completion handler can exist for one message type. Calling this function overwrites the previous completion handler.

KHMEXP khm_int32 KHMAPI kmq_subscribe | ( | khm_int32 | type,
 |  | kmq_callback_t | cb
 | ) |  |

Subscribte to a message type.

Adds a subscription to messages of type type. Subscriptions are managed per thread. Therefore the subscription is actually added to the subscription list for the current thread (the thread which calls kmq_subscribe()).

When a message of type type is received by the thread, it is dispatched to the callback function identified by cb within the context of this thread.

Note:
Calling kmq_subscribe() from within multiple threads with the same type and cb will result in multiple subscriptions.
See also:
kmq_unsubscribe()

kmq_dispatch()

KHMEXP khm_int32 KHMAPI kmq_subscribe_hwnd | ( | khm_int32 | type,
 |  | HWND | hwnd
 | ) |  |

Subscribe a window to a message type.

Adds the window specified by hwnd to the subscription list for the message type type. When a message of this type is posted, then the window procedure of the window hwnd receives a message KMQ_WM_DISPATCH.

When a window receives a KMQ_WM_DISPATCH message, it means that a message has been posted which is of a type that the window has subscribed for. Because of the way Windows handles window messages and the way NetIDMgr message queues work, a thread which has a window (or thread) procedure can not call kmq_dispatch() to handle these messages. For threads that have window or thread message loops, they must call kmq_subscribe_hwnd() to subscribe a particular window (for thread message loops, this would be the HWND of the message window for the thread) to NetIDMgr messages.

There are two supported ways of handling the KMQ_WM_DISPATCH message. Examples of both are provided below.

Handling the message inline:

    LRESULT CALLBACK WindowProc(HWND hwnd, UINT uMsg, WPARAM wParam, LPARAM lParam) {
    kmq_message * m;
    khm_int32 rv;
    ...
    switch(uMsg) {
    case WM_CREATE:
       ...
       kmq_subscribe_hwnd(KMSG_CRED, hwnd);
       ...
       break;

    case WM_DESTROY:
       ...
       kmq_unsubscribe_hwnd(KMSG_CRED, hwnd);
       ...
       break;

    ...
    case KMQ_WM_DISPATCH:
        kmq_wm_begin(lParam,&m);

    if(m->type == KMSG_CRED && m->subtype == KMSG_CRED_ROOTDELTA) {
    // do something
        rv = KHM_ERROR_SUCCESS;
    }

    return kmq_wm_end(m, rv);
    ...
    };
    ...
    }

The other method is to dispatch the KMQ_WM_DISPATCH message to a secondary callback function:

    khm_int32 msg_handler(khm_int32 t, khm_int32 st, khm_ui_4 up, void * pb) {
        khm_int32 rv = KHM_ERROR_SUCCESS;

        //handle message

    return rv;
    }

    LRESULT CALLBACK WindowProc(HWND hwnd, UINT uMsg, WPARAM wParam, LPARAM lParam) {
    kmq_message * m;
    khm_int32 rv;
    ...
    switch(uMsg) {
    ...

    case WM_CREATE:
       ...
       kmq_subscribe_hwnd(KMSG_CRED, hwnd);
       ...
       break;

    case WM_DESTROY:
       ...
       kmq_unsubscribe_hwnd(KMSG_CRED, hwnd);
       ...
       break;

    ...
    case KMQ_WM_DISPATCH:
        return kmq_wm_dispatch(lParam, msg_handler);
    ...
    };
    ...
    }

Note:
Make sure you unsubscribe from the message type when the window is destroyed.
See also:
kmq_unsubscribe_hwnd()

kmq_wm_begin()

kmq_wm_end()

kmq_wm_dispatch()

KHMEXP khm_int32 KHMAPI kmq_unregister_type ( khm_int32 id )

Unregister a message type.

Unregisters a message type that was registered using kmq_register_type().

Return values:
KHM_ERROR_SUCCESS | The specified message type was successfully unregistered.
KHM_ERROR_NOT_FOUND | The message type was not found.

KHMEXP khm_int32 KHMAPI kmq_unsubscribe | ( | khm_int32 | type,
 |  | kmq_callback_t | cb
 | ) |  |

Unsubscribe a callback from a message type.

Removes the subscription for message type type for callback function cb from the subscription list for the current thread (the thread that calls kmq_unsubscribe()).

Note:
kmq_unsubscribe() can only remove subscriptions for the subscription list for the current thread.
See also:
kmq_subscribe()

kmq_dispatch()

KHMEXP khm_int32 KHMAPI kmq_unsubscribe_hwnd | ( | khm_int32 | type,
 |  | HWND | hwnd
 | ) |  |

Unsubscribe a window from a message type.

Removes the specific window from the subsription list for message type type.

See also:
kmq_subscribe_hwnd()

KHMEXP khm_int32 KHMAPI kmq_wait | ( | kmq_call | call,
 |  | kmq_timer | timeout
 | ) |  |

Wait for a call to complete.

Waits for the specified call to complete. If the call dispatched to multiple recipients, the function waits for all dispatches to complete.

If the call has already completed, then the function returns immediately.

If more than one thread is waiting for a single message to complete, then only one of them will be released when the message compeltes. Each subsequent thread will be released as each released thread calls kmq_free_call().

Parameters:
[in] | call | A handle to a call.
[in] | timeout | Specifies, in milliseconds, the amount of time to wait for the call to complete. Specify INFINITE to wait indefinitely.
Return values:
KHM_ERROR_SUCCESS | The call completed
KHM_ERROR_TIMEOUT | The timeout period expired
KHM_ERROR_INVALID_PARAM | One of the parameters were invalid.

KHMEXP LRESULT KHMAPI kmq_wm_begin | ( | LPARAM | lparm,
 |  | kmq_message ** | m
 | ) |  |

Begins handling a KMQ_WM_DISPATCH message.

Returns:
The return value of this function should be ignored.
See also:
kmq_subscribe_hwnd() for more details about handling KMQ_WM_DISPATCH

KHMEXP LRESULT KHMAPI kmq_wm_dispatch | ( | LPARAM | lparm,
 |  | kmq_callback_t | cb
 | ) |  |

Dispatches a KMQ_WM_DISPATCH message to a callback.

Returns:
The return value of this function should be the return value of the window procedure. See kmq_subscribe_hwnd() documentation for example.
See also:
kmq_subscribe_hwnd() for more details about handling KMQ_WM_DISPATCH

KHMEXP LRESULT KHMAPI kmq_wm_end | ( | kmq_message * | m,
 |  | khm_int32 | rv
 | ) |  |

Ends handling a KMQ_WM_DISPATCH message.

Returns:
The return value of this function should be the return value of the window procedure. See kmq_subscribe_hwnd() documentation for example
See also:
kmq_subscribe_hwnd() for more details about handling KMQ_WM_DISPATCH

Generated on Mon Oct 22 22:56:46 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Message Types

Message Types
[NetIDMgr Message Queue]

Modules

KMSG_SYSTEM subtypes
KMSG_KCDB subtypes
KMSG_KMM subtypes
KMSG_ACT subtypes
KMSG_CRED subtypes
KMSG_ALERT Subtypes
KMSG_IDENT Subtypes

Global message types

#define | KMSG_SYSTEM 0
System messages.
#define | KMSG_ADHOC 1
Ad-hoc messages.
#define | KMSG_KCDB 2
NetIDMgr Credentials Database messages.
#define | KMSG_KMM 3
NetIDMgr Module Manager messages.
#define | KMSG_CRED 4
NetIDMgr Credential messages.
#define | KMSG_ACT 5
Action list messages.
#define | KMSG_ALERT 6
Alert messages.
#define | KMSG_IDENT 7
Identity messages.
#define | KMSGBASE_USER 16
Base message type ID for customized message types.

Define Documentation

#define KMSG_ACT 5

Action list messages.

Notifications of changes in action state and firing of custom actions.

See also:
KMSG_ACT subtypes

#define KMSG_ADHOC 1

Ad-hoc messages.

These are messages that are sent through add hoc publishers and subscribers.

#define KMSG_ALERT 6

Alert messages.

Notifier is the component which displays alerts and error messages when the NetIDMgr window is normally in operation and which displays balloon prompts when the window is minimized to alert the user to important messages such as credentials expiring etc.

Note:
This is an internal message class. Components that are not the notifier should not be subscribing to alert messages.
See also:
KMSG_ALERT Subtypes

#define KMSG_CRED 4

NetIDMgr Credential messages.

Notifications of crednetial events. These are the most important events that a credentials provider should respond to. The notifications provide co-oridination between credential providers for performing basic credentials management tasks such as obtaining new credentials for an identity, deleting credentials for an identity, obtaining or deleting credentials of a particular type for an identity etc.

See also:
Handling credentials provider messages

KMSG_CRED subtypes

#define KMSG_IDENT 7

Identity messages.

These are messages that are sent to the identity provider. These are generally dispatched through a specific subscription object and are not broadcast.

See also:
KMSG_IDENT Subtypes

#define KMSG_KCDB 2

NetIDMgr Credentials Database messages.

These messages notify subscribers of events related to the credentials database, such as the registration, unregistration and modification of identities, attributes, attribute types and credential types. It also provides notifications of changes to the root crednetial set.

See also:
KMSG_KCDB subtypes

#define KMSG_KMM 3

NetIDMgr Module Manager messages.

See also:
KMSG_KMM subtypes

#define KMSG_SYSTEM 0

System messages.

All subscribers are subscribed to the system message class by default.

See also:
KMSG_SYSTEM subtypes

Generated on Mon Oct 22 22:56:44 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: KMSG_SYSTEM subtypes

KMSG_SYSTEM subtypes
[Message Types]

Defines

#define | KMSG_SYSTEM_INIT 1
Generic initialization message.
#define | KMSG_SYSTEM_EXIT 2
Generic uninitialization message.
#define | KMSG_SYSTEM_COMPLETION 3
Message completion.

Define Documentation

#define KMSG_SYSTEM_COMPLETION 3

Message completion.

This is an internal message

#define KMSG_SYSTEM_EXIT 2

Generic uninitialization message.

Used by specific components to signal that the recipient should perform uninitilization tasks in preparation of termination. The return value of this message is not used.

Usually this is the last message to be received by the recipient.

See also:
Uninitialization

#define KMSG_SYSTEM_INIT 1

Generic initialization message.

This message is used by specific components to signal that the recipient is to perform initialization tasks. As a convention, the recipient should return KHM_ERROR_SUCCESS if it successfully performed the initlization tasks or some other value if it failed to do so. Failure to successfully initialize is usually taken to mean that the recipient component is not able to perform its function.

Usually this is the first message to be received by the recipient.

See also:
Initialization

Generated on Mon Oct 22 22:56:44 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: KMSG_KCDB subtypes

KMSG_KCDB subtypes
[Message Types]

Defines

#define | KMSG_KCDB_IDENT 1
#define | KMSG_KCDB_CREDTYPE 2
#define | KMSG_KCDB_ATTRIB 3
#define | KMSG_KCDB_TYPE 4
#define | KMSG_KCDB_REQUEST 256
Generic credentials request.

Define Documentation

#define KMSG_KCDB_REQUEST 256

Generic credentials request.

See also:
kcdb_cred_request for more information

Generated on Mon Oct 22 22:56:44 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: KMSG_KMM subtypes

KMSG_KMM subtypes
[Message Types]

Defines

#define | KMSG_KMM_I_REG 1
#define | KMSG_KMM_I_DONE 2

Generated on Mon Oct 22 22:56:44 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: KMSG_ACT subtypes

KMSG_ACT subtypes
[Message Types]

Defines

#define | KMSG_ACT_ENABLE 1
One or more actions changed state.
#define | KMSG_ACT_CHECK 2
One or more actions changed check state.
#define | KMSG_ACT_REFRESH 3
Refresh action states.
#define | KMSG_ACT_NEW 4
A new action was created.
#define | KMSG_ACT_DELETE 5
A custom action was deleted.
#define | KMSG_ACT_ACTIVATE 6
A custom action has been activated.
#define | KMSG_ACT_BEGIN_CMDLINE 128
Internal.
#define | KMSG_ACT_CONTINUE_CMDLINE 129
Internal.
#define | KMSG_ACT_SYNC_CFG 130
Internal.
#define | KMSG_ACT_END_CMDLINE 131
Internal.

Define Documentation

#define KMSG_ACT_ACTIVATE 6

A custom action has been activated.

When a custom action is activated, then the listener of that custom action receives this message. Note that only the listener for that custom action will receive this notification.

uparam of the message is set to the identifier of the custom action.

#define KMSG_ACT_CHECK 2

One or more actions changed check state.

Sent in response to khui_check_radio_action() or khui_check_action() and indicates that one or more actions have either been checked or unchecked.

#define KMSG_ACT_DELETE 5

A custom action was deleted.

Sent after a custom action is deleted. The uparam parameter of the message contains the identifier of the deleted action.

#define KMSG_ACT_ENABLE 1

One or more actions changed state.

This message is sent in response to a call to khui_enable_actions() or khui_enable_action() and indicates that one or more actions have changed their state.

#define KMSG_ACT_NEW 4

A new action was created.

Sent when a new custom action was created. The uparam parameter of the message contains the identifier of the newly created action.

#define KMSG_ACT_REFRESH 3

Refresh action states.

Sent after a batch of modifications were made to action states.

Generated on Mon Oct 22 22:56:44 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: KMSG_CRED subtypes

KMSG_CRED subtypes
[Message Types]

Defines

#define | KMSG_CRED_ROOTDELTA 1
Root credential set changed.
#define | KMSG_CRED_REFRESH 2
Re-enumerate credentials.
#define | KMSG_CRED_PASSWORD 16
Change the password.
#define | KMSG_CRED_NEW_CREDS 17
Initiate the process of obtaining new credentials.
#define | KMSG_CRED_RENEW_CREDS 18
Renew credentials.
#define | KMSG_CRED_DIALOG_SETUP 19
Dialog setup.
#define | KMSG_CRED_DIALOG_PRESTART 20
Dialog pre-start.
#define | KMSG_CRED_DIALOG_START 21
Dialog start.
#define | KMSG_CRED_DIALOG_NEW_IDENTITY 22
The primary identity of the new credentials dialog has changed.
#define | KMSG_CRED_DIALOG_NEW_OPTIONS 23
New credentials options have changed.
#define | KMSG_CRED_PROCESS 24
Process dialog.
#define | KMSG_CRED_END 25
End a credentials acquisition operation.
#define | KMSG_CRED_IMPORT 26
Import credentials from the operating system.
#define | KMSG_CRED_DESTROY_CREDS 32
Destroy credentials.
#define | KMSG_CRED_PP_BEGIN 128
A property page is being launced.
#define | KMSG_CRED_PP_PRECREATE 129
A property page is about to be created.
#define | KMSG_CRED_PP_END 130
A property page has finished processing.
#define | KMSG_CRED_PP_DESTROY 131
A property page has been destroyed.
#define | KMSG_CRED_ADDR_CHANGE 140
An IP address change occurred.
#define | IS_CRED_ACQ_MSG(msg) ((msg) >= 16 && (msg) <=31)
Check if a KMSG_CRED subtype is a credentials acquisition message.

Define Documentation

#define IS_CRED_ACQ_MSG ( msg ) ((msg) >= 16 && (msg) <=31)

Check if a KMSG_CRED subtype is a credentials acquisition message.

Dialog messages are those that deal with the new or initial credentials acquisition dialog, from initial announcement to dialog completion.

Currently, the dialog messages are:

  • KMSG_CRED_NEW_CREDS
  • KMSG_CRED_RENEW_CREDS
  • KMSG_CRED_DIALOG_SETUP
  • KMSG_CRED_DIALOG_PRESTART
  • KMSG_CRED_DIALOG_START
  • KMSG_CRED_DIALOG_NEW_IDENTITY
  • KMSG_CRED_DIALOG_NEW_OPTIONS
  • KMSG_CRED_PROCESS
  • KMSG_CRED_END

All dialog message numbers are allocated in a contigous block.

Note that while KMSG_CRED_PROCESS and KMSG_CRED_END are not specific to dialogs, they are still included in this predicate because they are also part of the dialog message sequence.

#define KMSG_CRED_ADDR_CHANGE 140

An IP address change occurred.

There are no parameters for this message. The NetIDMgr application handles this message and depending on configuration, posts message for the individual credentials providers to either obtain new credentials or renew old ones.

#define KMSG_CRED_DESTROY_CREDS 32

Destroy credentials.

Notification that the specified credentials should be destroyed. Once this message has completed processing a KMSG_CRED_REFRESH message will be issued.

The credentials that should be destroyed are specified by a khui_action_context structure. The context that should be used is the selection context. Hence, the credentials that must be destroyed are the ones lised in the credential set (credset).

Message parameters:

  • upram : Unused. Zero.

  • vparam : pointer to a khui_action_context structure which describes which credentials need to be destroyed.

#define KMSG_CRED_DIALOG_NEW_IDENTITY 22

The primary identity of the new credentials dialog has changed.

This message is not sent out by the UI, but is reserved here for use by individual credentials providers. The message may be sent from the dialog procedure to the plugin.

Message parameters:

  • vparam : pointer to a khui_new_creds structure

Note:
Be careful when sending this message. All messages that are not sent by the system should not be sent via broadcast. Instead, create a subscription using kmq_create_subscription() for the individual plugin that you want to send the message and use one of the per-subscription message functions to send the actual message.

#define KMSG_CRED_DIALOG_NEW_OPTIONS 23

New credentials options have changed.

This message is not sent out by the UI, but is reserved here for use by individual credentials providers. The message may be sent from the dialog procedure to the plugin.

Message parameters:

  • vparam : pointer to a khui_new_creds structure

Note:
Be careful when sending this message. All messages that are not sent by the system should not be sent via broadcast. Instead, create a subscription using kmq_create_subscription() for the individual plugin that you want to send the message and use one of the per-subscription message functions to send the actual message.

#define KMSG_CRED_DIALOG_PRESTART 20

Dialog pre-start.

Sent after all the credentials providers have responded to KMSG_CRED_DIALOG_SETUP and all the initialization has been completed. Credentials providers are expected to respond to this message by loading any default data into the dialog controls for each credential type.

Message parameters:

  • vparam : pointer to a khui_new_creds structure

Note:
May be sent to individual credential subscriptions.

#define KMSG_CRED_DIALOG_SETUP 19

Dialog setup.

Once KMSG_CRED_NEW_CREDS has been responded to by all the credential types, the UI creates the dialog windows using the data supplied in the khui_new_creds_by_type structures and issues this message. Each credentials provider is expected to respond by finalizing dialog creation operations.

Message parameters:

  • vparam : pointer to a khui_new_creds structure

Note:
May be sent to individual credential subscriptions.

#define KMSG_CRED_DIALOG_START 21

Dialog start.

A notification that the dialog is now in progress.

Message parameters:

  • vparam : pointer to a khui_new_creds structure

Note:
May be sent to individual credential subscriptions.

#define KMSG_CRED_END 25

End a credentials acquisition operation.

A notification that the credentials acquisition operation has ended.

Message parameters:

  • vparam : pointer to a khui_new_creds structure

Note:
May be sent to individual credential subscriptions.

#define KMSG_CRED_IMPORT 26

Import credentials from the operating system.

Notification to all credentials providers to import any available credentials from the operating system.

Message parameters:

  • This message does not have any parameters

#define KMSG_CRED_NEW_CREDS 17

Initiate the process of obtaining new credentials.

The UI sends this message to start the process of obtaining new credentials. See Managed credential acquisition for more information about handling this message.

A plug-in handling this message that wishes to participate in the new credentials acquisition operation is expected to add a khui_new_creds_by_type to hte list of participants in the khui_new_creds structure by calling khui_cw_add_type().

Message parameters:

  • vparam : pointer to a khui_new_creds structure

See also:
Managed credential acquisition, khui_cw_add_type(), khui_new_creds, khui_new_creds_by_type

#define KMSG_CRED_PASSWORD 16

Change the password.

This message notifies credentials providers that a password change request has been received.

A plug-in handling this message that wishes to participate in the password change operation is expected to add a khui_new_creds_by_type to the list of participants in the khui_new_creds structure by calling khui_cw_add_type().

The password change operation requires user interaction. Any plug-ins that are participating in the operation need to provide a user-interface.

Message parameters:

  • vparam : pointer to a khui_new_creds structure

See also:
khui_cw_add_type(), khui_new_creds, khui_new_creds_by_type

#define KMSG_CRED_PP_BEGIN 128

A property page is being launced.

Handlers of this message should determine whether or not they should participate in the property sheet and if so, add a khui_property_page structure to the property sheet.

Message parameters:

  • vparam : pointer to a khui_property_sheet structure

#define KMSG_CRED_PP_DESTROY 131

A property page has been destroyed.

Message parameters:

  • vparam : pointer to a khui_property_sheet structure

Note:
This is a notification that the property sheet processing has been completed and that the property sheet data structures should be freed. Any property page data structures should have already been freed while processing KMSG_CRED_PP_END. The validity of the khui_property_sheet structure should not be relied upon while processing this message.

#define KMSG_CRED_PP_END 130

A property page has finished processing.

Handlers of this message should remove any khui_property_page structures they added when processing KMSG_CRED_PP_BEGIN.

Message parameters:

  • vparam : pointer to a khui_property_sheet structure

#define KMSG_CRED_PP_PRECREATE 129

A property page is about to be created.

Message parameters:

  • vparam : pointer to a khui_property_sheet structure

Note:
This message is merely a notification that the property sheet is being created. Handlers should not modify the state of the property sheet or pages at this time.

#define KMSG_CRED_PROCESS 24

Process dialog.

Sent to all the credential providers to look at the contents of the given khui_new_creds structure and do any required processing.

If the result field in the structure is set to KHUI_NC_RESULT_PROCESS, then new credentials should be obtained using the given data.

Set the response field in the structure to indicate how the UI should proceed from here.

Message parameters:

  • vparam : pointer to a khui_new_creds structure

Note:
May be sent to individual credential subscriptions.

#define KMSG_CRED_REFRESH 2

Re-enumerate credentials.

A notice to all credential providers to re-enumerate their respective credentials.

Note:
May be sent to individual credential subscriptions.

#define KMSG_CRED_RENEW_CREDS 18

Renew credentials.

This is a notification sent to individual credentials providers that a specified identity's credentials should be renewed.

A plug-in handling this message that wishes to participate in the renew credentials operation is expected to add a khui_new_creds_by_type to the list of participants in the khui_new_creds structure by calling khui_cw_add_type().

Message parameters:

  • vparam : Pointer to a khui_new_creds object

See also:
khui_cw_add_type(), khui_new_creds, khui_new_creds_by_type

#define KMSG_CRED_ROOTDELTA 1

Root credential set changed.

This message is issued when the root credential set successfully collected credentials from another credential set.

uparam of the message is set to a bitmask indicating the change that occured. It is a combination of KCDB_DELTA_ADD, KCDB_DELTA_DEL and KCDB_DELTA_MODIFY.

Generated on Mon Oct 22 22:56:44 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: KMSG_ALERT Subtypes

KMSG_ALERT Subtypes
[Message Types]

Defines

#define | KMSG_ALERT_SHOW 1
Show an alert.
#define | KMSG_ALERT_QUEUE 2
Add an alert to the alert queue.
#define | KMSG_ALERT_SHOW_QUEUED 3
Show the next queued alert.
#define | KMSG_ALERT_CHECK_QUEUE 4
Check if there are any queued messages and, if so, update the statusbar.
#define | KMSG_ALERT_SHOW_MODAL 5
Show a modal alert.

Define Documentation

#define KMSG_ALERT_CHECK_QUEUE 4

Check if there are any queued messages and, if so, update the statusbar.

There are no message parameters

#define KMSG_ALERT_QUEUE 2

Add an alert to the alert queue.

Message parameters:

  • vparam : held pointer to a khui_alert object

Note:
the khui_alert object will be released when the queued messages are displayed.

#define KMSG_ALERT_SHOW 1

Show an alert.

Message parameters:

  • vparam : held pointer to a khui_alert object

Note:
The khui_alert object will be released when the processing of this message completes.

#define KMSG_ALERT_SHOW_MODAL 5

Show a modal alert.

Message parameters:

  • vparam : held pointer to a khui_alert object.

Note:
the khui_alert object will be released when the queued messages are displayed.

#define KMSG_ALERT_SHOW_QUEUED 3

Show the next queued alert.

There are no message parameters

Generated on Mon Oct 22 22:56:44 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: KMSG_IDENT Subtypes

KMSG_IDENT Subtypes
[Message Types]

Defines

#define | KMSG_IDENT_INIT 1
Initialize and start the identity provider.
#define | KMSG_IDENT_EXIT 2
Stop the identity provider.
#define | KMSG_IDENT_VALIDATE_NAME 3
Check if an identity name is valid.
#define | KMSG_IDENT_VALIDATE_IDENTITY 4
Check if an identity is valid.
#define | KMSG_IDENT_CANON_NAME 5
Canonicalize identity name.
#define | KMSG_IDENT_COMPARE_NAME 6
Compare names.
#define | KMSG_IDENT_SET_DEFAULT 7
Set the default identity.
#define | KMSG_IDENT_SET_SEARCHABLE 8
Set an identity as searchable.
#define | KMSG_IDENT_GET_INFO 9
Get information about an identity.
#define | KMSG_IDENT_ENUM_KNOWN 10
Enumerate known and accessible identities.
#define | KMSG_IDENT_UPDATE 11
Update information about an identity.
#define | KMSG_IDENT_GET_UI_CALLBACK 12
Retrieve the user interface callback function.
#define | KMSG_IDENT_NOTIFY_CREATE 13
Notification of the creation of an identity.

Define Documentation

#define KMSG_IDENT_CANON_NAME 5

Canonicalize identity name.

The identity provider will be given a name, which it should put in canonical form, adjusting case and any character replacement or doing any relevant expansions if applicable, and place it in the supplied buffer.

Message parameters:

  • vparam : Pointer to a kcdb_ident_name_xfer structure which provides the identity name to canonicalize in the name_src member, and the buffer to store the canonical name in the name_dest member. The name_dest buffer is guaranteed to be at least KCDB_IDENT_MAXCCH_NAME characters in size.

If the name cannot be canonicalized for some reason, the destination buffer should be set to a zero-length string and the result member of the kcdb_ident_name_xfer structure should be set to the error code. If the destination buffer is set to a zero-length string and result is KHM_ERROR_SUCCESS, then the original name provided in name_src is assumed to be already in canonical form.

#define KMSG_IDENT_COMPARE_NAME 6

Compare names.

Compare two identity names. The names that are given aren't guaranteed to be in canonical form. The return value should be akin to strcmp().

Message parameters:

  • vparam : A pointer to a kcdb_ident_name_xfer structure. The name_src member points at the first name, and the name_alt member specifies the second name. The result of the comparison should be place in result.

#define KMSG_IDENT_EXIT 2

Stop the identity provider.

Sent by the KCDB as notificaton that the identity provider is no longer the current provider.

#define KMSG_IDENT_GET_UI_CALLBACK 12

Retrieve the user interface callback function.

When obtaining new credentials, the user interface needs to obtain a callback function which will provide identity selection controls.

Message parameters:

  • uparam : Not used

  • vparam : pointer to a khui_ident_new_creds_cb which will receive the call back.

#define KMSG_IDENT_INIT 1

Initialize and start the identity provider.

Sent by the KCDB to notify the identity provider that it is now the current identity provider.

Note that unlike regular plugins, an identity provider can be loaded and inert (not provide any services). Also, the user may switch between multiple identity providers on the fly.

#define KMSG_IDENT_NOTIFY_CREATE 13

Notification of the creation of an identity.

This should be considered just a notification. The identit provider does not have an opportunity to veto the creation of an identity whose name has been found to be valid. However, when handing this notification, the identity provider can:

  • Change the flags of the identity and/or marking the identity as invalid.

  • Change the default identity.

Note that this notification is sent before the general :;KMSG_KCDB notification of the identity creation is sent.

Message parameters:

  • uparam : Not used.

  • vparam : handle to the identity

#define KMSG_IDENT_SET_DEFAULT 7

Set the default identity.

Set or unset the default identity. To set the default identity, the uparam parameter will be set to a non-zero value and a handle to the identity will be specified in vparam. To unset the default identity (i.e. not have a default identity), a zero value will be specified in uparam and no identities will be specified in vparam.

When setting a default identity, the identity provider will receive this message prior to the KCDB_IDENT_FLAG_DEFAULT bit being set or reset on any identity. It should return KHM_ERROR_SUCCESS if the requested operation can be performed. Returning any other value will abort the operation and will leave the default identity unchanged.

When resetting the default identity, this message should be treated only as a notification.

Message parameters:

  • uparam : Is non-zero if an identity is being made default. If this is zero, then identity should be the default.

  • vparam : A handle to the identity to be made default if uparam is non-zero. NULL otherwise.

Return value:

  • KHM_ERROR_SUCCESS : The identity should be marked as default
  • Any other value : The identity should not be marked as default

#define KMSG_IDENT_SET_SEARCHABLE 8

Set an identity as searchable.

Set or reset the searchable bit on an identity. If the uparam parameter is non-zero, then the searchable bit is being set. Otherwise it is being reset. The identity provider should return KHM_ERROR_SUCCESS in order to indicate that the identity should be marked as searchable. Any other value will result in the searchable bit being reset on the identity.

Message parameters:

  • uparam : Is non-zero if the searchable bit is being set. Zero otherwise.

  • vparam : Handle to the identity

Return value:

  • KHM_ERROR_SUCCESS: The identity should be marked as searchable
  • Any other value : The identity should not be marked as default

#define KMSG_IDENT_VALIDATE_IDENTITY 4

Check if an identity is valid.

Sent to the identity provider to verify the validity of the given identity. The provider should verify that the identity exists and is in a state where it can be actively used.

Depending on the result of the validation, the flags of the identity should be updated.

Message parameters:

  • vparam : Handle to an identity cast as a void pointer.

#define KMSG_IDENT_VALIDATE_NAME 3

Check if an identity name is valid.

This message is sent to the identity provider to verify the syntax of an identity name. Note that only the syntax of the name is to be verfied and not the actual physical existence of said identity.

Message parameters:

  • vparam : pointer to kcdb_ident_name_xfer object. The name to be validated will be in the name_src member. The buffer will be NULL terminated with a maximum limit of KCDB_IDENT_MAXCCH_NAME characters including the terminating NULL, consisting only of characters in KCDB_IDENT_VALID_CHARS The result member should be set to one of the following depending on the result of the validation:

  • KHM_ERROR_SUCCESS : The name was valid
  • KHM_ERROR_INVALID_NAME : The name was invalid

Generated on Mon Oct 22 22:56:45 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: kmq_response Struct Reference

kmq_response Struct Reference
[NetIDMgr Message Queue]

#include <kmq.h>

Detailed Description

A single response.

Certain broadcast messages may user scatter-gather type notification and result gathering. Individual subscribers to a message attach their individual responses to a kmq_response object and attach that to the message which can later be read by the sender of the message.

Public Member Functions

LDCL (struct tag_kmq_response)

Data Fields

kmq_thread_id | thread
void * | response

The documentation for this struct was generated from the following file:
  • kmq.h
Generated on Mon Oct 22 22:56:49 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: kmq_message Struct Reference

kmq_message Struct Reference
[NetIDMgr Message Queue]

#include <kmq.h>

Detailed Description

A single message.

Public Member Functions

LDCL (struct tag_kmq_message)

Data Fields

khm_int32 type
khm_int32 subtype
khm_ui_4 uparam
void * | vparam
khm_int32 nSent
khm_int32 nCompleted
khm_int32 nFailed
kmq_response * responses
HANDLE | wait_o
kmq_timer | timeSent
kmq_timer | timeExpire
kherr_context * err_ctx
khm_boolean aborted
khm_int32 refcount

Member Function Documentation

kmq_message::LDCL ( struct tag_kmq_message )

Internal use

Field Documentation

khm_int32 kmq_message::type

Type of message

khm_int32 kmq_message::subtype

Subtype of message

khm_ui_4 kmq_message::uparam

Integer parameter

void* kmq_message::vparam

Pointer to parameter blob

khm_int32 kmq_message::nSent

Number of instances of message sent (for broadcast messages)

khm_int32 kmq_message::nCompleted

Number of instances that have completed processing (for broadcast messages)

khm_int32 kmq_message::nFailed

Number of instances that failed to process (for broadcast messages)

kmq_response* kmq_message::responses

List of responses

HANDLE kmq_message::wait_o

Event to wait on (only valid if the publisher of the message requested a handle to the call)

kmq_timer kmq_message::timeSent

Time at which the message was sent

kmq_timer kmq_message::timeExpire

Time at which the message expires

kherr_context* kmq_message::err_ctx

Error context for the message

khm_boolean kmq_message::aborted

TRUE if the message has been aborted.

khm_int32 kmq_message::refcount

Internal use

The documentation for this struct was generated from the following file:
  • kmq.h
Generated on Mon Oct 22 22:56:48 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: User Interface

User Interface

Detailed Description

Functions and data structures for interacting with the user interface.

Modules

Actions
Alerter and Error Reporting
Configuration Panels
Hyperlink
Credentials acquisition
Property sheets
Connecting to NetIDMgr from another process
Duration sliders

Typedefs

typedef khm_int32(KHMAPI * | khm_ui_callback )(HWND hwnd_main_wnd, void *rock)
UI callback function.

Functions

KHMEXP void KHMAPI | khm_get_lib_version (khm_version *libver, khm_ui_4 *apiver)
Get the version of the NetIDMgr library.
KHMEXP khm_ui_4 KHMAPI | khm_get_commctl_version (khm_version *pdvi)
Return the version of Common Control library.
KHMEXP khm_int32 KHMAPI | khui_request_UI_callback (khm_ui_callback cb, void *rock)
Request a UI callback.

Typedef Documentation

typedef khm_int32(KHMAPI * khm_ui_callback)(HWND hwnd_main_wnd, void *rock)

UI callback function.

Used with khui_request_UI_callback().

See also:
khui_request_UI_callback()

Function Documentation

KHMEXP khm_ui_4 KHMAPI khm_get_commctl_version ( khm_version * pdvi )

Return the version of Common Control library.

Can be used to check the version of the Windows Common Control library that is currently loaded. The return value of the function is the packed version value obatained by the macro :

    MAKELONG(vesion->dwMinorVersion, version->dwMajorVersion);

The pdvi parameter is optional. Specify NULL if this is not required.

KHMEXP void KHMAPI khm_get_lib_version | ( | khm_version * | libver,
 |  | khm_ui_4 * | apiver
 | ) |  |

Get the version of the NetIDMgr library.

Parameters:
[out] | libver | Receives the version of the library.
[out] | apiver | Receives the API version of the library. Optional. Set to NULL if this value is not required.
Note:
When the NetIDMgr framework loads a plugin, it checks the version information of the plugin against the version of the library to determine if the plugin is compatible.

KHMEXP khm_int32 KHMAPI khui_request_UI_callback | ( | khm_ui_callback | cb,
 |  | void * | rock
 | ) |  |

Request a UI callback.

In general, plug-ins in Network Identity Manager run in their own thread and will not be able to interact with the user directly by creating windows of its own. There are exceptions to this, such as when the plug-in is responding to a new credentials request or if the plug-in provides configuration panels. However, if a plug-in needs to provide a user interface to the user outside of the provisions already provided by Network Identity Manager, it needs to do so from within the user interface thread.

To do so, a plug-in would provide a callback function of the type khm_ui_callback to this function. The Network Identity Manager will then call the callback function from within the user interface thread. At this point, the callback function can create any windows it wishes to create and interact with the user directly.

The callback function would be called synchronously. khui_request_UI_callback() will not return until the user interface processes the request and calls the callback function. The return code of khui_request_UI_callback() will be the return code of the callback.

Parameters:
[in] | cb | The callback function which will be called from the user interface thread.
[in] | rock | An arbitrary parameter which will be passed into the callback function.
Returns:
The return value of cb.
Note:
When the plug-in creates any windows, it should specify the window handle provided via the hwnd_main_wnd parameter as the parent window.
See also:
khm_ui_callback

Generated on Mon Oct 22 22:56:46 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Actions

Actions
[User Interface]

Modules

Standard Actions

Data Structures

struct | khui_action
An action. More...
struct | khui_action_ref
A reference to an action. More...
struct | khui_menu_def
Menu definition. More...
struct | khui_header
Outline header. More...
struct | khui_action_context
Action context. More...

Defines

#define | KHUI_ACTIONTYPE_IDENTITY 0x00010000
#define | KHUI_ACTIONTYPE_NONE 0
Unknown action type.
#define | KHUI_ACTIONTYPE_TRIGGER 1
A trigger type action.
#define | KHUI_ACTIONTYPE_TOGGLE 2
A toggle type action.
#define | KHUI_ACTIONSTATE_ENABLED 0
The action is enabled.
#define | KHUI_ACTIONSTATE_DISABLED 1
The action is diabled.
#define | KHUI_ACTIONSTATE_CHECKED 2
For toggle type actions, the action is checked.
#define | KHUI_ACTIONSTATE_HOT 4
The action is hot.
#define | KHUI_ACTIONSTATE_DELETED 8
The action has been marked for deletion.
#define | KHUI_ACTIONREF_SUBMENU 0x01
A submenu.
#define | KHUI_ACTIONREF_SEP 0x02
Separator.
#define | KHUI_ACTIONREF_PACTION 0x04
Action by reference.
#define | KHUI_ACTIONREF_DEFAULT 0x20
The default action.
#define | KHUI_MENU_NONE -3
Unspecified menu.
#define | KHUI_MENU_END -2
Menu end indicator.
#define | KHUI_MENU_SEP -1
Menu separator.
#define | KHUI_MENUSTATE_CONSTANT 0
Constant menu.
#define | KHUI_MENUSTATE_ALLOCD 1
Variable menu.
#define | khui_menu_add_action(d, c) khui_menu_insert_action((d),-1,(c),0)
#define | KHUI_MAX_HEADERS 6
Maximum number of outline headers.

Typedefs

typedef struct
tag_khui_action 		khui_action
typedef enum
tag_khui_scope 		khui_scope
Action scope identifiers.

Enumerations

enum tag_khui_scope {
KHUI_SCOPE_NONE, KHUI_SCOPE_IDENT, KHUI_SCOPE_CREDTYPE, KHUI_SCOPE_GROUP,
KHUI_SCOPE_CRED
}
Action scope identifiers. More...

Functions

KHMEXP void KHMAPI | khui_refresh_actions (void)
Refresh the global action table.
KHMEXP void KHMAPI | khui_action_lock (void)
Lock the action and menu tables.
KHMEXP void KHMAPI | khui_action_unlock (void)
Unlock the action and menu tables.
KHMEXP khui_menu_def
*KHMAPI 		khui_menu_create (khm_int32 action)
Create a new menu.
KHMEXP khui_menu_def
*KHMAPI 		khui_menu_dup (khui_menu_def *src)
Duplicate a menu.
KHMEXP void KHMAPI | khui_menu_delete (khui_menu_def *d)
Delete a menu.
KHMEXP void KHMAPI | khui_menu_insert_action (khui_menu_def *d, khm_size idx, khm_int32 cmd, khm_int32 flags)
Insert an action into a menu.
KHMEXP void KHMAPI | khui_menu_remove_action (khui_menu_def *d, khm_size idx)
Remove an action from a menu.
KHMEXP khm_size KHMAPI | khui_menu_get_size (khui_menu_def *d)
Get the number of items in the menu.
KHMEXP khui_action_ref * | khui_menu_get_action (khui_menu_def *d, khm_size idx)
Get the menu item at a specified index.
KHMEXP void KHMAPI | khui_context_set (khui_scope scope, khm_handle identity, khm_int32 cred_type, khm_handle cred, khui_header *headers, khm_size n_headers, khm_handle cs_src)
Set the current context.
KHMEXP void KHMAPI | khui_context_set_ex (khui_scope scope, khm_handle identity, khm_int32 cred_type, khm_handle cred, khui_header *headers, khm_size n_headers, khm_handle cs_src, void *vparam, khm_size cb_vparam)
Set the current context.
KHMEXP void KHMAPI | khui_context_set_indirect (khui_action_context *ctx)
Set the current UI context using an existing context.
KHMEXP void KHMAPI | khui_context_get (khui_action_context *ctx)
Obtain the current UI context.
KHMEXP void KHMAPI | khui_context_create (khui_action_context *ctx, khui_scope scope, khm_handle identity, khm_int32 cred_type, khm_handle cred)
Create a new UI context.
KHMEXP void KHMAPI | khui_context_release (khui_action_context *ctx)
Release a context obtained using khui_context_get().
KHMEXP void KHMAPI | khui_context_reset (void)
Reset the UI context.
KHMEXP void KHMAPI | khui_context_refresh (void)
Refresh context data.
KHMEXP khm_int32 KHMAPI | khui_context_cursor_filter (khm_handle cred, khm_int32 flags, void *rock)
A filter function that filters for credentials in the cursor context.
KHMEXP khm_boolean KHMAPI | khui_get_cmd_accel_string (khm_int32 cmd, wchar_t *buf, khm_size bufsiz)
Get a string representation of an accelerator.
KHMEXP khui_menu_def
*KHMAPI 		khui_find_menu (khm_int32 action)
Find a menu by id.
KHMEXP void KHMAPI | khui_action_trigger (khm_int32 action, khui_action_context *ctx)
Trigger an action.
KHMEXP khui_action
*KHMAPI 		khui_find_action (khm_int32 action)
Find an action by id.
KHMEXP khm_int32 KHMAPI | khui_action_create (const wchar_t *name, const wchar_t *caption, const wchar_t *tooltip, void *userdata, khm_int32 type, khm_handle hsub)
Create a new action.
KHMEXP void KHMAPI | khui_action_delete (khm_int32 action)
KHMEXP void *KHMAPI | khui_action_get_data (khm_int32 action)
Get the user data associated with a custom action.
KHMEXP khui_action
*KHMAPI 		khui_find_named_action (const wchar_t *name)
Find an action by name.
KHMEXP void KHMAPI | khui_enable_actions (khui_menu_def *d, khm_boolean enable)
Enables or disables a group of actions.
KHMEXP void KHMAPI | khui_enable_action (khm_int32 action, khm_boolean enable)
Enables or disables an action.
KHMEXP void KHMAPI | khui_check_radio_action (khui_menu_def *d, khm_int32 action)
Check an action in an action group.
KHMEXP void KHMAPI | khui_check_action (khm_int32 cmd, khm_boolean check)
Check an action.

Define Documentation

#define KHUI_ACTIONREF_DEFAULT 0x20

The default action.

When this bit is set in an action reference that describes a menu, the menu item will be the default item and will be rendered differently from other menu items. Only useful when defining context menus. In general, it is good practice to place the default item at the top of a menu, although the UI library does not enforce this. This is purely meant as a rendering hint.

Only one action is allowed to have this flag set. When an action is added to a menu using khui_menu_insert_action() or khui_menu_insert_paction() and this flag is set, all other menu items will be stripped of this flag.

#define KHUI_ACTIONREF_PACTION 0x04

Action by reference.

The p_action member of the structure points to the khui_action structure that describes the action.

#define KHUI_ACTIONREF_SEP 0x02

Separator.

This is not an actual action, but represents a separator between actions. When displaying this action in a menu or a toolbar, a separating line will be drawn in place of this action. The action and p_action members of the structures are unused if this flag is set.

#define KHUI_ACTIONREF_SUBMENU 0x01

A submenu.

There should exist a menu associated with the action that is being referred. When displaying this action in a menu, the contents of the associated menu will appear as a submenu.

#define KHUI_ACTIONSTATE_DELETED 8

The action has been marked for deletion.

For custom actions, this means that the custom action was deleted. The contents of the custom action fields are no longer valid.

#define KHUI_ACTIONSTATE_ENABLED 0

The action is enabled.

This is the default if no other state is specified. Just means not-disabled.

#define KHUI_ACTIONSTATE_HOT 4

The action is hot.

Typically this means that the user is hovering the pointing device over a UI element representing the action.

#define KHUI_ACTIONTYPE_NONE 0

Unknown action type.

Unknown action type.

#define KHUI_ACTIONTYPE_TOGGLE 2

A toggle type action.

A toggle type action typically changes the CHECKED state of the action each time it is invoked.

#define KHUI_ACTIONTYPE_TRIGGER 1

A trigger type action.

A trigger action usually triggers some event, which is what pretty much every action does.

#define KHUI_MAX_HEADERS 6

Maximum number of outline headers.

This is the maximum number of fields that the credentials view can be grouped by.

#define KHUI_MENU_END -2

Menu end indicator.

For static or constant menus this indicates that this action marks the end of the list of actions which defined the menu. This is invalid if used in a dynamic menu (a menu with the KHUI_MENUSTATE_ALLOCD bit set).

#define KHUI_MENU_NONE -3

Unspecified menu.

Used when there is no single command associated with the entire menu, such as for ad-hoc context menus.

#define KHUI_MENU_SEP -1

Menu separator.

A separator for actions. When displaying a menu or showing a toolbar based on a menu definition, a separator is rendered as a bar separating the user interface elements for the actions on either side of this.

#define KHUI_MENUSTATE_ALLOCD 1

Variable menu.

The menu is dnamically allocated. The list of actions contained in the menu can be modified.

#define KHUI_MENUSTATE_CONSTANT 0

Constant menu.

The contents of the menu cannot be modified (individual actions in the menu may be modified, but the order and the contents of the menu itself cannot be modified.

This is the default if KHUI_MENUSTATE_ALLOCD is not specified.

Typedef Documentation

typedef enum tag_khui_scope khui_scope

Action scope identifiers.

The scope identifier is a value which describes the scope of the cursor context. See documentation on individual scope identifiers for details.

The role of the scope identifier is to provide a summary of the current cursor context. Specifically, these identify several special cases of credential selection, such as the selection of an entire identity, a credential type or a single credential. If none of these are applicable, then the generic scope identifier KHUI_SCOPE_GROUP is set or KHUI_SCOPE_NONE if there is nothing selected.

Note that the scope typically only apply to cursor contexts and not the selection context. Please see UI Contexts for more information.

See also:
UI Contexts

Enumeration Type Documentation

enum tag_khui_scope

Action scope identifiers.

The scope identifier is a value which describes the scope of the cursor context. See documentation on individual scope identifiers for details.

The role of the scope identifier is to provide a summary of the current cursor context. Specifically, these identify several special cases of credential selection, such as the selection of an entire identity, a credential type or a single credential. If none of these are applicable, then the generic scope identifier KHUI_SCOPE_GROUP is set or KHUI_SCOPE_NONE if there is nothing selected.

Note that the scope typically only apply to cursor contexts and not the selection context. Please see UI Contexts for more information.

See also:
UI Contexts
Enumerator:
KHUI_SCOPE_NONE | No context. Nothing is selected.
KHUI_SCOPE_IDENT | Identity. The selection is the entire identity specified in the identity field of the context.
KHUI_SCOPE_CREDTYPE A credentials type. The selection is an entire credentials type. If identity is non-NULL, then the scope is all the credentials of type cred_type which belong to identity. Otherwise, the selection is all credentials of type cred_type.

Note:
The identity can be non-NULL even for the case where all credentials of type cred_type under identity is the same scope as all credentials of type cred_type under all identities.
KHUI_SCOPE_GROUP A grouping of credentials. The scope is a group of credentials which can not be simplified using one of the other context identifiers. The headers array contains n_headers elements describing the outline level that has been selected.

See also:
khui_header

KHUI_SCOPE_GROUP description

KHUI_SCOPE_CRED | A single credential. Only a single credential was selected. The cred field of the context specifies the credential. The identity and cred_type fields specify the identity and the credential type respectively.

Function Documentation

KHMEXP khm_int32 KHMAPI khui_action_create | ( | const wchar_t * | name,
 |  | const wchar_t * | caption,
 |  | const wchar_t * | tooltip,
 |  | void * | userdata,
 |  | khm_int32 | type,
 |  | khm_handle | hsub
 | ) |  |

Create a new action.

Creates a new custom action. The created custom action can be added to menus, toolbars and can be triggered by khui_action_trigger().

When the action is triggered as a result of the user selecting a menu item, a toolbar item or as a result of calling khui_action_trigger(), the subscription identified by hsub will received a message of type KMSG_ACT, subtype KMSG_ACT_ACTIVATE. The uparam for the message will be the action identifier that was returned by khui_action_create(). The vparam of the message will currently be set to NULL.

Actions can optionally be named. The name is not actively used by the Network Identity Manager framework, but can be used to label actions so that they can be looked up later using khui_find_named_action().

Parameters:
[in] | name | Name for a named action. The name must be unique among all registered actions. (limited by KHUI_MAXCCH_NAME). (Optional. Set to NULL if the action is not a named action.) See note below for additional restrictions on the name of the action.
[in] | caption | The localized caption for the action. This will be shown in menus, toolbars and buttons when the action needs to be represented. (limited by KHUI_MAXCCH_SHORT_DESC) (Required)
[in] | tooltip | The localized tooltip for the action. (limited by KHUI_MAXCCH_SHORT_DESC) (Optional, set to NULL if there is no tooltip associated with the action)
[in] | userdata | A custom value.
[in] | type | The type of the action. Currently it should be set to either KHUI_ACTIONTYPE_TRIGGER or KHUI_ACTIONTYPE_TOGGLE. For KHUI_ACTIONTYPE_TOGGLE, the initial state will be unchecked. Use khui_check_action() function to change the checked state of the action.
[in] | hsub | The subscription that is notified when the action is triggered. (Optional) The subscription must be created with kmq_create_subscription(). The handle will be released when it is no longer needed. Hence, the caller should not release it.
Returns:
The identifier of the new action or zero if the action could not be created.
Note:
For named custom actions, the name of the action can not be the same as the name of a configuration node. See khui_cfg_register_node().

KHMEXP void* KHMAPI khui_action_get_data ( khm_int32 action )

Get the user data associated with a custom action.

This function returns the user data that was specified when the custom action was created usng khui_action_create(). If the custom action identifier is invalid or if the custom action does not contain any user data, this function will return NULL.

KHMEXP void KHMAPI khui_action_lock ( void )

Lock the action and menu tables.

This function, along with khui_action_unlock() is used to prevent changes from being made to shared menus and actions while they are being updated. In particular, changes to shared menus usually need to be done in a batch and may suffer corruption of other threads access or modify the menu while one thread is updating it. Operations on shared menus should always be done with the actions locked.

KHMEXP void KHMAPI khui_action_trigger | ( | khm_int32 | action,
 |  | khui_action_context * | ctx
 | ) |  |

Trigger an action.

Triggers the specified action using the specified UI context.

This function does not return until the specified action has been processed. Many standard actions are asynchronous and they will return before processing will complete.

Pseudo actions should not be triggered using khui_action_trigger() as they only carry meaning when invoked from specific windows or contexts.

Parameters:
[in] | action | Action. Should be one of the standard actions or an action created by khui_action_create()
[in] | ctx | The UI context to use for the action. If this is NULL, the action will be triggered under the current UI context.

KHMEXP void KHMAPI khui_action_unlock ( void )

Unlock the action and menu tables.

Unlocks the action and menu tables after a call to khui_action_lock().

See also:
khui_action_lock()

KHMEXP void KHMAPI khui_check_action | ( | khm_int32 | cmd,
 |  | khm_boolean | check
 | ) |  |

Check an action.

For toggle typed actions, this sets or resets the check.

KHMEXP void KHMAPI khui_check_radio_action | ( | khui_menu_def * | d,
 |  | khm_int32 | action
 | ) |  |

Check an action in an action group.

Marks the action denoted by action as checked and resets the checked bit in all other actions.

Parameters:
[in] | d | A menu definition.
[in] | action | A command identifier. Setting this to -1 will reset the checked bit in all the actions in the menu definition.

KHMEXP void KHMAPI khui_context_create | ( | khui_action_context * | ctx,
 |  | khui_scope | scope,
 |  | khm_handle | identity,
 |  | khm_int32 | cred_type,
 |  | khm_handle | cred
 | ) |  |

Create a new UI context.

The created context does not have any relation to the current UI context. This function is provided for use in situations where an application needs to provide a scope description through a khui_action_context structure.

Once the application is done with the context, it should call khui_context_release() to release the created context.

KHMEXP khm_int32 KHMAPI khui_context_cursor_filter | ( | khm_handle | cred,
 |  | khm_int32 | flags,
 |  | void * | rock
 | ) |  |

A filter function that filters for credentials in the cursor context.

This is a function of type kcdb_cred_filter_func which can be used to filter for credentials that are included in the cursor context.

The rock parameter should be a pointer to a khui_action_context structure which will be used as the filter.

For example, the following code will extract the cursor context credentials into the credential set my_credset based on the UI context my context:

    kcdb_credset_extract_filtered(my_credset,
                                  NULL,
                                  khui_context_cursor_filter,
                                  (void *) my_context);

KHMEXP void KHMAPI khui_context_get ( khui_action_context * ctx )

Obtain the current UI context.

The parameter specified by ctx will receive the current UI context. If the context contains an identity or a credential handle, a hold will be obtained on the relevant object. Use khui_context_release() to release the holds obtained in a prior call to khui_context_get().

Note:
The returned context should not be modified prior to calling khui_context_release().

KHMEXP void KHMAPI khui_context_refresh ( void )

Refresh context data.

Setting the UI context involves other side effects such as activation of or disabling certain actions based on the selection. If an operation is performed which may affect the side effects, khui_context_refresh() is called to refresh them.

An example is when setting the default identity. The state of the action KHUI_ACTION_SET_DEF_ID depends on whether the currently selected identity is the default. However, if the currently selected identity becomes the default after selection, then khui_context_refresh() should be called to adjust the state of the KHUI_ACTION_SET_DEF_ID action.

KHMEXP void KHMAPI khui_context_release ( khui_action_context * ctx )

Release a context obtained using khui_context_get().

Releases all holds obtained on related objects in a prior call to khui_context_get() and nullifies the context.

Note:
The context should not have been modified between calling khui_context_get() and khui_context_release()

KHMEXP void KHMAPI khui_context_reset ( void )

Reset the UI context.

Nullifies the current UI context and releases any holds obtained on objects related to the previous context.

KHMEXP void KHMAPI khui_context_set | ( | khui_scope | scope,
 |  | khm_handle | identity,
 |  | khm_int32 | cred_type,
 |  | khm_handle | cred,
 |  | khui_header * | headers,
 |  | khm_size | n_headers,
 |  | khm_handle | cs_src
 | ) |  |

Set the current context.

Changes the UI context to that represented by the parameters to the function. Note that specifying a valid identity or cred parameter will result in an automatic hold on the respective object. The hold will stay until another call to khui_context_set() overwrites the identity or credential handle or a call to khui_context_reset() is made.

While this API is available, it is only called from the main NetIDMgr application. Plugins do not have a good reason to call this API directly and should not do so.

Parameters:
[in] | scope | The new context scope
[in] | identity | A handle to an identity. If this is not NULL, then it should be a valid handle to an identity. Required if scope specifies KHUI_SCOPE_IDENT. Optional if scope specifies KHUI_SCOPE_CREDTYPE. Ignored otherwise.
[in] | cred_type | A credentials type. Specify KCDB_CREDTYPE_INVALID if this parameter is not given or not relevant. Required if scope specifies KHUI_SCOPE_CREDTYPE. Ignored otherwise.
[in] | cred | A handle to a credential. If this parameter is not NULL it is expected to be a valid handle to a credential. Required if scope specifies KHUI_SCOPE_CRED. Ignored otherwise.
[in] | headers | An array of headers. The n_headers parameter specifies the number of elements in the array. Set to NULL if not specified. Required if scope specifies KHUI_SCOPE_GROUP.
[in] | n_headers | Number of elements in headers. Must be less than or equal to KHUI_MAX_HEADERS. Required if headers is not NULL. Ignored otherwise.
[in] | cs_src | A handle to a credential set from which the selected credentials will be extracted. The credentials that are selected must have the KCDB_CRED_FLAG_SELECTED flag set.
Note:
This function should only be called from the UI thread.

KHMEXP void KHMAPI khui_context_set_ex | ( | khui_scope | scope,
 |  | khm_handle | identity,
 |  | khm_int32 | cred_type,
 |  | khm_handle | cred,
 |  | khui_header * | headers,
 |  | khm_size | n_headers,
 |  | khm_handle | cs_src,
 |  | void * | vparam,
 |  | khm_size | cb_vparam
 | ) |  |

Set the current context.

Changes the UI context to that represented by the parameters to the function. Note that specifying a valid identity or cred parameter will result in an automatic hold on the respective object. The hold will stay until another call to khui_context_set() overwrites the identity or credential handle or a call to khui_context_reset() is made.

While this API is available, it is only called from the main NetIDMgr application. Plugins do not have a good reason to call this API directly and should not do so.

Parameters:
[in] | scope | The new context scope
[in] | identity | A handle to an identity. If this is not NULL, then it should be a valid handle to an identity. Required if scope specifies KHUI_SCOPE_IDENT. Optional if scope specifies KHUI_SCOPE_CREDTYPE. Ignored otherwise.
[in] | cred_type | A credentials type. Specify KCDB_CREDTYPE_INVALID if this parameter is not given or not relevant. Required if scope specifies KHUI_SCOPE_CREDTYPE. Ignored otherwise.
[in] | cred | A handle to a credential. If this parameter is not NULL it is expected to be a valid handle to a credential. Required if scope specifies KHUI_SCOPE_CRED. Ignored otherwise.
[in] | headers | An array of headers. The n_headers parameter specifies the number of elements in the array. Set to NULL if not specified. Required if scope specifies KHUI_SCOPE_GROUP.
[in] | n_headers | Number of elements in headers. Must be less than or equal to KHUI_MAX_HEADERS. Required if headers is not NULL. Ignored otherwise.
[in] | cs_src | A handle to a credential set from which the selected credentials will be extracted. The credentials that are selected must have the KCDB_CRED_FLAG_SELECTED flag set.
[in] | vparam | Optional parameter blob
[in] | cb_vparam | Size of parameter blob
Note:
This function should only be called from the UI thread.

KHMEXP void KHMAPI khui_context_set_indirect ( khui_action_context * ctx )

Set the current UI context using an existing context.

Copies the context specified in ctx into the active UI context.

Parameters:
[in] ctx A pointer to a khui_action_context structure that specifies the new UI context. Cannot be NULL.

KHMEXP void KHMAPI khui_enable_action | ( | khm_int32 | action,
 |  | khm_boolean | enable
 | ) |  |

Enables or disables an action.

The action designated by the command action will either be enabled or disabled depending on the enable parameter. If enable is TRUE then the action is enabled.

KHMEXP void KHMAPI khui_enable_actions | ( | khui_menu_def * | d,
 |  | khm_boolean | enable
 | ) |  |

Enables or disables a group of actions.

The group of actions are specified by the menu definition. All valid action entries in the menu are marked as enabled or disabled according to the value of enable.

KHMEXP khui_action* KHMAPI khui_find_action ( khm_int32 action )

Find an action by id.

Note:
This function should not be used by plugins. It is there for use by the NetIDMgr application.

KHMEXP khui_menu_def* KHMAPI khui_find_menu ( khm_int32 action )

Find a menu by id.

Finds the menu that is associated with the specified action.

KHMEXP khm_boolean KHMAPI khui_get_cmd_accel_string | ( | khm_int32 | cmd,
 |  | wchar_t * | buf,
 |  | khm_size | bufsiz
 | ) |  |

Get a string representation of an accelerator.

Parameters:
[in] | cmd | Command for which to obtain the accelerator string for
[out] | buf | Buffer to receive the accelerator string
[in] | bufsiz | Size of the buffer in bytes. Note that the size of the buffer must be sufficient to hold at least one character and a NULL terminator.
Returns:
TRUE if the operation was successful. FALSE otherwise.

KHMEXP khui_menu_def* KHMAPI khui_menu_create ( khm_int32 action )

Create a new menu.

Creates a new menu. The returned data structure must be freed by a call to khui_menu_delete(). Custom menus that are created this way are not reference counted or maintained by the UI library. The caller is responsible for calling khui_menu_delete() when the data is no longer needed.

Specifiying an action in the action parameter will associate the menu with the specified action. In this case, if the action is added to another menu with the KHUI_ACTIONREF_SUBMENU flag, this menu will appear as a submenu within that menu. Only one menu can be associated with any given action. Custom menus can not be associated with standard actions.

KHMEXP void KHMAPI khui_menu_delete ( khui_menu_def * d )

Delete a menu.

Deletes a menu created by a call to khui_menu_create() or khui_menu_dup(). This frees up the memory and associated resources used by the menu definition. The pointer that is passed in will no longer be valid.

KHMEXP khui_menu_def* KHMAPI khui_menu_dup ( khui_menu_def * src )

Duplicate a menu.

Creates a copy of the specified menu. The returned data structure must be freed by a call to khui_menu_delete(). Custom menus are not reference counted or maintained by the UI library. The caller is responsible for calling khui_menu_delete() when the data is no longer needed.

Note that even if the original menu was associated with an action, the duplicate will not be. Modifying the duplicate will not modify the original menu. Only one menu can be associated with an action.

KHMEXP khui_action_ref* khui_menu_get_action | ( | khui_menu_def * | d,
 |  | khm_size | idx
 | ) |  |

Get the menu item at a specified index.

The returned reference is only valid while the khui_menu_def structure is valid. In addition, the reference becomes invalid if the list of actions in the menu data structure is modified in any way.

If the specified index is out of bounds, then the function returns NULL.

KHMEXP khm_size KHMAPI khui_menu_get_size ( khui_menu_def * d )

Get the number of items in the menu.

Note that the count includes menu separators. The indices of the menu items range from 0 to one less than the value returned by this function.

KHMEXP void KHMAPI khui_menu_insert_action | ( | khui_menu_def * | d,
 |  | khm_size | idx,
 |  | khm_int32 | cmd,
 |  | khm_int32 | flags
 | ) |  |

Insert an action into a menu.

The action specified by cmd will be inserted in to the menu d at index idx.

Parameters:
[in] | d | The menu to insert the action into
[in] | idx | The index at which to insert the action. The index is zero based. If idx is (-1) or larger than the largest index in the menu, the item is appended to the menu.
[in] | cmd | The command representing the action to insert into the menu. This should be either a standard action, a user action created with khui_action_create(), or certain pseudo actions. Not all pseudo actions can be placed on a menu.
[in] | flags | Flags for the action. This is a combination of KHUI_ACTIONREF_* constants. Currently, the only constants that are valid for this function are: KHUI_ACTIONREF_SEP, KHUI_ACTIONREF_SUBMENU, KHUI_ACTIONREF_DEFAULT. KHUI_ACTIONREF_SEP will be automatically added if the command is KHUI_MENU_SEP. If KHUI_ACTIONREF_DEFAULT is specified, then all other items in the menu will be stripped of that flag leaving this action as the only one with that flag set.

KHMEXP void KHMAPI khui_menu_remove_action | ( | khui_menu_def * | d,
 |  | khm_size | idx
 | ) |  |

Remove an action from a menu.

The action at the specified index will be removed from the menu.

KHMEXP void KHMAPI khui_refresh_actions ( void )

Refresh the global action table.

Changes to system menus and toolbars may not be immediately reflected in the user interface. Calling this function forces the UI to reparse the action tables and menus and refresh the application menu bar and toolbars.

Generated on Mon Oct 22 22:56:46 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Standard Actions

Standard Actions
[Actions]

Standard actions

#define | KHUI_ACTION_BASE 50000
#define | KHUI_ACTION_PROPERTIES (KHUI_ACTION_BASE + 0)
#define | KHUI_ACTION_EXIT (KHUI_ACTION_BASE + 1)
#define | KHUI_ACTION_SET_DEF_ID (KHUI_ACTION_BASE + 3)
#define | KHUI_ACTION_SET_SRCH_ID (KHUI_ACTION_BASE + 4)
#define | KHUI_ACTION_PASSWD_ID (KHUI_ACTION_BASE + 7)
#define | KHUI_ACTION_NEW_CRED (KHUI_ACTION_BASE + 8)
#define | KHUI_ACTION_DEBUG_WINDOW (KHUI_ACTION_BASE + 10)
#define | KHUI_ACTION_VIEW_REFRESH (KHUI_ACTION_BASE + 11)
#define | KHUI_ACTION_LAYOUT_ID (KHUI_ACTION_BASE + 12)
#define | KHUI_ACTION_LAYOUT_TYPE (KHUI_ACTION_BASE + 13)
#define | KHUI_ACTION_LAYOUT_LOC (KHUI_ACTION_BASE + 14)
#define | KHUI_ACTION_TB_STANDARD (KHUI_ACTION_BASE + 15)
#define | KHUI_ACTION_OPT_KHIM (KHUI_ACTION_BASE + 16)
#define | KHUI_ACTION_OPT_IDENTS (KHUI_ACTION_BASE + 17)
#define | KHUI_ACTION_OPT_NOTIF (KHUI_ACTION_BASE + 18)
#define | KHUI_ACTION_HELP_CTX (KHUI_ACTION_BASE + 19)
#define | KHUI_ACTION_HELP_CONTENTS (KHUI_ACTION_BASE + 20)
#define | KHUI_ACTION_HELP_INDEX (KHUI_ACTION_BASE + 21)
#define | KHUI_ACTION_HELP_ABOUT (KHUI_ACTION_BASE + 22)
#define | KHUI_ACTION_DESTROY_CRED (KHUI_ACTION_BASE + 23)
#define | KHUI_ACTION_RENEW_CRED (KHUI_ACTION_BASE + 24)
#define | KHUI_ACTION_OPEN_APP (KHUI_ACTION_BASE + 25)
#define | KHUI_ACTION_MENU_ACTIVATE (KHUI_ACTION_BASE + 26)
#define | KHUI_ACTION_CLOSE_APP (KHUI_ACTION_BASE + 27)
#define | KHUI_ACTION_IMPORT (KHUI_ACTION_BASE + 28)
#define | KHUI_ACTION_OPT_PLUGINS (KHUI_ACTION_BASE + 29)
#define | KHUI_ACTION_LAYOUT_CUST (KHUI_ACTION_BASE + 30)
#define | KHUI_ACTION_OPT_APPEAR (KHUI_ACTION_BASE + 31)
#define | KHUI_ACTION_LAYOUT_RELOAD (KHUI_ACTION_BASE + 32)
#define | KHUI_ACTION_RENEW_ALL (KHUI_ACTION_BASE + 33)
#define | KHUI_ACTION_DESTROY_ALL (KHUI_ACTION_BASE + 34)
#define | KHUI_ACTION_UICB (KHUI_ACTION_BASE + 35)
#define | KHUI_ACTION_LAYOUT_MINI (KHUI_ACTION_BASE + 36)
#define | KHUI_ACTION_VIEW_ALL_IDS (KHUI_ACTION_BASE + 37)

Pseudo actions

Pseudo actions do not trigger any specific function, but acts as a signal of some generic event which will be interpreted based on context.

#define | KHUI_PACTION_BASE (KHUI_ACTION_BASE + 500)
#define | KHUI_PACTION_MENU (KHUI_PACTION_BASE + 0)
#define | KHUI_PACTION_UP (KHUI_PACTION_BASE + 1)
#define | KHUI_PACTION_DOWN (KHUI_PACTION_BASE + 2)
#define | KHUI_PACTION_LEFT (KHUI_PACTION_BASE + 3)
#define | KHUI_PACTION_RIGHT (KHUI_PACTION_BASE + 4)
#define | KHUI_PACTION_ENTER (KHUI_PACTION_BASE + 5)
#define | KHUI_PACTION_ESC (KHUI_PACTION_BASE + 6)
#define | KHUI_PACTION_OK (KHUI_PACTION_BASE + 7)
#define | KHUI_PACTION_CANCEL (KHUI_PACTION_BASE + 8)
#define | KHUI_PACTION_CLOSE (KHUI_PACTION_BASE + 9)
#define | KHUI_PACTION_DELETE (KHUI_PACTION_BASE + 10)
#define | KHUI_PACTION_UP_EXTEND (KHUI_PACTION_BASE + 11)
#define | KHUI_PACTION_UP_TOGGLE (KHUI_PACTION_BASE + 12)
#define | KHUI_PACTION_DOWN_EXTEND (KHUI_PACTION_BASE + 13)
#define | KHUI_PACTION_DOWN_TOGGLE (KHUI_PACTION_BASE + 14)
#define | KHUI_PACTION_BLANK (KHUI_PACTION_BASE + 15)
#define | KHUI_PACTION_NEXT (KHUI_PACTION_BASE + 16)
#define | KHUI_PACTION_SELALL (KHUI_PACTION_BASE + 17)
#define | KHUI_PACTION_YES (KHUI_PACTION_BASE + 18)
#define | KHUI_PACTION_NO (KHUI_PACTION_BASE + 19)
#define | KHUI_PACTION_YESALL (KHUI_PACTION_BASE + 20)
#define | KHUI_PACTION_NOALL (KHUI_PACTION_BASE + 21)
#define | KHUI_PACTION_REMOVE (KHUI_PACTION_BASE + 22)
#define | KHUI_PACTION_KEEP (KHUI_PACTION_BASE + 23)
#define | KHUI_PACTION_DISCARD (KHUI_PACTION_BASE + 24)
#define | KHUI_PACTION_PGDN (KHUI_PACTION_BASE + 25)
#define | KHUI_PACTION_PGUP (KHUI_PACTION_BASE + 26)
#define | KHUI_PACTION_PGUP_EXTEND (KHUI_PACTION_BASE + 27)
#define | KHUI_PACTION_PGDN_EXTEND (KHUI_PACTION_BASE + 28)

Menus

Stock menus.

#define | KHUI_MENU_BASE (KHUI_ACTION_BASE + 1000)
#define | KHUI_MENU_MAIN (KHUI_MENU_BASE + 0)
#define | KHUI_MENU_FILE (KHUI_MENU_BASE + 1)
#define | KHUI_MENU_CRED (KHUI_MENU_BASE + 2)
#define | KHUI_MENU_VIEW (KHUI_MENU_BASE + 3)
#define | KHUI_MENU_OPTIONS (KHUI_MENU_BASE + 4)
#define | KHUI_MENU_HELP (KHUI_MENU_BASE + 5)
#define | KHUI_MENU_LAYOUT (KHUI_MENU_BASE + 6)
#define | KHUI_MENU_TOOLBARS (KHUI_MENU_BASE + 7)
#define | KHUI_MENU_IDENT_CTX (KHUI_MENU_BASE + 8)
#define | KHUI_MENU_TOK_CTX (KHUI_MENU_BASE + 9)
#define | KHUI_MENU_ICO_CTX_MIN (KHUI_MENU_BASE + 12)
#define | KHUI_MENU_ICO_CTX_NORMAL (KHUI_MENU_BASE + 13)
#define | KHUI_MENU_CWHEADER_CTX (KHUI_MENU_BASE + 14)
#define | KHUI_MENU_COLUMNS (KHUI_MENU_BASE + 15)
#define | KHUI_PMENU_TOK_SEL (KHUI_MENU_BASE + 10)
#define | KHUI_PMENU_ID_SEL (KHUI_MENU_BASE + 11)
#define | KHUI_MENU_DESTROY_CRED (KHUI_MENU_BASE + 16)
#define | KHUI_MENU_RENEW_CRED (KHUI_MENU_BASE + 17)
#define | KHUI_MENU_SETDEF (KHUI_MENU_BASE + 18)

Toolbars

#define | KHUI_TOOLBAR_BASE (KHUI_ACTION_BASE + 2000)
#define | KHUI_TOOLBAR_STANDARD (KHUI_TOOLBAR_BASE + 0)

Defines

#define | KHUI_USERACTION_BASE (KHUI_ACTION_BASE + 10000)
Base for user actions.
#define | IS_USERACTION(cmd) ((cmd) >= KHUI_USERACTION_BASE)
Does this command represent a user action?

Define Documentation

#define KHUI_USERACTION_BASE (KHUI_ACTION_BASE + 10000)

Base for user actions.

When creating new actions, the UI library will allocate command identifiers starting with this one.

Generated on Mon Oct 22 22:56:46 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: khui_action Struct Reference

khui_action Struct Reference
[Actions]

#include <intaction.h>

Detailed Description

An action.

Data Fields

khm_int32 cmd
khm_int32 type
wchar_t * | name
khm_int16 ib_normal
khm_int16 ib_hot
khm_int16 ib_disabled
khm_int16 ib_icon
khm_int16 ib_icon_dis
khm_int16 is_caption
khm_int16 is_tooltip
khm_int16 ih_topic
wchar_t * | caption
wchar_t * | tooltip
khm_handle listener
void * | data
void * | reserved1
void * | reserved2
void * | reserved3
int | state

Field Documentation

khm_int32 khui_action::cmd

action identifier

khm_int32 khui_action::type

combination of KHUI_ACTIONTYPE_*

wchar_t* khui_action::name

name for named actions. NULL if not named.

khm_int16 khui_action::ib_normal

(internal) normal bitmap (index) (toolbar sized icon)

khm_int16 khui_action::ib_hot

(internal) hot bitmap (index) (toolbar sized icon)

khm_int16 khui_action::ib_disabled

(internal) disabled bitmap (index) (toolbar sized icon)

khm_int16 khui_action::ib_icon

(internal) index of small (16x16) icon (for menu) (small icon)

khm_int16 khui_action::ib_icon_dis

(internal) index of disabled (greyed) icon (small icon)

khm_int16 khui_action::is_caption

(internal) index of string resource for caption

khm_int16 khui_action::is_tooltip

(internal) same for description / tooltip

khm_int16 khui_action::ih_topic

(internal) help topic

wchar_t* khui_action::caption

Caption (localized) (limited by KHUI_MAXCCH_SHORT_DESC). The caption is used for representing the action in menus and toolbars.

wchar_t* khui_action::tooltip

Tooltip (localized) (limited by KHUI_MAXCCH_SHORT_DESC). If this is specified, whenever the user hovers over the menu item or toolbar button representing the action, the tooltip will be displayed either on a tooltip window or in the status bar.

khm_handle khui_action::listener

Listener of this action. Should be a handle to a message subscription. When the action is invoked, a message of type KMSG_ACT and subtype KMSG_ACT_ACTIVATE will be posted to this subscriber. The uparam parameter of the message will have the identifier of the action.

void* khui_action::data

User data for custom action. This field is not used by the UI library. It is reserved for plugins to store data that is specific for this action. The data that's passed in in the userdata parameter to khui_action_create() will be stored here and can be retrieved by calling khui_action_get_data().

void* khui_action::reserved1

Reserved.

void* khui_action::reserved2

Reserved.

void* khui_action::reserved3

Reserved.

int khui_action::state

current state. combination of KHUI_ACTIONSTATE_*

The documentation for this struct was generated from the following file:
  • intaction.h
Generated on Mon Oct 22 22:56:48 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: khui_action_ref Struct Reference

khui_action_ref Struct Reference
[Actions]

#include <khaction.h>

Detailed Description

A reference to an action.

If the flags member has the KHUI_ACTIONREF_PACTION bit set, then the action is referenced by the p_action member of the union. Otherwise the identifier for the action is specified by action member.

Data Fields

int flags
union {
khm_int32 action
khui_action * p_action
};

Field Documentation

int khui_action_ref::flags

A combination of KHUI_ACTIONREF_*

khm_int32 khui_action_ref::action

The action identifier for the action that is being referrred to. Only valid if KHUI_ACTIONREF_PACTION is not set in flags.

khui_action* khui_action_ref::p_action

A pointer to the khui_action structure that describes the action that is being referred to. Only valid if KHUI_ACTIONREF_PACTION is set.

The documentation for this struct was generated from the following file:
  • khaction.h
Generated on Mon Oct 22 22:56:48 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: khui_menu_def Struct Reference

khui_menu_def Struct Reference
[Actions]

#include <khaction.h>

Detailed Description

Menu definition.

Use the khui_menu_create(), khui_menu_insert_action(), khui_menu_insert_paction(), khui_menu_get_size(), khui_menu_get_action() functions to create and manipulate custom menus. Do not manipulate this structure directly as doing so may cause inconsistencies in the UI library.

Data Fields

khm_int32 cmd
khm_int32 state
khm_size n_items
khm_size nc_items
khui_action_ref * items

Field Documentation

khm_int32 khui_menu_def::cmd

Action associated with menu

khm_int32 khui_menu_def::state

combination of KHUI_MENUSTATE_*

khm_size khui_menu_def::n_items

The number of actions in the items list. If this is a custom menu, the KHUI_MENUSTATE_ALLOCD bit will be set, and the contents of this field will be valid. Otherwise, the contents of this field is ignored and the list of actions must be terminated with a ACTION_LIST_END action.

khm_size khui_menu_def::nc_items

max number of items in the buffer alocated for items. Ignored if KHUI_MENUSTATE_ALLOCD is not set in state.

khui_action_ref* khui_menu_def::items

Action list terminated by, ACTION_LIST_END. If n_items is set to a value other than -1, the list doesn't necessarily have to end with a ACTION_LIST_END. When constructing a menu using khui_menu_* functions, they will set the size of this list in the n_items member, and there will be no ACTION_LIST_END action to terminate the list.

The documentation for this struct was generated from the following file:
  • khaction.h
Generated on Mon Oct 22 22:56:48 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: khui_header Struct Reference

khui_header Struct Reference
[Actions]

#include <khaction.h>

Detailed Description

Outline header.

Describes an outline header in the user interface.

See also:
KHUI_SCOPE_GROUP description

Data Fields

khm_int32 attr_id
void * data
khm_size cb_data

Field Documentation

khm_int32 khui_header::attr_id

Attribute ID

void* khui_header::data

Value of attribute

khm_size khui_header::cb_data

Size of the value

The documentation for this struct was generated from the following file:
  • khaction.h
Generated on Mon Oct 22 22:56:48 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: khui_action_context Struct Reference

khui_action_context Struct Reference
[Actions]

#include <khaction.h>

Detailed Description

Action context.

Represents the UI context for an action.

Data Fields

khm_int32 magic
khui_scope scope
khm_handle identity
khm_int32 cred_type
khm_handle cred
khui_header | headers [KHUI_MAX_HEADERS]
khm_size n_headers
khm_handle credset
khm_size n_sel_creds
void * | int_buf
khm_size int_cb_buf
khm_size int_cb_used
void * | vparam
khm_size cb_vparam

Field Documentation

khm_int32 khui_action_context::magic

Internal.

khui_scope khui_action_context::scope

Context scope. One of khui_scope

khm_handle khui_action_context::identity

Identity

khm_int32 khui_action_context::cred_type

Credential type ID

khm_handle khui_action_context::cred

Credential

khui_header khui_action_context::headers[KHUI_MAX_HEADERS]

The ordered set of outline headers which define the current cursor location.

khm_size khui_action_context::n_headers

Number of actual headers defined above

khm_handle khui_action_context::credset

Handle to a credential set containing the currently selected credentials. When the context is obtained through khui_context_get(), this credential is returned in a sealed state.

khm_size khui_action_context::n_sel_creds

Number of selected credentials

void* khui_action_context::int_buf

Internal. Do not use.

khm_size khui_action_context::int_cb_buf

Internal. Do not use.

khm_size khui_action_context::int_cb_used

Internal. Do not use.

void* khui_action_context::vparam

Optional data

khm_size khui_action_context::cb_vparam

Size of optional data

The documentation for this struct was generated from the following file:
  • khaction.h
Generated on Mon Oct 22 22:56:48 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Alerter and Error Reporting

Alerter and Error Reporting
[User Interface]

Data Structures

struct | khui_alert

Defines

#define | KHUI_ALERT_MAGIC 0x48c39ce9
#define | KHUI_MAX_ALERT_COMMANDS 4
#define | KHUI_MAXCCH_TITLE 256
Maximum number of characters in title including terminating NULL.
#define | KHUI_MAXCB_TITLE (KHUI_MAXCCH_TITLE * sizeof(wchar_t))
Maximum number of bytes in title including terminating NULL.
#define | KHUI_MAXCCH_MESSAGE 1024
Maximum number of characters in message including terminating NULL.
#define | KHUI_MAXCB_MESSAGE (KHUI_MAXCCH_MESSAGE * sizeof(wchar_t))
Maximum number of bytes in message including terminating NULL.
#define | KHUI_MAXCCH_SUGGESTION 1024
Maxumum number of characters in a suggestion including terminating NULL.
#define | KHUI_MAXCB_SUGGESTION (KHUI_MAXCCH_SUGGESTION * sizeof(wchar_t))
Maximum number of bytes in a suggestion, including terminating NULL.

Typedefs

typedef struct
tag_khui_alert 		khui_alert
typedef enum
tag_khui_alert_types 		khui_alert_type
Alert types.

Enumerations

enum khui_alert_flags {
KHUI_ALERT_FLAG_FREE_STRUCT = 0x00000001, KHUI_ALERT_FLAG_FREE_TITLE = 0x00000002, KHUI_ALERT_FLAG_FREE_MESSAGE = 0x00000004, KHUI_ALERT_FLAG_FREE_SUGGEST = 0x00000008,
KHUI_ALERT_FLAG_DEFACTION = 0x00000010, KHUI_ALERT_FLAG_DISPATCH_CMD = 0x00000020, KHUI_ALERT_FLAG_VALID_TARGET = 0x00010000, KHUI_ALERT_FLAG_VALID_ERROR = 0x00020000,
KHUI_ALERT_FLAG_DISPLAY_WINDOW = 0x01000000, KHUI_ALERT_FLAG_DISPLAY_BALLOON = 0x02000000, KHUI_ALERT_FLAG_REQUEST_WINDOW = 0x04000000, KHUI_ALERT_FLAG_REQUEST_BALLOON = 0x08000000,
KHUI_ALERT_FLAG_MODAL = 0x10000000, KHUI_ALERT_FLAGMASK_RDWR = 0x0C000030
}
Flags for an alert. More...
enum tag_khui_alert_types {
KHUI_ALERTTYPE_NONE = 0, KHUI_ALERTTYPE_PLUGIN, KHUI_ALERTTYPE_EXPIRE, KHUI_ALERTTYPE_RENEWFAIL,
KHUI_ALERTTYPE_ACQUIREFAIL, KHUI_ALERTTYPE_CHPW
}
Alert types. More...

Functions

KHMEXP khm_int32 KHMAPI | khui_alert_create_empty (khui_alert **result)
Create an empty alert object.
KHMEXP khm_int32 KHMAPI | khui_alert_create_simple (const wchar_t *title, const wchar_t *message, khm_int32 severity, khui_alert **result)
Create a simple alert object.
KHMEXP khm_int32 KHMAPI | khui_alert_set_title (khui_alert *alert, const wchar_t *title)
Set the title of an alert object.
KHMEXP khm_int32 KHMAPI | khui_alert_set_message (khui_alert *alert, const wchar_t *message)
Set the message of an alert object.
KHMEXP khm_int32 KHMAPI | khui_alert_set_suggestion (khui_alert *alert, const wchar_t *suggestion)
Set the suggestion of an alert object.
KHMEXP khm_int32 KHMAPI | khui_alert_set_severity (khui_alert *alert, khm_int32 severity)
Set the severity of the alert object.
KHMEXP khm_int32 KHMAPI | khui_alert_set_flags (khui_alert *alert, khm_int32 mask, khm_int32 flags)
Sets the flags of the alert.
KHMEXP khm_int32 KHMAPI | khui_alert_clear_commands (khui_alert *alert)
Clear all the commands from an alert object.
KHMEXP khm_int32 KHMAPI | khui_alert_add_command (khui_alert *alert, khm_int32 command_id)
Add a command to an alert object.
KHMEXP khm_int32 KHMAPI | khui_alert_set_type (khui_alert *alert, khui_alert_type type)
Set the type of alert.
KHMEXP khm_int32 KHMAPI | khui_alert_set_ctx (khui_alert *alert, khui_scope scope, khm_handle identity, khm_int32 cred_type, khm_handle cred)
Set the action context for the alert.
KHMEXP khm_int32 KHMAPI | khui_alert_get_response (khui_alert *alert)
Get the response code from an alert.
KHMEXP khm_int32 KHMAPI | khui_alert_show (khui_alert *alert)
Display an alert.
KHMEXP khm_int32 KHMAPI | khui_alert_show_modal (khui_alert *alert)
Display a modal alert.
KHMEXP khm_int32 KHMAPI | khui_alert_queue (khui_alert *alert)
Queue an alert.
KHMEXP khm_int32 KHMAPI | khui_alert_show_simple (const wchar_t *title, const wchar_t *message, khm_int32 severity)
Display a simple alert.
KHMEXP khm_int32 KHMAPI | khui_alert_hold (khui_alert *alert)
Obtain a hold on the alert.
KHMEXP khm_int32 KHMAPI | khui_alert_release (khui_alert *alert)
Release the hold on the alert.
KHMEXP void KHMAPI | khui_alert_lock (khui_alert *alert)
Lock an alert.
KHMEXP void KHMAPI | khui_alert_unlock (khui_alert *alert)
Unlock an alert.

Typedef Documentation

typedef enum tag_khui_alert_types khui_alert_type

Alert types.

These types can be set with khui_alert_set_type() to indicate which type of alert this is. The types defined here are identified by the Network Identity Manager and will receive special handling whereever appropriate.

The type is a hint to the application and will not guarantee a particular behavior.

Enumeration Type Documentation

enum khui_alert_flags

Flags for an alert.

Enumerator:
KHUI_ALERT_FLAG_FREE_STRUCT | Internal. Free the structure once the alert is done.
KHUI_ALERT_FLAG_FREE_TITLE | Internal. Free the title field when the alert is done.
KHUI_ALERT_FLAG_FREE_MESSAGE | Internal. Free the message field when the alert is done.
KHUI_ALERT_FLAG_FREE_SUGGEST | Internal. Free the suggest field when the alert is done
KHUI_ALERT_FLAG_DEFACTION | If the message is displayed as a balloon prompt, then perform the default action when it is clicked. The default action is the first action added to the alert. Cannot be used if there are no actions or if KHUI_ALERT_FLAG_REQUEST_WINDOW is specified.
KHUI_ALERT_FLAG_DISPATCH_CMD | If the message has commands, when the user clicks on one of the command buttons, the corresponding command will be immediately dispatched as if khui_action_trigger() is called with a NULL UI context. Otherwise, the selected command will be stored in the alert and can be retrieved via a call to khui_alert_get_response().
KHUI_ALERT_FLAG_VALID_TARGET | Internal. There is a valid target for the alert
KHUI_ALERT_FLAG_VALID_ERROR | Internal. There is a valid error context associated with the alert
KHUI_ALERT_FLAG_DISPLAY_WINDOW | The alert has been displayed in a window
KHUI_ALERT_FLAG_DISPLAY_BALLOON | The alert has been displayed in a ballon
KHUI_ALERT_FLAG_REQUEST_WINDOW | The alert should be displayed in a window
KHUI_ALERT_FLAG_REQUEST_BALLOON | The alert should be displayed in a balloon
KHUI_ALERT_FLAG_MODAL | Internal. Modal alert. Do not set direclty.
KHUI_ALERT_FLAGMASK_RDWR | Bit mask of flags that can be set by khui_alert_set_flags()

enum tag_khui_alert_types

Alert types.

These types can be set with khui_alert_set_type() to indicate which type of alert this is. The types defined here are identified by the Network Identity Manager and will receive special handling whereever appropriate.

The type is a hint to the application and will not guarantee a particular behavior.

Enumerator:
KHUI_ALERTTYPE_NONE | No specific alert type
KHUI_ALERTTYPE_PLUGIN | Plug-in or module load related alert
KHUI_ALERTTYPE_EXPIRE | Credential or identity expiration warning
KHUI_ALERTTYPE_RENEWFAIL | Failed to renew credentials
KHUI_ALERTTYPE_ACQUIREFAIL | Failed to acquire credentials
KHUI_ALERTTYPE_CHPW | Failed to change password

Function Documentation

KHMEXP khm_int32 KHMAPI khui_alert_add_command | ( | khui_alert * | alert,
 |  | khm_int32 | command_id
 | ) |  |

Add a command to an alert object.

The command ID should be a valid registered action.

KHMEXP khm_int32 KHMAPI khui_alert_clear_commands ( khui_alert * alert )

Clear all the commands from an alert object.

See also:
khui_alert_add_command()

KHMEXP khm_int32 KHMAPI khui_alert_create_empty ( khui_alert ** result )

Create an empty alert object.

The returned result is a held pointer to a khui_alert object. Use khui_alert_release() to release the object.

KHMEXP khm_int32 KHMAPI khui_alert_create_simple | ( | const wchar_t * | title,
 |  | const wchar_t * | message,
 |  | khm_int32 | severity,
 |  | khui_alert ** | result
 | ) |  |

Create a simple alert object.

The returned result is a held pointer to a khui_alert object. Use khui_alert_release() to release the object.

Parameters:
[in] | title | The title of the alert. (Required, Localized) Limited by KHUI_MAXCCH_TITLE.
[in] | message | The message. (Required. Localized). Limited by KHUI_MAXCCH_MESSAGE.
[in] | severity | One of tag_kherr_severity
[out] | result | Receives a held pointer to a khui_alert object upon successful completion.

KHMEXP khm_int32 KHMAPI khui_alert_get_response ( khui_alert * alert )

Get the response code from an alert.

Once an alert has been displayed to the user, the user may choose a command from the list of commands provided in the alert (see khui_alert_add_command() ). This function can retrieve the selected command from the alert.

Returns:
The selected command or 0 if no commands were selected.

KHMEXP khm_int32 KHMAPI khui_alert_hold ( khui_alert * alert )

Obtain a hold on the alert.

An alert structure is only considered valid for the duration that there is a hold on it.

Use khui_alert_release() to release the hold.

KHMEXP void KHMAPI khui_alert_lock ( khui_alert * alert )

Lock an alert.

Locking an alert disallows any other thread from accessing the alert at the same time. NetIDMgr keeps a global list of all alert objects and the user interface may access any of them at various points in time. Locking the alert allows a thread to modify an alert without causing another thread to be exposed to an inconsistent state.

Once a thread obtains a lock on the alert, it must call khui_alert_unlock() to unlock it. Otherwise no other thread will be able to access the alert.

Note:
Currently the alert lock is global. Locking one alert disallows access to all other alerts as well.

Calling khui_alert_lock() is only necessary if you are accessing the khui_alert structure directly. Calling any of the khui_alert_* functions to modify the alert does not require obtaining a lock, as they perform synchronization internally.

KHMEXP khm_int32 KHMAPI khui_alert_queue ( khui_alert * alert )

Queue an alert.

Instead of displaying the alert immediately, the alert is queued and the status bar updated to notify the user that there is a pending alert. Once the user activates the pending alert, it will be displayed as if khui_alert_show() was called.

KHMEXP khm_int32 KHMAPI khui_alert_release ( khui_alert * alert )

Release the hold on the alert.

Holds obtained on an alert using any of the functions that either return a held pointer to an alert or implicitly obtains a hold on it need to be undone through a call to khui_alert_release().

KHMEXP khm_int32 KHMAPI khui_alert_set_flags | ( | khui_alert * | alert,
 |  | khm_int32 | mask,
 |  | khm_int32 | flags
 | ) |  |

Sets the flags of the alert.

The flags are as defined in khui_alert_flags. The bits that are on in mask will be set to the corresponding values in flags. Only the bits specified in KHUI_ALERT_FLAGMASK_RDWR can be specified in mask.

KHMEXP khm_int32 KHMAPI khui_alert_set_message | ( | khui_alert * | alert,
 |  | const wchar_t * | message
 | ) |  |

Set the message of an alert object.

The message is limited by KHUI_MAXCCH_MESSAGE.

KHMEXP khm_int32 KHMAPI khui_alert_set_severity | ( | khui_alert * | alert,
 |  | khm_int32 | severity
 | ) |  |

Set the severity of the alert object.

The severity value is one of tag_kherr_severity

KHMEXP khm_int32 KHMAPI khui_alert_set_suggestion | ( | khui_alert * | alert,
 |  | const wchar_t * | suggestion
 | ) |  |

Set the suggestion of an alert object.

The suggestion is limited by KHUI_MAXCCH_SUGGESTION

KHMEXP khm_int32 KHMAPI khui_alert_set_title | ( | khui_alert * | alert,
 |  | const wchar_t * | title
 | ) |  |

Set the title of an alert object.

The title is limited by KHUI_MAXCCH_TITLE.

KHMEXP khm_int32 KHMAPI khui_alert_show ( khui_alert * alert )

Display an alert.

The alert must have a valid severity, title and a message to be displayed. Otherwise the function immediately returns with a failure code.

The method used to display the alert is as follows:

  • A balloon alert will be shown if one of the following is true:
    • The NetIDMgr application is minimized or in the background.
    • KHUI_ALERT_FLAG_REQUEST_BALLOON is specified in flags.
  • Otherwise an alert window will be shown.

If the message, title of the alert is too long to fit in a balloon prompt, there's a suggestion or if there are custom commands then a placeholder balloon prompt will be shown which when clicked on, shows the actual alert in an alert window.

An exception is when KHUI_ALERT_FLAG_DEFACTION is specified in flags. In this case instead of a placeholder balloon prompt, one will be shown with the actual title and message (truncated if necessary). Clicking on the balloon will cause the first command in the command list to be performed.

The placeholder balloon prompt will have a title derived from the first 63 characters of the title field in the alert and a message notifying the user that they should click the balloon prompt for more information.

To this end, it is beneficial to limit the length of the title to 63 characters (64 counting the terminating NULL). This limit is enforced on Windows. Also, try to make the title descriptive.

User interaction with the alert will be as follows:

  • If the alert contains no commands, then the alert will be displayed to the user as described above. A 'close' button will be added to the alert if the alert is being displayed in a window.

  • If the alert contains commands, has the KHUI_ALERT_FLAG_DEFACTION flag set and is displayed in a balloon and the user clicks on it, the first command in the command list will be executed.

  • If the alert contains commands and does not have the KHUI_ALERT_FLAG_DEFACTION and has the KHUI_ALERT_FLAG_DISPATCH_CMD flag set, then when the user selects one of the command buttons, the corresponding command will immediately be dispatched. (see KHUI_ALERT_FLAG_DISPATCH_CMD).

  • If the alert contains command and have neither KHUI_ALERT_FLAG_DEFACTION nor KHUI_ALERT_FLAG_DISPATCH_CMD, then when the user selects one of the command buttons, the selected command will be stored along with the alert. It can be retrieved via a call to khui_alert_get_response().

KHMEXP khm_int32 KHMAPI khui_alert_show_modal ( khui_alert * alert )

Display a modal alert.

Similar to khui_alert_show(), but shows a modal alert dialog. The function does not return until the user has closed the alert.

This function always opens an alert window (never shows a balloon).

KHMEXP khm_int32 KHMAPI khui_alert_show_simple | ( | const wchar_t * | title,
 |  | const wchar_t * | message,
 |  | khm_int32 | severity
 | ) |  |

Display a simple alert.

See also:
khui_alert_show()

KHMEXP void KHMAPI khui_alert_unlock ( khui_alert * alert )

Unlock an alert.

See also:
khui_alert_lock()

Generated on Mon Oct 22 22:56:46 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Configuration Panels

Configuration Panels
[User Interface]

Detailed Description

Configuration panels are the primary means from which the user is presented with an interface to change NetIDMgr and plugin configuration.

Data Structures

struct | khui_config_node_reg
Registration information for a configuration node. More...
struct | khui_config_init_data
Initialization data passed in to a subpanel. More...

Defines

#define | KHUI_WM_CFG_NOTIFY (WM_APP + 0x101)
Configuration window notification message.
#define | KHUI_CNFLAG_SORT_CHILDREN 0x0001
Sort the child nodes by short description.
#define | KHUI_CNFLAG_SUBPANEL 0x0002
Is a subpanel.
#define | KHUI_CNFLAG_PLURAL 0x0004
Node represents a panel that is replicated for all child nodes.
#define | KHUI_CNFLAG_SYSTEM 0x0010
System node.
#define | KHUI_CNFLAG_MODIFIED 0x0100
Settings have been modified.
#define | KHUI_CNFLAG_APPLIED 0x0200
Settings have been applied.
#define | KHUI_CNFLAGMASK_STATIC 0x00ff
#define | KHUI_CNFLAGMASK_DYNAMIC 0x0f00
#define | KHUI_MAXCCH_NAME 256
Maximum length of the name in characters.
#define | KHUI_MAXCB_NAME (KHUI_MAXCCH_NAME * sizeof(wchar_t))
Maximum length of the name in bytes.
#define | KHUI_MAXCCH_LONG_DESC 1024
Maximum length of the long description in characters.
#define | KHUI_MAXCB_LONG_DESC (KHUI_MAXCCH_LONG_DESC * sizeof(wchar_t))
Maximum length of the long description in bytes.
#define | KHUI_MAXCCH_SHORT_DESC 256
Maximum length of the short description in chracters.
#define | KHUI_MAXCB_SHORT_DESC (KHUI_MAXCCH_SHORT_DESC * sizeof(wchar_t))
Maximum length of the short description in bytes.
#define | CFGDLG_WIDTH 255
Width of a configuration dialog in dialog units.
#define | CFGDLG_HEIGHT 182
Height of a configuration dialog in dialog units.
#define | CFGDLG_TAB_WIDTH 235
Width of a configuration tab dialog in dialog units.
#define | CFGDLG_TAB_HEIGHT 151
Height of configuration tab dialog in dialog units.

Typedefs

typedef khm_handle | khui_config_node
A handle to a configuration node.

Enumerations

enum | khui_wm_cfg_notifications { WMCFG_SHOW_NODE = 1, WMCFG_UPDATE_STATE = 2, WMCFG_APPLY = 3, WMCFG_SYNC_NODE_LIST = 4 }
Configuration notifications. More...

Functions

KHMEXP khm_int32 KHMAPI | khui_cfg_register (khui_config_node parent, const khui_config_node_reg *reg)
Register a configuration node.
KHMEXP khm_int32 KHMAPI | khui_cfg_open (khui_config_node parent, const wchar_t *name, khui_config_node *result)
Open a configuration node by name.
KHMEXP khm_int32 KHMAPI | khui_cfg_remove (khui_config_node node)
Remove a configuration node.
KHMEXP khm_int32 KHMAPI | khui_cfg_hold (khui_config_node node)
Hold a handle to a configuration node.
KHMEXP khm_int32 KHMAPI | khui_cfg_release (khui_config_node node)
Release a handle to a configuration node.
KHMEXP khm_int32 KHMAPI | khui_cfg_get_parent (khui_config_node vnode, khui_config_node *result)
Get the parent of a node.
KHMEXP khm_int32 KHMAPI | khui_cfg_get_first_child (khui_config_node parent, khui_config_node *result)
Get a handle to the first child node.
KHMEXP khm_int32 KHMAPI | khui_cfg_get_first_subpanel (khui_config_node vparent, khui_config_node *result)
Get a handle to the first subpanel.
KHMEXP khm_int32 KHMAPI | khui_cfg_get_next (khui_config_node node, khui_config_node *result)
Get a handle to the next sibling node.
KHMEXP khm_int32 KHMAPI | khui_cfg_get_next_release (khui_config_node *node)
Get a handle to the next sibling node.
KHMEXP khm_int32 KHMAPI | khui_cfg_get_name (khui_config_node node, wchar_t *buf, khm_size *cb_buf)
Get the name of a configuration node.
KHMEXP khm_int32 KHMAPI | khui_cfg_get_reg (khui_config_node node, khui_config_node_reg *reg)
Get registration information for a node.
KHMEXP HWND KHMAPI | khui_cfg_get_hwnd_inst (khui_config_node node, khui_config_node noderef)
Internal use.
KHMEXP LPARAM KHMAPI | khui_cfg_get_param_inst (khui_config_node node, khui_config_node noderef)
Internal use.
KHMEXP void KHMAPI | khui_cfg_set_hwnd_inst (khui_config_node node, khui_config_node noderef, HWND hwnd)
Internal use.
KHMEXP void KHMAPI | khui_cfg_set_param_inst (khui_config_node node, khui_config_node noderef, LPARAM param)
Internal use.
KHMEXP HWND KHMAPI | khui_cfg_get_hwnd (khui_config_node node)
Internal use.
KHMEXP LPARAM KHMAPI | khui_cfg_get_param (khui_config_node node)
Internal use.
KHMEXP void KHMAPI | khui_cfg_set_hwnd (khui_config_node node, HWND hwnd)
Internal use.
KHMEXP void KHMAPI | khui_cfg_set_param (khui_config_node node, LPARAM param)
Internal use.
KHMEXP void KHMAPI | khui_cfg_clear_params (void)
Internal use.
KHMEXP void KHMAPI | khui_cfg_set_configui_handle (HWND hwnd)
Internal use.
KHMEXP void KHMAPI | khui_cfg_set_flags (khui_config_node vnode, khm_int32 flags, khm_int32 mask)
Update the state for the specified node.
KHMEXP khm_int32 KHMAPI | khui_cfg_get_flags (khui_config_node vnode)
Retrieve the state flags for the configuration node.
KHMEXP khm_int32 KHMAPI | khui_cfg_init_dialog_data (HWND hwnd_dlg, const khui_config_init_data *data, khm_size cb_extra, khui_config_init_data **new_data, void **extra)
Utility function: Initialize dialog box window data.
KHMEXP khm_int32 KHMAPI | khui_cfg_get_dialog_data (HWND hwnd_dlg, khui_config_init_data **data, void **extra)
Utility function: Retrieves dialog data.
KHMEXP khm_int32 KHMAPI | khui_cfg_free_dialog_data (HWND hwnd_dlg)
Utility function: Free dialog data.
KHMEXP void KHMAPI | khui_cfg_set_flags_inst (khui_config_init_data *d, khm_int32 flags, khm_int32 mask)
Sets the instance flags for a subpanel.

Define Documentation

#define CFGDLG_HEIGHT 182

Height of a configuration dialog in dialog units.

See also:
CFGDLG_WIDTH

#define CFGDLG_TAB_HEIGHT 151

Height of configuration tab dialog in dialog units.

See also:
CFGDLG_TAB_WIDTH

#define CFGDLG_TAB_WIDTH 235

Width of a configuration tab dialog in dialog units.

CFGDLG_TAB_WIDTH and CFGDLG_TAB_HEIGHT specify the dimensions (in dialog units) of a dialog that will be placed within a tab control for dialogs where multiple display panels need to be shown.

#define CFGDLG_WIDTH 255

Width of a configuration dialog in dialog units.

CFGDLG_WIDTH and CFGDLG_HEIGHT specify the dimensions of a configuration dialog width and height in dialog units. The dialog will be created as a child of the configuration dialog and placed within it.

#define KHUI_CNFLAG_APPLIED 0x0200

Settings have been applied.

Set once any modified settings were successfully applied.

#define KHUI_CNFLAG_MODIFIED 0x0100

Settings have been modified.

Settings for this configuration panel have been modified. This flag should be cleared once the settings have been successfully applied.

#define KHUI_CNFLAG_SYSTEM 0x0010

System node.

Note:
For internal use by the NetIDMgr application. Do not use.

#define KHUI_MAXCB_LONG_DESC (KHUI_MAXCCH_LONG_DESC * sizeof(wchar_t))

Maximum length of the long description in bytes.

The length includes the terminating NULL

#define KHUI_MAXCB_NAME (KHUI_MAXCCH_NAME * sizeof(wchar_t))

Maximum length of the name in bytes.

The length includes the terminating NULL

#define KHUI_MAXCB_SHORT_DESC (KHUI_MAXCCH_SHORT_DESC * sizeof(wchar_t))

Maximum length of the short description in bytes.

The length includes the terminating NULL

#define KHUI_MAXCCH_LONG_DESC 1024

Maximum length of the long description in characters.

The length includes the terminating NULL

#define KHUI_MAXCCH_NAME 256

Maximum length of the name in characters.

The length includes the terminating NULL

#define KHUI_MAXCCH_SHORT_DESC 256

Maximum length of the short description in chracters.

The length includes the terminating NULL

#define KHUI_WM_CFG_NOTIFY (WM_APP + 0x101)

Configuration window notification message.

This is the message that will be used to notify dialog panels.

The format of the message is :

  • uMsg : KHUI_WM_CFG_NOTIFY
  • HIWORD(wParam) : one of khui_wm_cfg_notifications

Note:
This is the same as KHUI_WM_NC_NOTIFY

Typedef Documentation

typedef khm_handle khui_config_node

A handle to a configuration node.

See also:
khui_cfg_open_node(), khui_cfg_close_node()

Enumeration Type Documentation

enum khui_wm_cfg_notifications

Configuration notifications.

These are sent thorugh a KHUI_WM_CFG_NOTIFY message.

The format of the message is :

  • uMsg : KHUI_WM_CFG_NOTIFY
  • HIWORD(wParam) : one of khui_wm_cfg_notifications
Enumerator:
WMCFG_SHOW_NODE | Sent to the configuration dialog to request that the panel for the specified node be shown. The lParam message parameter will contain a held khui_config_node handle. The sender of the mssage is responsible for releasing the handle.
WMCFG_UPDATE_STATE Sent to the configuration dialog to indicate that the state flags for the specified configuration node have changed.

  • LOWORD(wParam) : new flags
  • lParam : khui_config_node for the node
WMCFG_APPLY | Sent to all the configuration panels when the user clicks the 'Apply' button or the 'Ok' button. The panels are responsible for applying the configuration changes and updating their flags using khui_cfg_set_flags().
WMCFG_SYNC_NODE_LIST | Sent from the UI library to the configuration window to notify the window that the node list has changed. This message is sent synchronously before the node is removed.

Function Documentation

KHMEXP void KHMAPI khui_cfg_clear_params ( void )

Internal use.

This function is used internally by NetIDMgr. Do not use.

KHMEXP khm_int32 KHMAPI khui_cfg_free_dialog_data ( HWND hwnd_dlg )

Utility function: Free dialog data.

Deallocates the memory allcated in a previous call to khui_cfg_init_dialog_data()

KHMEXP khm_int32 KHMAPI khui_cfg_get_dialog_data | ( | HWND | hwnd_dlg,
 |  | khui_config_init_data ** | data,
 |  | void ** | extra
 | ) |  |

Utility function: Retrieves dialog data.

Retrieves the dialog data previoulsy stored using khui_cfg_init_dialog_data().

Parameters:
[in] | hwnd_dlg | Handle to the dialog box
[out] | data | Receives a pointer to the khui_config_init_data block.
[out] | extra | Receives a pointer to the extra memory allocated. Optional (set to NULL if this value is not needed).

KHMEXP khm_int32 KHMAPI khui_cfg_get_first_child | ( | khui_config_node | parent,
 |  | khui_config_node * | result
 | ) |  |

Get a handle to the first child node.

If the call is successful, result will receieve a handle to the first child node of the specified node. The returned handle must be released with a call to khui_cfg_release()

If parent does not have any child nodes, the function will return KHM_ERROR_NOT_FOUND and set result to NULL.

Parameters:
[in] | parent | Parent node. Set to NULL to specify root node.
[out] | result | Receives a held handle to the first child node.
See also:
khui_cfg_get_next()

KHMEXP khm_int32 KHMAPI khui_cfg_get_first_subpanel | ( | khui_config_node | vparent,
 |  | khui_config_node * | result
 | ) |  |

Get a handle to the first subpanel.

If the call is successful, result will receieve a handle to the first subpanel node of the specified node. The returned handle must be released with a call to khui_cfg_release()

If parent does not have any subpanels, the function will return KHM_ERROR_NOT_FOUND and set result to NULL.

A subpanel node is a node which has the KHUI_CNFLAG_SUBPANEL flag set.

Parameters:
[in] | parent | Parent node. Set to NULL to specify root node.
[out] | result | Receives a held handle to the first subpanel node.
See also:
khui_cfg_get_next()

KHMEXP khm_int32 KHMAPI khui_cfg_get_flags ( khui_config_node vnode )

Retrieve the state flags for the configuration node.

See also:
khui_cfg_set_flags()

KHMEXP HWND KHMAPI khui_cfg_get_hwnd ( khui_config_node node )

Internal use.

This function is used internally by NetIDMgr. Do not use.

KHMEXP HWND KHMAPI khui_cfg_get_hwnd_inst | ( | khui_config_node | node,
 |  | khui_config_node | noderef
 | ) |  |

Internal use.

This function is used internally by NetIDMgr. Do not use.

KHMEXP khm_int32 KHMAPI khui_cfg_get_name | ( | khui_config_node | node,
 |  | wchar_t * | buf,
 |  | khm_size * | cb_buf
 | ) |  |

Get the name of a configuration node.

Gets the name (not the short description or the long description) of the given configuration node.

KHMEXP khm_int32 KHMAPI khui_cfg_get_next | ( | khui_config_node | node,
 |  | khui_config_node * | result
 | ) |  |

Get a handle to the next sibling node.

If the call is successful, result will receive a held handle to the next sibling node. The returned handle must be released with a call to khui_cfg_release().

If there are no more sibling nodes, then the function return KHM_ERROR_NOT_FOUND and set result to NULL.

This function can be used to traverse a list of child nodes as well as a list of subpanel nodes.

KHMEXP khm_int32 KHMAPI khui_cfg_get_next_release ( khui_config_node * node )

Get a handle to the next sibling node.

Similar to khui_cfg_get_next(), but implicitly releases the handle that was supplied. Equivalent to doing :

    khui_cfg_get_next(node, &next);
    khui_cfg_release(node);
    node = next;

Parameters:
[in,out] node On entry, specifies the node whose sibling needs to be fetched. On exit, will have either NULL or a held handle to the sibling node. The handle which was supplied to the function is released.
Return values:
KHM_ERROR_SUCCESS | The next node is now in node
KHM_ERROR_INVALID_PARAM | node was not a valid handle
KHM_ERROR_NOT_FOUND | There are no more siblings. node is set to NULL.
Note:
Even if there are no more siblings, the handle specified in node on entry is released.

KHMEXP LPARAM KHMAPI khui_cfg_get_param ( khui_config_node node )

Internal use.

This function is used internally by NetIDMgr. Do not use.

KHMEXP LPARAM KHMAPI khui_cfg_get_param_inst | ( | khui_config_node | node,
 |  | khui_config_node | noderef
 | ) |  |

Internal use.

This function is used internally by NetIDMgr. Do not use.

KHMEXP khm_int32 KHMAPI khui_cfg_get_parent | ( | khui_config_node | vnode,
 |  | khui_config_node * | result
 | ) |  |

Get the parent of a node.

Returns a held handle to the parent of the node, or NULL if the current node is a top level node. The returned handle must be released with khui_cfg_release().

Return values:
KHM_ERROR_SUCCESS | The handle to the parent node is in result
KHM_ERROR_NOT_FOUND | The node is a top level node

KHMEXP khm_int32 KHMAPI khui_cfg_get_reg | ( | khui_config_node | node,
 |  | khui_config_node_reg * | reg
 | ) |  |

Get registration information for a node.

The registration information that is returned is a shallow copy of the data kept by NetIDMgr. In particular, the strings that will be returned actually point to internal buffers and should not be modified.

No further action is necessary to release the information. However, the returned data ceases to be valid when node is released with a call to khui_cfg_release().

Parameters:
[in] | node | Node for which information is requested. Can be NULL if requesting information about the root node.
[out] | reg | Pointer to a khui_config_node_reg structure.

KHMEXP khm_int32 KHMAPI khui_cfg_hold ( khui_config_node node )

Hold a handle to a configuration node.

Obtains an additional hold on the handle specified by node. The hold must be released with a call to khui_cfg_release()

KHMEXP khm_int32 KHMAPI khui_cfg_init_dialog_data | ( | HWND | hwnd_dlg,
 |  | const khui_config_init_data * | data,
 |  | khm_size | cb_extra,
 |  | khui_config_init_data ** | new_data,
 |  | void ** | extra
 | ) |  |

Utility function: Initialize dialog box window data.

This function initializes the dialog box window data using the khui_config_init_data that was passed into the WM_INITDIALOG message.

A new block of memory will be alocated to store the dialog data as well as any extra space specified. A pointer to this memory block will be stored in the DWLP_USER slot in the dialog box.

The allocated block of memory must be freed by a call to khui_cfg_free_dialog_data(). While handling other messages, the dialog data can be retrieved using khui_cfg_get_dialog_data().

Parameters:
[in] | hwnd_dlg | Handle to the dialog box
[in] | data | Pointer to the khui_config_init_data that was passed in to WM_INITDIALOG (this is the value of lParam)
[in] | cb_extra | Number of extra bytes to allocate, along with the space required to store the contents of khui_config_init_data. The extra space will be initialized to zero.
[out] | new_data | Receives a pointer to the copy of the initialization data that was allocated. Optional. Pass in NULL if this value is not required.
[out] | extra | Receives a pointer to the block of extra memory allocated as specified in cb_extra. If cb_extra is 0, then this receives a NULL.
See also:
khui_cfg_get_dialog_data(), khui_cfg_free_dialog_data()

KHMEXP khm_int32 KHMAPI khui_cfg_open | ( | khui_config_node | parent,
 |  | const wchar_t * | name,
 |  | khui_config_node * | result
 | ) |  |

Open a configuration node by name.

If successful, the result parameter will receive a handle to the configuration node. Use khui_cfg_release() to release the handle.

Parameters:
[in] parent Parent node. Set to NULL to specify root node.

KHMEXP khm_int32 KHMAPI khui_cfg_register | ( | khui_config_node | parent,
 |  | const khui_config_node_reg * | reg
 | ) |  |

Register a configuration node.

The caller fills the registration information in the khui_config_node_reg structre. If the call succeeds, the function will return KHM_ERROR_SUCCESS.

Parameters:
[in] | parent | Parent of the node to be registered. Set to NULL if the parent is the root node.
[in] | reg | Registration information
[out] | new_id | Receives the new unique identifier of the configuration node. Pass in NULL if the new identifier is not required.
Return values:
KHM_ERROR_SUCCESS | Success
KHM_ERROR_INVALID_PARAM | One or more parameters, or fields of reg were invalid
KHM_ERROR_DUPLICATE | A node with the same name exists as a child of the specified parent node.
Note:
The name (not the short or long description) of the node can not be the same as the name of a custom action. See khui_action_create().

KHMEXP khm_int32 KHMAPI khui_cfg_release ( khui_config_node node )

Release a handle to a configuration node.

See also:
khui_cfg_hold()

KHMEXP khm_int32 KHMAPI khui_cfg_remove ( khui_config_node node )

Remove a configuration node.

Marks a configuration node as deleted. Once all the handles, including the handle specified in node have been released, it will be deleted.

KHMEXP void KHMAPI khui_cfg_set_configui_handle ( HWND hwnd )

Internal use.

This function is used internally by NetIDMgr. Do not use.

KHMEXP void KHMAPI khui_cfg_set_flags | ( | khui_config_node | vnode,
 |  | khm_int32 | flags,
 |  | khm_int32 | mask
 | ) |  |

Update the state for the specified node.

Parameters:
[in] | node | khui_config_node handle for the configuration node.
[in] | flags | New flags. Combination of KHUI_CNFLAG_APPLIED and KHUI_CNFLAG_MODIFIED
[in] | mask | Valid bits in flags
Note:
Should only be called from within the dialog procedure for the configuration node.

KHMEXP void KHMAPI khui_cfg_set_flags_inst | ( | khui_config_init_data * | d,
 |  | khm_int32 | flags,
 |  | khm_int32 | mask
 | ) |  |

Sets the instance flags for a subpanel.

Since there can be more than one subpanel in a configuration panel, they shouldn't modify the flags of the configuration node directly. Instead, they should call this function to set the instance flags.

The instance flags will be merged with the flags for the configuration node automatically.

KHMEXP void KHMAPI khui_cfg_set_hwnd | ( | khui_config_node | node,
 |  | HWND | hwnd
 | ) |  |

Internal use.

This function is used internally by NetIDMgr. Do not use.

KHMEXP void KHMAPI khui_cfg_set_hwnd_inst | ( | khui_config_node | node,
 |  | khui_config_node | noderef,
 |  | HWND | hwnd
 | ) |  |

Internal use.

This function is used internally by NetIDMgr. Do not use.

KHMEXP void KHMAPI khui_cfg_set_param | ( | khui_config_node | node,
 |  | LPARAM | param
 | ) |  |

Internal use.

This function is used internally by NetIDMgr. Do not use.

KHMEXP void KHMAPI khui_cfg_set_param_inst | ( | khui_config_node | node,
 |  | khui_config_node | noderef,
 |  | LPARAM | param
 | ) |  |

Internal use.

This function is used internally by NetIDMgr. Do not use.

Generated on Mon Oct 22 22:56:46 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: khui_config_node_reg Struct Reference

khui_config_node_reg Struct Reference
[Configuration Panels]

#include <khconfigui.h>

Detailed Description

Registration information for a configuration node.

See also:
khui_cfg_register_node()

Data Fields

const wchar_t * | name
const wchar_t * | short_desc
const wchar_t * | long_desc
HMODULE | h_module
LPWSTR | dlg_template
DLGPROC | dlg_proc
khm_int32 flags

Field Documentation

const wchar_t* khui_config_node_reg::name

Internal identifier (not-localized, required). The name is required to be unique among sibling nodes. However it is not required to be unique globally. The size of the name is constrained by KHUI_MAXCCH_NAME

const wchar_t* khui_config_node_reg::short_desc

Short description (Localized, required). This is the name which identifies the node within a collection of siblings. The size of the string is constrained by KHUI_MAXCCH_SHORT_DESC

const wchar_t* khui_config_node_reg::long_desc

Global name of the node. (Localized, required). This uniquely identifies the node in the collection of all configuration nodes. The size of the string is constrained by KHUI_MAXCCH_LONG_DESC.

HMODULE khui_config_node_reg::h_module

Module which contains the dialog resource specified in dlg_template

LPWSTR khui_config_node_reg::dlg_template

Dialog template for the configuration window

DLGPROC khui_config_node_reg::dlg_proc

Dialog procedure

khm_int32 khui_config_node_reg::flags

Flags. Can be a combination of KHUI_CNFLAG_SORT_CHILDREN and KHUI_CNFLAG_SUBPANEL

The documentation for this struct was generated from the following file:
  • khconfigui.h
Generated on Mon Oct 22 22:56:48 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: khui_config_init_data Struct Reference

khui_config_init_data Struct Reference
[Configuration Panels]

#include <khconfigui.h>

Detailed Description

Initialization data passed in to a subpanel.

When creating a subpanel, a pointer to the following strucutred will be passed in as the creation parameter for the dialog.

Data Fields

khui_config_node ctx_node
khui_config_node this_node
khui_config_node ref_node

Field Documentation

khui_config_node khui_config_init_data::ctx_node

The node under which the current dialog subpanel is being created.

khui_config_node khui_config_init_data::this_node

The node which provided the registration information for the creation of the subpanel.

khui_config_node khui_config_init_data::ref_node

The parent node of the subpanel node. In nodes which have the KHUI_CNFLAG_PLURAL, this would be different from the node. This is the node under which the subpanel was registered.

The documentation for this struct was generated from the following file:
  • khconfigui.h
Generated on Mon Oct 22 22:56:48 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Hyperlink

Hyperlink
[User Interface]

Data Structures

struct | khui_htwnd_link
A hyperlink. More...

Defines

#define | KHUI_MAXCCH_HTLINK_FIELD 256
#define | KHUI_MAXCB_HTLINK_FIELD (KHUI_MAXCCH_HTLINK_FIELD * sizeof(wchar_t))

Generated on Mon Oct 22 22:56:46 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: khui_htwnd_link Struct Reference

khui_htwnd_link Struct Reference
[Hyperlink]

#include <khhtlink.h>

Detailed Description

A hyperlink.

When a link in a hypertext window is clicked, this structure is passed along with the message.

The link text fields do to point to NULL terminated strings. Instead, the length fields should be used to extract the string.

Data Fields

RECT | r
wchar_t * | id
int | id_len
wchar_t * | param
int | param_len

Field Documentation

RECT khui_htwnd_link::r

The enclosing rectangle of the hyperlink. Units are screen units and the coordinates are relative to the top left hand corner of the hypertext area.

wchar_t* khui_htwnd_link::id

The value of the id attribute of the link or NULL if there was no id attribute. This does not point to a NULL terminated string. The length of the string is given by the id_len field.

int khui_htwnd_link::id_len

The length of the string pointed to by id in characters. Undefined if id is NULL.

wchar_t* khui_htwnd_link::param

The value of the param attribute of the link or NULL if there was no param attribute. This does not point to a NULL terminated string. The length of the string is given by the param_len field.

int khui_htwnd_link::param_len

Length of the string pointed to by param in characters. Undefined if param is NULL.

The documentation for this struct was generated from the following file:
  • khhtlink.h
Generated on Mon Oct 22 22:56:48 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Credentials acquisition

Credentials acquisition
[User Interface]

Detailed Description

Declarations associated with credentials acquisition.

Data Structures

struct | khui_new_creds
New credentials acquisition blob. More...
struct | khui_new_creds_by_type
A descriptor of a panel in the new credentials acquisition tab. More...
struct | khui_new_creds_prompt
A custom prompt. More...
struct | khui_control_row
Internal use. More...

Standard credtext link IDs

#define | CTLINKID_SWITCH_PANEL L"SwitchPanel"
Switch the panel.

Result values for khui_new_creds_t::result

#define | KHUI_NC_RESULT_PROCESS 0
#define | KHUI_NC_RESULT_CANCEL 1

Mode values for khui_new_creds_t::mode

#define | KHUI_NC_MODE_MINI 0
#define | KHUI_NC_MODE_EXPANDED 1

Response values for khui_new_creds_t::response

#define | KHUI_NC_RESPONSE_NONE 0
No known response.
#define | KHUI_NC_RESPONSE_EXIT 0
It is okay to exit the dialog now.
#define | KHUI_NC_RESPONSE_NOEXIT 0x00000002
It is NOT okay to exit the dialog now.
#define | KHUI_NC_RESPONSE_SUCCESS 0
The dialog was processed successfully.
#define | KHUI_NC_RESPONSE_FAILED 0x00000008
The processing of the dialog failed.
#define | KHUI_NC_RESPONSE_PENDING 0x00000010
Further interaction required.
#define | KHUI_NC_RESPONSE_COMPLETED 0x00000020
Completed.
#define | KHUI_NC_RESPONSE_PROCESSING 0x00010000
Processing.
#define | KHUI_NCMASK_RESPONSE (KHUI_NC_RESPONSE_EXIT|KHUI_NC_RESPONSE_NOEXIT)
#define | KHUI_NCMASK_RESULT (KHUI_NC_RESPONSE_SUCCESS|KHUI_NC_RESPONSE_FAILED|KHUI_NC_RESPONSE_PENDING)

Flags for khui_new_creds_by_type

Note that KHUI_NC_RESPONSE_SUCCESS, KHUI_NC_RESPONSE_FAILED, KHUI_NC_RESPONSE_PENDING are also stored in the flags.

#define | KHUI_NCT_FLAG_PROCESSED 1024
#define | KHUI_NCT_FLAG_DISABLED 2048

Defines

#define | KHUI_WM_NC_NOTIFY (WM_APP + 0x101)
Window message sent to credentials type panels.
#define | KHUI_CW_ID_MIN 8016
The first control ID that may be used by an identity provider.
#define | KHUI_CW_MAX_CTRLS 8
The maximum number of controls that may be created by an identity provider.
#define | KHUI_CW_ID_MAX (KHUI_CW_ID_MIN + KHUI_CW_MAX_CTRLS - 1)
The maximum control ID that may be used by an identity provider.
#define | WMNC_USER 2048
Plugins can use WMNC_NOTIFY message codes from here on up.
#define | KHUI_NC_MAGIC 0x84270427
#define | KHUI_MAX_TYPE_DEPS 8
Maximum number of dependencies for a credentials type.
#define | KHUI_MAX_NCTYPES 16
Maximum number of credential types for a new creds window.
#define | KHUI_MAXCCH_PASSWORD 512
Maximum number of characters in a password.
#define | KHUI_MAXCB_PASSWORD (KHUI_MAXCCH_PASSWORD * sizeof(wchar_t))
Maximum number of bytes in a password.
#define | KHUI_MAXCCH_BANNER 256
Maximum number of characters in a custom banner.
#define | KHUI_MAXCB_BANNER (KHUI_MAXCCH_BANNER * sizeof(wchar_t))
Maximum number of bytes in a custom banner.
#define | KHUI_MAXCCH_PNAME 256
Maximum number of characters in a panel name.
#define | KHUI_MAXCB_PNAME (KHUI_MAXCCH_PNAME * sizeof(wchar_t))
Maximum number of bytes in a panel name.
#define | NCDLG_WIDTH 300
Width of a new creds dialog panel in dialog units.
#define | NCDLG_HEIGHT 166
Height of a new creds dialog panel in dialog units.
#define | KHUI_NCPROMPT_FLAG_HIDDEN 1
The prompt input is hidden.
#define | KHUI_NCPROMPT_FLAG_STOCK 2
Internal use.
#define | KHUI_MAXCCH_PROMPT 256
Maximum number of characters in a prompt.
#define | KHUI_MAXCB_PROMPT (KHUI_MAXCCH_PROMPT * sizeof(wchar_t))
Maximum number of bytes in a prompt.
#define | KHUI_MAXCCH_PROMPT_VALUE 256
Maximum number of characters that can be entered in an input control.
#define | KHUI_MAXCB_PROMPT_VALUE (KHUI_MAXCCH_PROMPT_VALUE * sizeof(wchar_t))
Maximum number of bytes that can be entered in an input control.
#define | KHUI_NCPROMPT_TYPE_PASSWORD 1
A password control.
#define | KHUI_NCPROMPT_TYPE_NEW_PASSWORD 2
New password control.
#define | KHUI_NCPROMPT_TYPE_NEW_PASSWORD_AGAIN 3
New password again control.
#define | KHUI_NCPROMPT_TYPE_PREAUTH 4
Preauthentication (reserved).

Typedefs

typedef struct
tag_khui_new_creds_by_type 		khui_new_creds_by_type
typedef struct
tag_khui_new_creds_prompt 		khui_new_creds_prompt
typedef struct
tag_khui_new_creds 		khui_new_creds
typedef LRESULT(KHMAPI * | khui_ident_new_creds_cb )(khui_new_creds *nc, UINT cmd, HWND hwnd, UINT uMsg, WPARAM wParam, LPARAM lParam)
typedef enum
tag_khui_control_size 		khui_control_size
Control sizes.

Enumerations

enum khui_wm_nc_notifications {
WMNC_DIALOG_EXPAND = 1, WMNC_DIALOG_SETUP, WMNC_DIALOG_ACTIVATE, WMNC_DIALOG_MOVE,
WMNC_DIALOG_SWITCH_PANEL, WMNC_UPDATE_CREDTEXT, WMNC_CREDTEXT_LINK, WMNC_IDENTITY_CHANGE,
WMNC_CLEAR_PROMPTS, WMNC_SET_PROMPTS, WMNC_DIALOG_PREPROCESS, WMNC_DIALOG_PROCESS,
WMNC_DIALOG_PROCESS_COMPLETE, WMNC_TYPE_STATE, WMNC_ADD_CONTROL_ROW, WMNC_UPDATE_LAYOUT
}
Credentials dialog notifications. More...
enum | khui_wm_nc_ident_notify { WMNC_IDENT_INIT, WMNC_IDENT_WMSG, WMNC_IDENT_EXIT, WMNC_IDENT_PREPROCESS }
Notifications to the identity provider. More...
enum | tag_khui_control_size { KHUI_CTRLSIZE_SMALL, KHUI_CTRLSIZE_HALF, KHUI_CTRLSIZE_FULL }
Control sizes. More...

Functions

KHMEXP khm_int32 KHMAPI | khui_cw_create_cred_blob (khui_new_creds **c)
Create a khui_new_creds object.
KHMEXP khm_int32 KHMAPI | khui_cw_destroy_cred_blob (khui_new_creds *c)
Destroy a khui_new_creds object.
KHMEXP khm_int32 KHMAPI | khui_cw_lock_nc (khui_new_creds *c)
Lock the new_creds object.
KHMEXP khm_int32 KHMAPI | khui_cw_unlock_nc (khui_new_creds *c)
Unlock a new_creds object.
KHMEXP khm_int32 KHMAPI | khui_cw_add_type (khui_new_creds *c, khui_new_creds_by_type *t)
Add a new panel to a new credentials acquisition window.
KHMEXP khm_int32 KHMAPI | khui_cw_del_type (khui_new_creds *c, khm_int32 type)
Remove a panel from a new credentials acquisition window.
KHMEXP khm_int32 KHMAPI | khui_cw_find_type (khui_new_creds *c, khm_int32 type, khui_new_creds_by_type **t)
Find the panel belonging to a particular credentials type.
KHMEXP khm_int32 KHMAPI | khui_cw_enable_type (khui_new_creds *c, khm_int32 type, khm_boolean enable)
Enable/disable a particular credentials type.
KHMEXP khm_int32 KHMAPI | khui_cw_set_primary_id (khui_new_creds *c, khm_handle id)
Set the primary identity in a new credentials acuisition.
KHMEXP khm_int32 KHMAPI | khui_cw_add_identity (khui_new_creds *c, khm_handle id)
Add an additional identity to the new credentials acquisition.
KHMEXP khm_int32 KHMAPI | khui_cw_clear_prompts (khui_new_creds *c)
Clear all custom prompts.
KHMEXP khm_int32 KHMAPI | khui_cw_sync_prompt_values (khui_new_creds *c)
Synchronize custom prompt values.
KHMEXP khm_int32 KHMAPI | khui_cw_begin_custom_prompts (khui_new_creds *c, khm_size n_prompts, wchar_t *banner, wchar_t *name)
Begin custom prompting.
KHMEXP khm_int32 KHMAPI | khui_cw_add_prompt (khui_new_creds *c, khm_int32 type, wchar_t *prompt, wchar_t *def, khm_int32 flags)
Add a custom prompt.
KHMEXP khm_int32 KHMAPI | khui_cw_get_prompt (khui_new_creds *c, khm_size idx, khui_new_creds_prompt **prompt)
Retrieve a custom prompt.
KHMEXP khm_int32 KHMAPI | khui_cw_get_prompt_count (khui_new_creds *c, khm_size *np)
Get the number of custom prompts.
KHMEXP khm_int32 KHMAPI | khui_cw_get_prompt_value (khui_new_creds *c, khm_size idx, wchar_t *buf, khm_size *cbbuf)
Get the value of a custom prompt.
KHMEXP khm_int32 KHMAPI | khui_cw_set_response (khui_new_creds *c, khm_int32 type, khm_int32 response)
Set the response for a plugin.
KHMEXP khm_boolean KHMAPI | khui_cw_type_succeeded (khui_new_creds *c, khm_int32 type)
Check whether a specified credential type panel succeeded.
KHMEXP khm_int32 KHMAPI | khui_cw_add_control_row (khui_new_creds *c, HWND label, HWND input, khui_control_size size)
Add a row of controls to the identity specifier area.

Define Documentation

#define CTLINKID_SWITCH_PANEL L"SwitchPanel"

Switch the panel.

The id attribute of the link specifies the ordinal of the panel to switch to.

#define KHUI_MAXCB_BANNER (KHUI_MAXCCH_BANNER * sizeof(wchar_t))

Maximum number of bytes in a custom banner.

Length includes terminating NULL

#define KHUI_MAXCB_PASSWORD (KHUI_MAXCCH_PASSWORD * sizeof(wchar_t))

Maximum number of bytes in a password.

Includes terminating NULL

#define KHUI_MAXCB_PNAME (KHUI_MAXCCH_PNAME * sizeof(wchar_t))

Maximum number of bytes in a panel name.

Length includes terminating NULL

#define KHUI_MAXCB_PROMPT (KHUI_MAXCCH_PROMPT * sizeof(wchar_t))

Maximum number of bytes in a prompt.

Refers to the prompt text that accompanies an input control. THe length includes the terminating NULL.

#define KHUI_MAXCB_PROMPT_VALUE (KHUI_MAXCCH_PROMPT_VALUE * sizeof(wchar_t))

Maximum number of bytes that can be entered in an input control.

Refers to the input control of a prompt. The length includes the terminating NULL.

#define KHUI_MAXCCH_BANNER 256

Maximum number of characters in a custom banner.

Length includes terminating NULL

#define KHUI_MAXCCH_PASSWORD 512

Maximum number of characters in a password.

Length includes the termininating NULL

#define KHUI_MAXCCH_PNAME 256

Maximum number of characters in a panel name.

Length includes terminating NULL

#define KHUI_MAXCCH_PROMPT 256

Maximum number of characters in a prompt.

Refers to the prompt text that accompanies an input control. THe length includes the terminating NULL.

#define KHUI_MAXCCH_PROMPT_VALUE 256

Maximum number of characters that can be entered in an input control.

Refers to the input control of a prompt. The length includes the terminating NULL.

#define KHUI_NC_RESPONSE_COMPLETED 0x00000020

Completed.

This is automatically set if the plugin sets a response which does not indicate either KHUI_NC_RESPONSE_NOEXIT or KHUI_NC_RESPONSE_PENDING, which is considered to mean that the plugin is completed processing.

This flag cannot be explicitly specified in a response.

#define KHUI_NC_RESPONSE_EXIT 0

It is okay to exit the dialog now.

This is the default, which is why it has a value of zero. In order to prevent the dialog from exiting, set the KHUI_NC_RESPONSE_NOEXIT response bit.

#define KHUI_NC_RESPONSE_FAILED 0x00000008

The processing of the dialog failed.

Self explanatory. More information about the failure should have been reported using the khlog API, however, this response value indicates to other credential types that depend on this credential type that whatever it was that this credential type was supposed to do didn't happen.

#define KHUI_NC_RESPONSE_NOEXIT 0x00000002

It is NOT okay to exit the dialog now.

Used to indicate that further user-interaction is necessary to process the dialog. Usually this is accompanied by setting necessary custom prompts and notifications so the user knows why the dialog is prompting for more information.

#define KHUI_NC_RESPONSE_PENDING 0x00000010

Further interaction required.

Set along with KHUI_NC_RESPONSE_NOEXIT although it is not required. Setting this bit will automatically add the KHUI_NC_RESPONSE_NOEXIT.

If this bit is set, all dependent plugins will be set on hold until another round of processing clears the pending bit.

#define KHUI_NC_RESPONSE_PROCESSING 0x00010000

Processing.

This is an internal flag set while the credentials acquisition process is executing.

#define KHUI_NC_RESPONSE_SUCCESS 0

The dialog was processed successfully.

Since this is the default response, the value is zero. Use one of KHUI_NC_RESPONSE_FAILED or KHUI_NC_RESPONSE_PENDING to indicate an error or pending status.

#define KHUI_NCPROMPT_FLAG_HIDDEN 1

The prompt input is hidden.

The input is hidden for prompts which accept passwords. The control which represents the input will display an asterisk or a small circle corresponding to each character typed in, but will not show the actual character.

#define KHUI_NCPROMPT_TYPE_NEW_PASSWORD 2

New password control.

Used when changing the password

#define KHUI_NCPROMPT_TYPE_NEW_PASSWORD_AGAIN 3

New password again control.

Used when changing the password

#define KHUI_WM_NC_NOTIFY (WM_APP + 0x101)

Window message sent to credentials type panels.

This message is sent to the child windows.

The format of the message is :

  • uMsg : KHUI_WM_NC_NOTIFY
  • HIWORD(wParam) : one of khui_wm_nc_notifications
  • LPARAM : pointer to the khui_new_creds structure (except where noted)

#define WMNC_USER 2048

Plugins can use WMNC_NOTIFY message codes from here on up.

See also:
KHUI_WM_NC_NOTIFY

Enumeration Type Documentation

enum khui_wm_nc_ident_notify

Notifications to the identity provider.

These notifications are sent through to the identity provider's UI callback that was obtained using a KMSG_IDENT_GET_UI_CB message.

The callback routine is called from the context of the UI thread and is expected to not make any blocking calls. One of the following commands will be passed in as the cmd parameter to the callback.

Enumerator:
WMNC_IDENT_INIT | Initialize an identity selector for a new credentials dialog. The lParam parameter contains a handle to the dialog window which will contain the identity selector controls. The identity provider may make use of the ident_aux field of the khui_new_creds structure to hold any data pertaining to the credentials acquisition dialog.
WMNC_IDENT_WMSG | Windows message. Presumably sent from one of the controls that was created by the identity provider. The callback is expected to return TRUE if it processed the message or FALSE if it did not. The uMsg, wParam and lParam parameters are set to the values passed in by Windows.
WMNC_IDENT_EXIT | Terminate a credentials acquisition dialog. Sent just before the dialog is terminated.
WMNC_IDENT_PREPROCESS | The identity is about to be fetched from the khui_new_creds structure. The callback is expected to ensure that the primary identity listed in that structure is consistent with the user selection.

enum khui_wm_nc_notifications

Credentials dialog notifications.

These notifications will be sent to the individual dialog procedures of the credential type panels or to the new credentials window as a KHUI_WM_NC_NOTIFY message.

Enumerator:
WMNC_DIALOG_EXPAND The dialog is switching from basic to advanced mode or vice versa.

In expanded mode, all credentials type panels are visible as opposed to the compressed mode where they are not visible. The message is not sent to credentials type panels.

Only sent to the new credentials window.

WMNC_DIALOG_SETUP Sent to the new creds window to notify it that the dialog should create all the type configuration panels.

Until this message is issued, none of the credentials type panels exist. The credentials type panels will receive WM_INITDIALOG etc as per the normal dialog creation process.

Only sent to the new credentials window.

WMNC_DIALOG_ACTIVATE Sent to the new creds window to notify it that the dialog should do final initialization work and activate.

Only sent to the new credentials window.

WMNC_DIALOG_MOVE The new credentials window has moved.

This message is sent to all the credentials type panels when the new credentials window is being moved. It will be sent continuously if the user is dragging the window. Plug-ins rarely need to know their position on the screen. However, if there are any other windows that were created by the plug-in, such as floating controls or tooltips, they may need to be repositioned in response to this message.

Sent to all the credentials type panels.

WMNC_DIALOG_SWITCH_PANEL Sent to the new creds window to cause it to switch to the panel identified by LOWORD(wParam).

Does nothing if the specified panel is already the current panel. If the dialog is in compact mode and making the specified panel visible requires switching to expanded mode, the dialog will do so.

Only sent to the new credentials window.

WMNC_UPDATE_CREDTEXT Update the credentials text associated with a panel.

During the new credentials operation, each plug-in is expected to maintain a textual representation of the credentials that the plug-in expects to obtain for the selected identity. It can, alternatively, be used to indicate the state of the credentials type in respect to the selected identity (for example, whether the credentials type is disabled for the identity and why).

This text is not visible when the new credentials window is in basic mode, but it is visible when the window is in advanced mode. The following image shows the expanded new credentials window including the credentials text from a several plug-ins:

Once this message is received, each plug-in should construct its credentials text string and store it in the credtext member of its khui_new_creds_by_type structure as shown in the sample code below:

      // Handler for window message WM_NC_NOTIFY with
      // HWND hwnd, WPARAM wParam and LPARAM lParam

      // This structure holds the dialog data for the panel.  We
      // assume it has 'nc' and 'nct' fields that point to the
      // khui_new_creds and khui_new_creds_by_type structures
      // respectively.

      ...
      struct nc_dialog_data * d;
      ...

      // Retrieve the data structure from the dialog user data.
      d = (struct nc_dialog_data *) GetWindowLongPtr(hwnd, DWLP_USER);

      switch (HIWORD(wParam)) {
      case WMNC_UPDATE_CREDTEXT:
        {
          wchar_t buffer[KHUI_MAXCCH_LONG_DESC];
          size_t cb_size;

          // we are being requested to update the credentials text. We
          // already allocated a buffer when we created the nct
          // structure.  So we can just set the text here.

          // The credentials text should reflect the credentials that
          // will be obtained when the new credentials operation
          // completes.

          assert(d && d->nc && d->nct);

          if (d->nct->credtext) {
              free(d->nct->credtext);
              d->nct->credtext = NULL;
          }

          // We only display something if there is a selected identity
          if (d->nc->n_identities > 0) {
            StringCbPrintf(buffer, sizeof(buffer),
                           L"<p>My Credentials<tab>: %s</p>",
                           get_credential_name(d));
            StringCbLength(buffer, sizeof(buffer), &cb_size);
            cb_size += sizeof(wchar_t); // account for the terminating NULL

            d->nct->credtext = malloc(cb_size);
            if (d->nct->credtext) {
               StringCbCopy(d->nct->credtext, cb_size, buffer);
            }
          }

          break;
        }

      ... // Handler other notifications
      }

The text that is specified as the credentials text is formatted hypertext. For more information about support for formatting and hypertext and handling hyperlinks, see khui_htwnd.

Note:
When this message is sent to the new credentials window, the application will send the WMNC_UPDATE_CREDTEXT message to all the credential type panels and update the credential text window.
WMNC_CREDTEXT_LINK A hyperlink was activated.

Sent to a panel dialog procedure when a user clicks an embedded link in the credentials text that belongs to that panel. The lParam parameter of the message is a pointer to a khui_htwnd_link structure describing the link.

See also:
khui_htwnd
Note:
The lParam parameter does not point to a khui_new_creds structure for this message.
WMNC_IDENTITY_CHANGE The primary identity has changed.

The khui_new_creds structure contains a list of identities to which the current operation should be applied. In its current implementation, only the first identity in this list is used. Therefore, the list will contain at most one identity. It is possible for the list to be empty (for example, if the user hasn't selected an identity yet).

When handling this notification, the plug-in should check the n_identities member of the khui_new_creds structure to see whether there are any identities selected. This value would be either zero or one. If it is non-zero, then a handle to the selected identity will be in khui_new_creds::identities[0].

Plug-ins typically use this notfication to load identity specific settings when a new identity is selected.

This notification is sent to all the credentials type panels.

WMNC_CLEAR_PROMPTS Sent to the new creds window to clear any custom prompts.

Only sent to the new credentials window.

WMNC_SET_PROMPTS Sent to the new creds window to set custom prompts.

Only sent to the new credentials window.

WMNC_DIALOG_PREPROCESS The credentials acquisition process is about to start.

Sent to all the credentials type panels to notify them that the credentials acquisition process will start. Once all plug-ins have handled the notification, the application will start sending out <KMSG_CRED, KMSG_CRED_PROCESS> messages to the credentials providers which are participating in the new credentials operation.

WMNC_DIALOG_PROCESS | This notification is no longer used.
WMNC_DIALOG_PROCESS_COMPLETE | Sent to the new creds window to indicate that the all the threads have completed processing.
WMNC_TYPE_STATE | Sent to the new creds window as notification that a particular credentials type has changed state from enabled to disabled or vice versa. The LPARAM member of the message specifies the credentials type identifier for the changed type
WMNC_ADD_CONTROL_ROW | Add a row of controls to a new cred dialog. This is an internal message.
WMNC_UPDATE_LAYOUT | Update the layout of a dialog or window. This is an internal message.

enum tag_khui_control_size

Control sizes.

Enumerator:
KHUI_CTRLSIZE_SMALL | A small control fits in about 1/5 the width of the new credentials panel
KHUI_CTRLSIZE_HALF | Half size controls fit in 1/2 the width of the new credentials panel
KHUI_CTRLSIZE_FULL | Takes up the whole width of the crednetials panel

Function Documentation

KHMEXP khm_int32 KHMAPI khui_cw_add_control_row | ( | khui_new_creds * | c,
 |  | HWND | label,
 |  | HWND | input,
 |  | khui_control_size | size
 | ) |  |

Add a row of controls to the identity specifier area.

Only for use by identity provider callbacks that wish to add an identity selector control. A row of controls consist of a label control and some input control.

When the WMNC_IDENT_INIT message is sent to the identity provider, it receives a handle to the dialog panel in the lParam parameter which should be the parent window of both the windows specified here. The control ID for any controls created must fall within the KHUI_CW_ID_MIN and KHUI_CW_ID_MAX range.

Both controls will be resized to fit in the row.

If long_label is TRUE then the size of the label will be larger than normal and will accomodate more text.

KHMEXP khm_int32 KHMAPI khui_cw_add_identity | ( | khui_new_creds * | c,
 |  | khm_handle | id
 | ) |  |

Add an additional identity to the new credentials acquisition.

Individual plugins are free to decide how to handle additional identities. Generally, they would attempt to obtain credentials for the primary and additional identities, but would not consider it an error if an additional identity failed to obtain credentials.

Calling this function with id of NULL does nothing.

KHMEXP khm_int32 KHMAPI khui_cw_add_prompt | ( | khui_new_creds * | c,
 |  | khm_int32 | type,
 |  | wchar_t * | prompt,
 |  | wchar_t * | def,
 |  | khm_int32 | flags
 | ) |  |

Add a custom prompt.

After khui_cw_begin_custom_prompts() is called, the plugin should call khui_cw_add_prompt() to add the actual prompts. The number of prompts that can be added is the n_prompts value specified in the earlier call to khui_cw_begin_custom_prompts().

Once n_prompts prompts have been added, the new prompts will automatically be created and shown in the user interface. However, if less than that prompts are added, nothing is displayed to the user.

Parameters:
[in] | c | Pointer to khui_new_creds structure
[in] | type | Type of prompt. One of KHUI_NCPROMPT_TYPE_PREAUTH, KHUI_NCPROMPT_TYPE_PASSWORD, KHUI_NCPROMPT_TYPE_NEW_PASSWORD, KHUI_NCPROMPT_TYPE_NEW_PASSWORD_AGAIN
[in] | prompt | Text of the prompt. Constrained by KHUI_MAXCCH_PROMPT. (Localized, required)
[in] | def | Default value. (optional). Constrained by KHUI_MAXCCH_PROMPT_VALUE. Set to NULL if not provided.
[in] | flags | Flags. Combination of KHUI_NCPROMPT_FLAG_HIDDEN

KHMEXP khm_int32 KHMAPI khui_cw_add_type | ( | khui_new_creds * | c,
 |  | khui_new_creds_by_type * | t
 | ) |  |

Add a new panel to a new credentials acquisition window.

See the description of khui_new_cred_panel for information on how to populate it to describe a credentials type panel.

Note that the structure pointed to by t is added by reference. The memory pointed to by t is not copied. Hence, the block of memory and any other blocks pointed to by the khui_new_creds_by_type structure located there should remain intact for the lifetime of the khui_new_creds structure pointed to by c or until the credentials type panel is removed from the khui_new_creds structure with a call to khui_cw_del_type().

Generally, a plug-in that calls this function should allocate a block of memory to contain the khui_new_creds_by_type structure, fill it in and then pass in the address in a call to khui_cw_add_type() while handling a KMSG_CRED_PASSWORD, KMSG_CRED_NEW_CREDS or KMSG_CRED_RENEW_CREDS message. Then the plug-in should remove the reference with a call to khui_cw_del_type() while processing KMSG_CRED_END.

See also:
khui_cw_del_type()

Specifying the credentials type panel

khui_new_cred_panel

khui_new_creds

KHMEXP khm_int32 KHMAPI khui_cw_begin_custom_prompts | ( | khui_new_creds * | c,
 |  | khm_size | n_prompts,
 |  | wchar_t * | banner,
 |  | wchar_t * | name
 | ) |  |

Begin custom prompting.

Begins the process of defining custom prompts. Implicity removes all the custom prompts that are currently being displayed. The banner and name will be displayed in separate controls above the set of new custom prompts.

The controls associated with the prompts will not actually be created until all the prompts have been added using khui_cw_add_prompt(). The number of promtps that can be added will be exactly n_prompts.

KHMEXP khm_int32 KHMAPI khui_cw_clear_prompts ( khui_new_creds * c )

Clear all custom prompts.

Removes all the custom prompts from the new credentials dialog.

KHMEXP khm_int32 KHMAPI khui_cw_create_cred_blob ( khui_new_creds ** c )

Create a khui_new_creds object.

Creates and initializes a khui_new_creds object. The created object must be destroyed using the khui_cw_destroy_cred_blob() function.

Note:
Plugins should not call this function directly. The necessary khui_new_creds objects will be created by NetIDMgr.
See also:
khui_cw_destroy_cred_blob()

KHMEXP khm_int32 KHMAPI khui_cw_del_type | ( | khui_new_creds * | c,
 |  | khm_int32 | type
 | ) |  |

Remove a panel from a new credentials acquisition window.

See also:
khui_cw_add_type()

KHMEXP khm_int32 KHMAPI khui_cw_destroy_cred_blob ( khui_new_creds * c )

Destroy a khui_new_creds object.

Destroys a khui_new_creds object that was fomerly created using a call to khui_cw_create_cred_blob().

Note:
Plugins should not call this function directly. The necessary khui_new_creds objects will be created by NetIDMgr.
See also:
khui_cw_create_cred_blob()

KHMEXP khm_int32 KHMAPI khui_cw_enable_type | ( | khui_new_creds * | c,
 |  | khm_int32 | type,
 |  | khm_boolean | enable
 | ) |  |

Enable/disable a particular credentials type.

Enables or disables the panel associated with a particular credentials type. Does not preclude the credentials type from participating in the new credentials acquisition. However, the user will be prevented from interacting with the specific panel.

KHMEXP khm_int32 KHMAPI khui_cw_find_type | ( | khui_new_creds * | c,
 |  | khm_int32 | type,
 |  | khui_new_creds_by_type ** | t
 | ) |  |

Find the panel belonging to a particular credentials type.

This panel would have been added to the new credentials window using khui_cw_add_type().

See also:
khui_cw_add_type()

KHMEXP khm_int32 KHMAPI khui_cw_get_prompt | ( | khui_new_creds * | c,
 |  | khm_size | idx,
 |  | khui_new_creds_prompt ** | prompt
 | ) |  |

Retrieve a custom prompt.

Retrieves an individual prompt. The idx parameter is a zero-based index of the prompt to retrieve. The ordering is the same as the order in which khui_cw_add_prompt() was called.

KHMEXP khm_int32 KHMAPI khui_cw_get_prompt_count | ( | khui_new_creds * | c,
 |  | khm_size * | np
 | ) |  |

Get the number of custom prompts.

Retrieves the number of custom prompts currently displayed. If this function is called between calling khui_cw_begin_custom_prompts() and adding all the prompts, the number returned will be the number of prompts that is expected to be registered (i.e. the n_prompts parameter passed to khui_cw_begin_custom_prompts()).

KHMEXP khm_int32 KHMAPI khui_cw_get_prompt_value | ( | khui_new_creds * | c,
 |  | khm_size | idx,
 |  | wchar_t * | buf,
 |  | khm_size * | cbbuf
 | ) |  |

Get the value of a custom prompt.

Retrieve the value of a specific prompt. The value is the string that was typed into the input control associated with a custom prompt. The idx parameter is the zero-based index of the prompt from which to retrieve the value from. The ordering is the same as the order in which khui_cw_add_prompt() was called.

It is important to call khui_cw_sync_prompt_values() before starting to call khui_cw_get_prompt_value() so that the values returned are up-to-date.

KHMEXP khm_int32 KHMAPI khui_cw_lock_nc ( khui_new_creds * c )

Lock the new_creds object.

When a plugin is accessing the fields of a khui_new_creds object, it must first obtain a lock on the object so that other threads will not modify the fields at the same time. Locking the object ensures that the fields of the object will be consistent.

Use khui_cw_unlock_nc() to undo the lock obtained through a call to khui_cw_lock_nc().

It is not necessary to lock a new credentials object when modifying it using the NetIDMgr API.

KHMEXP khm_int32 KHMAPI khui_cw_set_primary_id | ( | khui_new_creds * | c,
 |  | khm_handle | id
 | ) |  |

Set the primary identity in a new credentials acuisition.

The primary identity dictates many of the defaults and the semantics associated with the credentials acquision process. Setting the primary identity also triggers the WMNC_IDENTITY_CHANGE notification which will be sent to all the credentials type panels.

Has no effect if the primary identity is already the same as the one specified in id. Specify NULL for id if the current primary identity is to be cleared.

If the primary identity is changed, then all the additional identities associated with the new credentials acquisition dialog will also be discarded.

KHMEXP khm_int32 KHMAPI khui_cw_set_response | ( | khui_new_creds * | c,
 |  | khm_int32 | type,
 |  | khm_int32 | response
 | ) |  |

Set the response for a plugin.

When handling KMSG_CRED_DIALOG_PROCESS from within the plugin thread, it is important to set the response by calling this function. The response can be used to signal whether the plugin successfully obtained credentials or whether further interaction is required, or the credentials acquisition failed.

The response is a combination of :

  • KHUI_NC_RESPONSE_PENDING
  • KHUI_NC_RESPONSE_FAILED
  • KHUI_NC_RESPONSE_PENDING
  • KHUI_NC_RESPONSE_SUCCESS
  • KHUI_NC_RESPONSE_NOEXIT
  • KHUI_NC_RESPONSE_EXIT

KHMEXP khm_int32 KHMAPI khui_cw_sync_prompt_values ( khui_new_creds * c )

Synchronize custom prompt values.

It is important to synchronize the values before accessing their values. The controls associated with custom prompts update the values in the khui_new_creds object periodically. However, the values may lose sync intermittently.

KHMEXP khm_boolean KHMAPI khui_cw_type_succeeded | ( | khui_new_creds * | c,
 |  | khm_int32 | type
 | ) |  |

Check whether a specified credential type panel succeeded.

This is called during the processing of KMSG_CRED_DIALOG_PROCESS to determine whether a specified credential type succeeded in obtaining credentials. The credential type that is being queried should have also been listed as a dependency when adding the current credentials type, otherwise the type queried may not have been invoked yet.

Returns:
TRUE iff the queried type has reported that it successfully completed the credentials acquision operation.

KHMEXP khm_int32 KHMAPI khui_cw_unlock_nc ( khui_new_creds * c )

Unlock a new_creds object.

See also:
khui_cw_lock_nc()

Generated on Mon Oct 22 22:56:46 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: khui_new_creds Struct Reference

khui_new_creds Struct Reference
[Credentials acquisition]

#include <khnewcred.h>

Detailed Description

New credentials acquisition blob.

A pointer to an object of this type is passed in along with the credentials acquisition messages.

See also:
Managed credential acquisition for more information

Data Fields

khm_int32 magic
khm_int32 subtype
CRITICAL_SECTION | cs
khm_boolean set_default
khm_handle * identities
khm_size n_identities
khm_size nc_identities
khui_action_context ctx
khm_int32 mode
HWND | hwnd
struct
tag_khui_new_creds_by_type ** 		types
khm_handle * type_subs
khm_size n_types
khm_size nc_types
khm_int32 result
khm_int32 response
wchar_t * | password
wchar_t * | banner
wchar_t * | pname
khm_size n_prompts
khm_size nc_prompts
struct
tag_khui_new_creds_prompt ** 		prompts
khui_ident_new_creds_cb | ident_cb
wchar_t * | window_title
LPARAM | ident_aux

Field Documentation

khm_int32 khui_new_creds::magic

Internal use

khm_int32 khui_new_creds::subtype

Subtype of the request that is being handled through this object. One of KMSG_CRED_NEW_CREDS, KMSG_CRED_RENEW_CREDS or KMSG_CRED_PASSWORD

CRITICAL_SECTION khui_new_creds::cs

Internal use

khm_boolean khui_new_creds::set_default

After a successfull credentials acquisition, set the primary identity as the default.

khm_handle* khui_new_creds::identities

The list of identities associated with this request. The first identity in this list (identities[0]) is the primary identity.

khm_size khui_new_creds::n_identities

Number of identities in the list identities

khm_size khui_new_creds::nc_identities

Internal use

khui_action_context khui_new_creds::ctx

An action context specifying the context in which the credentials acquisition operation was launced.

khm_int32 khui_new_creds::mode

The mode of the user interface. One of KHUI_NC_MODE_MINI or KHUI_NC_MODE_EXPANDED.

HWND khui_new_creds::hwnd

Handle to the new credentials window.

struct tag_khui_new_creds_by_type** khui_new_creds::types [read]

Internal use

khm_handle* khui_new_creds::type_subs

Internal use

khm_size khui_new_creds::n_types

Internal use

khm_size khui_new_creds::nc_types

Internal use

khm_int32 khui_new_creds::result

One of KHUI_NC_RESULT_CANCEL or KHUI_NC_RESULT_PROCESS indicating the result of the dialog with the user

khm_int32 khui_new_creds::response

Response. See individual message documentation for info on what to do with this field

wchar_t* khui_new_creds::password

Not used.

wchar_t* khui_new_creds::banner

Internal use

wchar_t* khui_new_creds::pname

Internal use

khm_size khui_new_creds::n_prompts

Internal use

khm_size khui_new_creds::nc_prompts

Internal use

struct tag_khui_new_creds_prompt** khui_new_creds::prompts [read]

Internal use

khui_ident_new_creds_cb khui_new_creds::ident_cb

Internal use

wchar_t* khui_new_creds::window_title

Internal use

LPARAM khui_new_creds::ident_aux

Auxilliary field which is reserved for use by the identity provider during the course of conducting this dialog.

The documentation for this struct was generated from the following file:
  • khnewcred.h
Generated on Mon Oct 22 22:56:48 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: khui_new_creds_by_type Struct Reference

khui_new_creds_by_type Struct Reference
[Credentials acquisition]

#include <khnewcred.h>

Detailed Description

A descriptor of a panel in the new credentials acquisition tab.

When processing certain credentials messages such as KMSG_CRED_PASSWORD, KMSG_CRED_NEW_CREDS, KMSG_CRED_RENEW_CREDS, a pointer to a khui_new_creds structure will be passed in to the message handler. If the handler of the message needs to add one or more credentials types as participants of the operation, the handler will need to call khui_cw_add_type() and specify a khui_new_creds_by_type structure.

Note that the memory address passed in to the call to khui_cw_add_type() will not be copied. Therefore, the block of memory should remain as-is for the lifetime of the khui_new_creds structure or until it is removed with a call to khui_cw_del_type().

Some of the credentials messages that require specifying a khui_new_creds_by_type structure require providing a user-interface. In these cases, the fields marked for providing a UI may be required to hold valid values. If the message does not require providing a UI, these fields will be ignored.

Data Fields

khui_new_creds * nc
khm_int32 flags
khm_int32 type
khm_int32 | type_deps [KHUI_MAX_TYPE_DEPS]
khm_size n_type_deps
khm_size ordinal
wchar_t * | name
HICON | icon
wchar_t * | tooltip
HMODULE | h_module
LPWSTR | dlg_template
DLGPROC | dlg_proc
HWND | hwnd_panel
HWND | hwnd_tc
wchar_t * | credtext
LPARAM | aux

Field Documentation

khui_new_creds* khui_new_creds_by_type::nc

Internal use. Do not set

khm_int32 khui_new_creds_by_type::flags

Internal use. Do not set

khm_int32 khui_new_creds_by_type::type

The identifier of the credentials type. This is a credentials type identifier allocated with a call to kcdb_credtype_register().

khm_int32 khui_new_creds_by_type::type_deps[KHUI_MAX_TYPE_DEPS]

credentials types that this credential type depends on. Each element defines a credentials type identifier that this type depends on for this operation. The number of valid values in this array should be specified in the n_type_deps field.

khm_size khui_new_creds_by_type::n_type_deps

Number of dependencies listed above. Should be between 0 and KHUI_MAX_TYPE_DEPS. Specify 0 if there are no dependencies.

khm_size khui_new_creds_by_type::ordinal

The requested ordinal. The UI would attempt to place this panel at the reqested order in the list of panels. Set to -1 if the order does not matter. Once the dialog is activated this field will be updated to reflect the actual ordinal of the panel.

wchar_t* khui_new_creds_by_type::name

Name of the panel (localized, optional). If NULL, the localized name of the credentials type is used. Only used if providing a user-interface.

HICON khui_new_creds_by_type::icon

Icon for the panel (optional). Only used if providing a user-interface.

wchar_t* khui_new_creds_by_type::tooltip

Tooltip for the panel (localized, optional). If NULL, no tooltip will be assigned for the panel. Only used if providing a user-interface.

HMODULE khui_new_creds_by_type::h_module

Handle to the module containing the dialog resource. Only used if providing a user-interface.

LPWSTR khui_new_creds_by_type::dlg_template

The dialog resource. Only used if providing a user-interface.

DLGPROC khui_new_creds_by_type::dlg_proc

The dialog procedure. Only used if providing a user-interface.

HWND khui_new_creds_by_type::hwnd_panel

The dialog window. Once the dialog panel is created, a handle to the panel will be assigned here. Note that the handle is assigned after a successful call to CreateDialogParam and hence would not be available when handling the WM_INITDIALOG message from the dialog procedure. Only used of providing a user-interface.

HWND khui_new_creds_by_type::hwnd_tc

Internal use. Do not set

wchar_t* khui_new_creds_by_type::credtext

A brief description of the current state of this cred type. (localized, optional). Only used if providing a user-interface. If this field is non-NULL, then it should point to a NULL terminated string that does not exceed KHUI_MAXCCH_LONG_DESC characters in length including the terminating NULL.

See also:
khui_htwnd for information on how to format the string for this field.

LPARAM khui_new_creds_by_type::aux

auxilliary field. For use by the plug-in.

The documentation for this struct was generated from the following file:
  • khnewcred.h
Generated on Mon Oct 22 22:56:48 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: khui_new_creds_prompt Struct Reference

khui_new_creds_prompt Struct Reference
[Credentials acquisition]

#include <khnewcred.h>

Detailed Description

A custom prompt.

Data Fields

khm_size index
khm_int32 type
wchar_t * | prompt
wchar_t * | def
wchar_t * | value
khm_int32 flags
HWND | hwnd_static
HWND | hwnd_edit

Field Documentation

khm_size khui_new_creds_prompt::index

Set to the zero based index of this prompt.

khm_int32 khui_new_creds_prompt::type

one of KHUI_NCPROMPT_TYPE_*

wchar_t* khui_new_creds_prompt::prompt

prompt string. Cannot exceed KHUI_MAXCCH_PROMPT

wchar_t* khui_new_creds_prompt::def

default value. Cannot exceed KHUI_MAXCCH_PROMPT_VALUE

wchar_t* khui_new_creds_prompt::value

On completion, this is set to the value that the user entered. Will not exceed KHUI_MAXCCH_PROMPT_VALUE

khm_int32 khui_new_creds_prompt::flags

Combination of KHUI_NCPROMPT_FLAG_*

The documentation for this struct was generated from the following file:
  • khnewcred.h
Generated on Mon Oct 22 22:56:48 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: khui_control_row Struct Reference

khui_control_row Struct Reference
[Credentials acquisition]

#include <khnewcred.h>

Detailed Description

Internal use.

Data Fields

HWND | label
HWND | input
khui_control_size | size
The documentation for this struct was generated from the following file:
  • khnewcred.h
Generated on Mon Oct 22 22:56:48 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Property sheets

Property sheets
[User Interface]

Data Structures

struct | khui_property_sheet
A property sheet. More...
struct | khui_property_page
A property sheet page. More...

Defines

#define | KHUI_PS_STATUS_NONE 0
The property sheet hasn't been created yet.
#define | KHUI_PS_STATUS_RUNNING 1
The property sheet is visible and running.
#define | KHUI_PS_STATUS_DONE 2
The property sheet has completed running.
#define | KHUI_PS_STATUS_DESTROY 3
The property sheet is in the process of being destroyed.
#define | KHUI_PS_MAX_PSP 16
Maximum number of property sheet pages in a property sheet.
#define | KHUI_PPCT_IDENTITY (-8)
Special pseudo credtype for identity page.
#define | KHUI_PPCT_CREDENTIAL (-9)
Special pseudo credtype for credential page.

Functions

KHMEXP khm_int32 KHMAPI | khui_ps_create_sheet (khui_property_sheet **sheet)
Create a property sheet.
KHMEXP khm_int32 KHMAPI | khui_ps_add_page (khui_property_sheet *sheet, khm_int32 credtype, khm_int32 ordinal, LPPROPSHEETPAGE ppage, khui_property_page **page)
Add a page to a property sheet.
KHMEXP khm_int32 KHMAPI | khui_ps_find_page (khui_property_sheet *sheet, khm_int32 credtype, khui_property_page **page)
Retrieve a property page structure from a property sheet.
KHMEXP HWND KHMAPI | khui_ps_show_sheet (HWND parent, khui_property_sheet *sheet)
Display the property sheet.
KHMEXP LRESULT KHMAPI | khui_ps_check_message (khui_property_sheet *sheet, PMSG msg)
Check if the given message belongs to the property sheet.
KHMEXP khm_int32 KHMAPI | khui_ps_destroy_sheet (khui_property_sheet *sheet)
Destroy a property sheet and all associated data structures.
KHMEXP khm_int32 KHMAPI | khui_property_wnd_set_record (HWND hwnd_pwnd, khm_handle record)

Define Documentation

#define KHUI_PS_STATUS_DONE 2

The property sheet has completed running.

At this point, it is safe to call khui_ps_destroy_sheet() to destroy the property sheet.

Function Documentation

KHMEXP khm_int32 KHMAPI khui_ps_add_page | ( | khui_property_sheet * | sheet,
 |  | khm_int32 | credtype,
 |  | khm_int32 | ordinal,
 |  | LPPROPSHEETPAGE | ppage,
 |  | khui_property_page ** | page
 | ) |  |

Add a page to a property sheet.

Called by a plugin or the NetIDMgr application to add a page to a property sheet.

Pages can only be added before the property sheet is made visible to the user.

Parameters:
[in] | sheet | The property sheet to add the page to
[in] | credtype | The credentials type ID of the owner of the property page. This should be set to KCDB_CREDTYPE_INVALID if the type is not relevant.
[in] | ordinal | Requested ordinal. A positive integer which is used to order the pages in a property sheet. The pages are ordered based on ordinal first and then alphabetically by credentials type name. If the type is unavailable, then the ordering is undefined. Ordinals for credential type property pages can be in the range from 0 to 127. Ordinals 128 and above are reserved. Passing in 0 will work for credentials providers unless they provide more than one property page per credential, in which case the ordinal should be used to enforce an order.
[in] | ppage | Pointer to structure that will be passed to CreatePropertySheetPage() to create the property page. The structure is not managed by NetIDMgr at all, and must exist until the status of the property sheet changes to KHUI_PS_STATUS_RUNNING. The same pointer will be found in the p_page member of the khui_property_page structure.
[out] | page | A pointer will be returned here that will point to the newly created khui_property_page structure. Specify NULL if this value is not required. You can use khui_ps_find_page() to retrieve a pointer to the structure later.

KHMEXP LRESULT KHMAPI khui_ps_check_message | ( | khui_property_sheet * | sheet,
 |  | PMSG | msg
 | ) |  |

Check if the given message belongs to the property sheet.

Note:
Only called by the NetIDMgr application

KHMEXP khm_int32 KHMAPI khui_ps_create_sheet ( khui_property_sheet ** sheet )

Create a property sheet.

Note:
Only called by the NetIDMgr application.

KHMEXP khm_int32 KHMAPI khui_ps_destroy_sheet ( khui_property_sheet * sheet )

Destroy a property sheet and all associated data structures.

Note:
Only called by the NetIDMgr application.

KHMEXP HWND KHMAPI khui_ps_show_sheet | ( | HWND | parent,
 |  | khui_property_sheet * | sheet
 | ) |  |

Display the property sheet.

Note:
Only called by the NetIDMgr application

Generated on Mon Oct 22 22:56:46 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: khui_property_sheet Struct Reference

khui_property_sheet Struct Reference
[Property sheets]

#include <khprops.h>

Detailed Description

A property sheet.

Public Member Functions

QDCL (struct tag_khui_property_page)

Data Fields

PROPSHEETHEADER | header
khm_int32 status
HWND | hwnd
HWND | hwnd_page
khui_action_context ctx
khm_handle identity
khm_int32 credtype
khm_handle cred
khm_int32 n_pages

Field Documentation

PROPSHEETHEADER khui_property_sheet::header

property sheet header

khm_int32 khui_property_sheet::status

status of property sheet. One of KHUI_PS_STATUS_NONE, KHUI_PS_STATUS_RUNNING or KHUI_PS_STATUS_DONE

HWND khui_property_sheet::hwnd

handle to the property sheet window. Only valid when status is NOT KHUI_PS_STATUS_NONE

HWND khui_property_sheet::hwnd_page

handle to the current page in the property sheet. Only valid when status is KHUI_PS_STATUS_RUNNING

khui_action_context khui_property_sheet::ctx

Context for the property sheet. See documentation for khui_action_context

khm_handle khui_property_sheet::identity

Handle to the associated identity, if applicable

khm_int32 khui_property_sheet::credtype

Type ID of the credentials type, if applicable

khm_handle khui_property_sheet::cred

Handle to the associated credential, if applicable

khm_int32 khui_property_sheet::n_pages

Number of property pages. Upperbound of KHUI_PS_MAX_PSP

The documentation for this struct was generated from the following file:
  • khprops.h
Generated on Mon Oct 22 22:56:48 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: khui_property_page Struct Reference

khui_property_page Struct Reference
[Property sheets]

#include <khprops.h>

Detailed Description

A property sheet page.

Public Member Functions

LDCL (struct tag_khui_property_page)

Data Fields

HPROPSHEETPAGE | h_page
LPPROPSHEETPAGE | p_page
HWND | hwnd
khm_int32 | credtype
khm_int32 | ordinal
The documentation for this struct was generated from the following file:
  • khprops.h
Generated on Mon Oct 22 22:56:48 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Connecting to NetIDMgr from another process

Connecting to NetIDMgr from another process
[User Interface]

Data Structures

struct | NETID_DLGINFO

Defines

#define | ID_OBTAIN_TGT_WITH_LPARAM 32810
#define | KHUI_REQDAEMONWND_CLASS L"IDMgrRequestDaemonCls"
#define | KHUI_REQDAEMONWND_NAME L"IDMgrRequestDaemon"
#define | KHUI_REQD_MAPPING_FORMAT L"Local\\NetIDMgr_DlgInfo_%lu"
#define | NETID_USERNAME_SZ 128
#define | NETID_REALM_SZ 192
#define | NETID_TITLE_SZ 256
#define | NETID_CCACHE_NAME_SZ 264
#define | NETID_DLGTYPE_TGT 0
#define | NETID_DLGTYPE_CHPASSWD 1
#define | NETID_DLGINFO_V1_SZ

Typedefs

typedef struct
NETID_DLGINFO * 		LPNETID_DLGINFO

Define Documentation

#define NETID_DLGINFO_V1_SZ

Value:

(10 * sizeof(DWORD) \
         + sizeof(WCHAR) * (NETID_TITLE_SZ + \
         2 * NETID_USERNAME_SZ + 2 * NETID_REALM_SZ + \
         2 * NETID_CCACHE_NAME_SZ))

Generated on Mon Oct 22 22:56:46 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Duration sliders

Duration sliders
[User Interface]

Detailed Description

The duration sliders in the UI are pseudo-log-scaled. This is based on the assumption that people don't really need 1 minute accuracy when setting a duration that's several hours long. As a result, it is easier to hone in on the duration that you want without having wizardly mouse maneuvering skillz.

Following are the duration ranges and the granularity that is offered in each range:

Range | Increment
0..5m | 1 min
5m..1hr | 5 min
1hr..4hr | 15 min
4hr..10hr | 30 min
10hr..24hr | 1 hr
24hr..4d | 6 hr
4d.. | 1 day

We don't really adjust for durations over 4 days. The ranges we are concerned with don't get much larger.

For the purpose of writing this piece of code, I have chosen the term "tick" to refer to a period of granularity. The number of periods of granularity (inclusive) within a certain duration interval is referred to as the number of ticks in the interval. For example, there are 4 ticks between the interval of 3 minutes to 10 minutes. Each occuring at the start of 3min, 4, 5 and 10mins. And thusly the slider control will display 4 ticks if it is displaying the interval 3-10mins.

Data Structures

struct | khui_tracker
Tracker data. More...

Functions

KHMEXP void KHMAPI | khui_tracker_install (HWND hwnd_edit, khui_tracker *tc)
Install a tracker into an edit control.
KHMEXP void KHMAPI | khui_tracker_reposition (khui_tracker *tc)
KHMEXP void KHMAPI | khui_tracker_initialize (khui_tracker *tc)
KHMEXP void KHMAPI | khui_tracker_refresh (khui_tracker *tc)
KHMEXP void KHMAPI | khui_tracker_kill_controls (khui_tracker *tc)

Function Documentation

KHMEXP void KHMAPI khui_tracker_install | ( | HWND | hwnd_edit,
 |  | khui_tracker * | tc
 | ) |  |

Install a tracker into an edit control.

Once installed, the edit control becomes a duration editor. The tracker data structure that is supplied should remain as is for the lifetime of the edit control.

The tracker strucutre should have been initialized with a call to khui_tracker_initialize() and should have valid values in the min, max and current fields.

Generated on Mon Oct 22 22:56:46 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: khui_tracker Struct Reference

khui_tracker Struct Reference
[Duration sliders]

#include <khtracker.h>

Detailed Description

Tracker data.

Data Fields

WNDPROC | fn_edit
WNDPROC | fn_tracker
HWND | hw_slider
HWND | hw_edit
int | lbl_y
int | lbl_lx
int | lbl_rx
DWORD | act_time
time_t | current
time_t | min
time_t | max

Field Documentation

time_t khui_tracker::current

Current selection

time_t khui_tracker::min

Minimum (inclusive)

time_t khui_tracker::max

Maximum (inclusive)

The documentation for this struct was generated from the following file:
  • khtracker.h
Generated on Mon Oct 22 22:56:48 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Utilities

Utilities

Modules

Hashtable
Multi String and CSV functions
Synchronization

Generated on Mon Oct 22 22:56:47 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Hashtable

Hashtable
[Utilities]

Data Structures

struct | hash_bin
struct | hashtable

Typedefs

typedef khm_int32(* | hash_function_t )(const void *key)
A hash function.
typedef khm_int32(* | comp_function_t )(const void *key1, const void *key2)
A comparison function.
typedef void(* | add_ref_function_t )(const void *key, void *data)
Add-reference function.
typedef void(* | del_ref_function_t )(const void *key, void *data)
Delete-reference function.

Functions

KHMEXP hashtable *KHMAPI | hash_new_hashtable (khm_int32 n, hash_function_t hash, comp_function_t comp, add_ref_function_t addr, del_ref_function_t delr)
Create a new hashtable.
KHMEXP void KHMAPI | hash_del_hashtable (hashtable *h)
Delete a hashtable.
KHMEXP void KHMAPI | hash_add (hashtable *h, const void *key, void *data)
Add an object to a hashtable.
KHMEXP void KHMAPI | hash_del (hashtable *h, const void *key)
Delete an object from a hashtable.
KHMEXP void *KHMAPI | hash_lookup (hashtable *h, const void *key)
Resolve and association.
KHMEXP khm_boolean KHMAPI | hash_exist (hashtable *h, const void *key)
Check for the presence of an association.
KHMEXP khm_int32 | hash_string (const void *str)
Compute a hashvalue for a unicode string.
KHMEXP khm_int32 | hash_string_comp (const void *vs1, const void *vs2)
Compare two strings.

Typedef Documentation

typedef void(* add_ref_function_t)(const void *key, void *data)

Add-reference function.

When an object is successfully added to a hashtable, this function will be called with the key and data used to add the object. The function is allowed to modify data, however, the modification should not alter the key or the relationship between key and data.

typedef khm_int32(* comp_function_t)(const void *key1, const void *key2)

A comparison function.

The function takes two keys and returns a value indicating the relative ordering of the two keys.

The return value should be:

  • Zero if key1 == key2
  • Negative if key1 < key2
  • Positive if key1 > key2

typedef void(* del_ref_function_t)(const void *key, void *data)

Delete-reference function.

When an object is successfully removed from the hashtable, this function will be called. As with the add-ref function, the object can be modified, but the key and the relationship between key and data should remain intact.

An object is removed if it is explicitly removed from the hashtable or another object with the same key is added to the hashtable. There should be a 1-1 correspondence with keys and objects in the hashtable. The delete-reference function will be called on all the remaining objects in the hashtable when the hashtable is deleted.

typedef khm_int32(* hash_function_t)(const void *key)

A hash function.

The function should take a key as a parameter and return an khm_int32 that serves as the hash of the key.

Function Documentation

KHMEXP void KHMAPI hash_add | ( | hashtable * | h,
 |  | const void * | key,
 |  | void * | data
 | ) |  |

Add an object to a hashtable.

Creates an association between the key and data in the hashtable h. If there is an add-ref function defined for the hashtable, it will be called with key and after the object is added. If there is already an object with the same key in the hashtable, that object will be removed (and the del-ref function called, if appilcable) before adding the new object and before the add-ref function is called for the new object.

Note that two keys key1 and key2 are equal (or same) in a hashtable if the comparator returns zero when called with key1 and key2.

Also note that all additions and removals to the hashtable are done by reference. No data is copied. Any objects pointed to are expected to exist for the duration that the object and key are contained in the hashtable.

Parameters:
[in] | h | Hashtable
[in] | key | A key. If key points to a location in memory, it should be within the object pointed to by data, or be a constant. Can be NULL.
[in] | data | Data. Cannot be NULL.
Note:
Not thread-safe. Applications must serialize calls that reference the same hashtable.

KHMEXP void KHMAPI hash_del | ( | hashtable * | h,
 |  | const void * | key
 | ) |  |

Delete an object from a hashtable.

Deletes the object in the hashtable h that is associated with key key. An object is associated with key key if the key key_o that the object is associated with is the same as key as determined by the comparator. If the del-ref function is defined for the hash-table, it will be called with the key_o and data that was used to add the object.

Note:
Not thread-safe. Applications must serialize calls that reference the same hashtable.

KHMEXP void KHMAPI hash_del_hashtable ( hashtable * h )

Delete a hashtable.

Note:
Not thread-safe. Applications must serialize calls that reference the same hashtable.

KHMEXP khm_boolean KHMAPI hash_exist | ( | hashtable * | h,
 |  | const void * | key
 | ) |  |

Check for the presence of an association.

Returns non-zero if there exists an association between key key and some object in hashtable h. See hash_lookup() for definition of "association".

Returns zero if there is no association.

Note:
(hash_lookup(h,key) == NULL) iff (hash_exist(h,key)==0)

Not thead-safe. Application must serialize calls that reference the same hashtable.

KHMEXP void* KHMAPI hash_lookup | ( | hashtable * | h,
 |  | const void * | key
 | ) |  |

Resolve and association.

Return the object that is associated with key key in hashtable h. An object data is associated with key key in h if the key key_o that was used to add data to h is equal to key as determined by the comparator.

Returns NULL if no association is found.

Note:
Not thread-safe. Applications must serialize calls that reference the same hashtable.

KHMEXP hashtable* KHMAPI hash_new_hashtable | ( | khm_int32 | n,
 |  | hash_function_t | hash,
 |  | comp_function_t | comp,
 |  | add_ref_function_t | addr,
 |  | del_ref_function_t | delr
 | ) |  |

Create a new hashtable.

Parameters:
[in] | n | Number of bins in hashtable.
[in] | hash | A hash function. Required.
[in] | comp | A comparator. Required.
[in] | addr | An add-ref function. Optional; can be NULL.
[in] | delr | A del-ref function. Optional; can be NULL.

KHMEXP khm_int32 hash_string ( const void * str )

Compute a hashvalue for a unicode string.

The hash value is computed using DJB with parameter 13331.

This function is suitable for use as the hash function for a hashtable if the keys are NULL terminated safe unicode strings that are either part of the data objects or are constants.

Parameters:
[in] str A pointer to a NULL terminated wchar_t string cast as (void *).
Note:
This function does not check the length of the string str. If the string is not NULL terminated, the behavior is undefined.

KHMEXP khm_int32 hash_string_comp | ( | const void * | vs1,
 |  | const void * | vs2
 | ) |  |

Compare two strings.

Compares two strings are returns a value that is in accordance with the comparator for a hashtable.

Parameters:
[in] | vs1 | A pointer to a NULL terminated wchar_t string cast as (void *).
[in] | vs2 | A pointer to a NULL terminated wchar_t string cast as (void *).
Note:
This function does not check the length of the strings vs1 and vs2. If the strings are not NULL terminated, the behavior is undefined.

Generated on Mon Oct 22 22:56:46 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Multi String and CSV functions

Multi String and CSV functions
[Utilities]

Defines

#define | KHM_PREFIX 8
#define | KHM_CASE_SENSITIVE 16
#define | KHM_MAXCCH_STRING 16384
#define | KHM_MAXCB_STRING (KHM_MAXCCH_STRING * sizeof(wchar_t))

Functions

KHMEXP khm_int32 KHMAPI | multi_string_init (wchar_t *ms, khm_size cb_ms)
Initialize a multi-string.
KHMEXP khm_int32 KHMAPI | multi_string_prepend (wchar_t *ms, khm_size *pcb_ms, const wchar_t *str)
Prepend a string to a multi string.
KHMEXP khm_int32 KHMAPI | multi_string_append (wchar_t *ms, khm_size *pcb_ms, const wchar_t *str)
Append a string to a multi-string.
KHMEXP khm_int32 KHMAPI | multi_string_delete (wchar_t *ms, const wchar_t *str, const khm_int32 flags)
Deletes a string from a multi string.
KHMEXP wchar_t *KHMAPI | multi_string_find (const wchar_t *ms, const wchar_t *str, const khm_int32 flags)
Search a multi string for a string.
KHMEXP khm_int32 KHMAPI | multi_string_to_csv (wchar_t *csvbuf, khm_size *pcb_csvbuf, const wchar_t *ms)
Convert a multi string to CSV.
KHMEXP khm_int32 KHMAPI | csv_to_multi_string (wchar_t *ms, khm_size *pcb_ms, const wchar_t *csv)
Converts a CSV to a multi string.
KHMEXP wchar_t *KHMAPI | multi_string_next (const wchar_t *str)
Get the next string in a multi string.
KHMEXP khm_int32 KHMAPI | multi_string_length_cb (const wchar_t *str, khm_size max_cb, khm_size *len_cb)
Get the length of a multi string in bytes.
KHMEXP khm_int32 KHMAPI | multi_string_length_cch (const wchar_t *str, khm_size max_cch, khm_size *len_cch)
Get the length of a multi string in characters.
KHMEXP khm_size KHMAPI | multi_string_length_n (const wchar_t *str)
Get the number of strings in a multi string.
KHMEXP khm_int32 KHMAPI | multi_string_copy_cb (wchar_t *s_dest, khm_size max_cb_dest, const wchar_t *src)
Copy a multi string with byte counts.
KHMEXP khm_int32 KHMAPI | multi_string_copy_cch (wchar_t *s_dest, khm_size max_cch_dest, const wchar_t *src)
Copy a multi string with character count.

Function Documentation

KHMEXP khm_int32 KHMAPI csv_to_multi_string | ( | wchar_t * | ms,
 |  | khm_size * | pcb_ms,
 |  | const wchar_t * | csv
 | ) |  |

Converts a CSV to a multi string.

Undoes what multi_string_to_csv() does.

Parameters:
[out] | ms | The buffer that recieves the multi string. This can be NULL if only the size of the buffer is requried.
[in,out] | pcb_ms | On entry contains the number of bytes ni the buffer poitned to by ms. On exit contains the number of bytes that were copied to ms including terminating NULLs, or if the buffer was too small or ms was NULL, holds the size in bytes of the requied buffer.
[in] | csv | The CSV string.
Return values:
KHM_ERROR_SUCCESS | The CSV string was successfully converted. The number of bytes written is in pcb_ms.
KHM_ERROR_TOO_LONG | The provided buffer was too small or ms was NULL. The required size of the buffer in bytes is in pcb_ms.
KHM_ERROR_INVALID_PARAM | One or more parameters were invalid.

KHMEXP khm_int32 KHMAPI multi_string_append | ( | wchar_t * | ms,
 |  | khm_size * | pcb_ms,
 |  | const wchar_t * | str
 | ) |  |

Append a string to a multi-string.

Appends the string specified by str to the multi string specified by ms. The size of the multi string in characters including terminating NULLs after appending str can not exceed KHM_MAXCCH_STRING.

Parameters:
[in] | ms | The buffer containing the multi string
[in,out] | pcb_ms | Points to a khm_int32 indicating the size of the buffer pointed to by ms. On entry this contains the size (in bytes) of the buffer pointed to by ms. On exit, contains the new size of the multi string in bytes.
[in] | str | The string to append to the multi string. This string cannot be NULL or an empty (zero length) string. The length of str cannot exceed KHM_MAXCCH_STRING in characters including terminating NULL.
Return values:
KHM_ERROR_SUCCESS | The string was appended to the multi string
KHM_ERROR_TOO_LONG | The buffer pointed to by ms was insufficient. The required size of the buffer is in pcb_ms
KHM_ERROR_INVALID_PARAM | One of more of the parameters were invalid.

KHMEXP khm_int32 KHMAPI multi_string_copy_cb | ( | wchar_t * | s_dest,
 |  | khm_size | max_cb_dest,
 |  | const wchar_t * | src
 | ) |  |

Copy a multi string with byte counts.

Copy a multi string from one location to another.

Parameters:
[out] | s_dest | Receives a copy of the multi string
[in] | max_cb_dest | Number of bytes in the buffer pointed to by s_dest.
[in] | src | The source multi string
Return values:
KHM_ERROR_SUCCESS | The multi string was copied successfully
KHM_ERROR_INVALID_PARAM | One or more parameters were invalid.
KHM_ERROR_TOO_LONG | The size of the destination buffer was insufficient.

KHMEXP khm_int32 KHMAPI multi_string_copy_cch | ( | wchar_t * | s_dest,
 |  | khm_size | max_cch_dest,
 |  | const wchar_t * | src
 | ) |  |

Copy a multi string with character count.

Copy a multi string from one location to another.

Parameters:
[out] | s_dest | Receives a copy of the multi string
[in] | max_cb_dest | Number of characters in the buffer pointed to by s_dest.
[in] | src | The source multi string
Return values:
KHM_ERROR_SUCCESS | The multi string was copied successfully
KHM_ERROR_INVALID_PARAM | One or more parameters were invalid.
KHM_ERROR_TOO_LONG | The size of the destination buffer was insufficient.

KHMEXP khm_int32 KHMAPI multi_string_delete | ( | wchar_t * | ms,
 |  | const wchar_t * | str,
 |  | const khm_int32 | flags
 | ) |  |

Deletes a string from a multi string.

Deletes the string specified by str from the multi string specified by ms. How the string is matched to the strings in ms is determined by flags. If more than one match is found, then only the first match is deleted.

Parameters:
[in] | ms | The multi string to modify. The length of the multi string in characters cannot exceed KHM_MAXCCH_STRING.
[in] | str | The string to search for
[in] | flags | How str is to be matched to existing strings in ms. This could be a combination of KHM_PREFIX and KHM_CASE_SENSITIVE. If KHM_PREFIX is used, then ms is searched for a string that begins with str. Otherwise, str must match the an entire string in the multi string. If KHM_CASE_SENSITIVE is specified, then a case sensitive match is performed. The defualt is to use a case insensitive search.
Return values:
KHM_ERROR_SUCCESS | A string was matched and deleted from ms
KHM_ERROR_NOT_FOUND | No matches were found
KHM_ERROR_INVALID_PARAM | One or more parameters were incorrect.
Note:
The search for the existing string is done with multi_string_find()

KHMEXP wchar_t* KHMAPI multi_string_find | ( | const wchar_t * | ms,
 |  | const wchar_t * | str,
 |  | const khm_int32 | flags
 | ) |  |

Search a multi string for a string.

Searches the string specified by ms for a string that matches str. How the match is performed is determined by flags. Returns a poitner to the start of the matched string in ms. If more than one string in ms matches str, then only the first match is returned.

Parameters:
[in] | ms | The multi string to search in. The length of the multi string cannot exceed KHM_MAXCCH_STRING in characters.
[in] | str | The string to search for
[in] | flags | How str is to be matched to existing strings in ms. This could be a combination of KHM_PREFIX and KHM_CASE_SENSITIVE. If KHM_PREFIX is used, then ms is searched for a string that begins with str. Otherwise, str must match the an entire string in the multi string. If KHM_CASE_SENSITIVE is specified, then a case sensitive match is performed. The defualt is to use a case insensitive search.
Returns:
A pointer to the start of the first matched string or NULL if no matches were found.

KHMEXP khm_int32 KHMAPI multi_string_length_cb | ( | const wchar_t * | str,
 |  | khm_size | max_cb,
 |  | khm_size * | len_cb
 | ) |  |

Get the length of a multi string in bytes.

The returned length includes the trailing double NULL and any other NULL inbetween.

Parameters:
[in] | str | Pointer to a multi string.
[in] | max_cb | Maximum size that the str can be. This can not be larger than KHM_MAXCB_STRING.
[out] | len_cb | The length of the string in bytes if the call is successful.
Return values:
KHM_ERROR_SUCCESS | The length of the string is in len_cb
KHM_ERROR_INVALID_PARAM | One or more parameters were invalid
KHM_ERROR_TOO_LONG | The multi string is longer than max_cb bytes.

KHMEXP khm_int32 KHMAPI multi_string_length_cch | ( | const wchar_t * | str,
 |  | khm_size | max_cch,
 |  | khm_size * | len_cch
 | ) |  |

Get the length of a multi string in characters.

The returned length includes the trailing double NULL and any other NULL inbetween.

Parameters:
[in] | str | Pointer to a multi string.
[in] | max_cch | Maximum size that the str can be. This can not be larger than KHM_MAXCCH_STRING.
[out] | len_cch | The length of the string in characters if the call is successful.
Return values:
KHM_ERROR_SUCCESS | The length of the string is in len_cch
KHM_ERROR_INVALID_PARAM | One or more parameters were invalid
KHM_ERROR_TOO_LONG | The multi string is longer than max_cch characters.

KHMEXP wchar_t* KHMAPI multi_string_next ( const wchar_t * str )

Get the next string in a multi string.

When str is pointing to a string that is in a multi string, this function returns a pointer to the next string in the multi string.

Typically, one would start by having str point to the start of the multi string (which is the first string in the multi string), and then call this function repeatedly, until it returns NULL, at which point the end of the multi string has been reached.

Parameters:
[in] str Pointer to a string in a multi string. Each string in a multi string cannot exceed KHM_MAXCCH_STRING in charaters including the terminating NULL.
Returns:
A pointer to the start of the next string in the multi string or NULL if there is no more strings.

KHMEXP khm_int32 KHMAPI multi_string_prepend | ( | wchar_t * | ms,
 |  | khm_size * | pcb_ms,
 |  | const wchar_t * | str
 | ) |  |

Prepend a string to a multi string.

Adds the string str to the beginning of multi-string ms.

Parameters:
[in,out] | ms | The multi-string to be modified.
[in,out] | pcb_ms | A pointer to the size of the multistring. On entry this specifies the size of the buffer pointed to by ms. If the call is successful, on exit this will receive the new size of the multi string in bytes. If the buffer is insufficient, the function will return KHM_ERROR_TOO_LONG and set this to the required size of the buffer in bytes.
[in] | str | The string to prepend to ms. This cannot be longer than KHM_MAXCCH_STRING in characters including the terminating NULL.

KHMEXP khm_int32 KHMAPI multi_string_to_csv | ( | wchar_t * | csvbuf,
 |  | khm_size * | pcb_csvbuf,
 |  | const wchar_t * | ms
 | ) |  |

Convert a multi string to CSV.

Converts a multi string to a comma separated value string based on the following rules.

  • Each string in the multi string is treated an individual field

  • A field is quoted if it has double quotes or commas

  • Double quotes within quoted fields are escaped by two consecutive double quotes.

For example:

    multi_string = L"foo\0bar\0baz,quux\0ab\"cd\0";
    csv_string = L"foo,bar,\"baz,quux\",\"ab\"\"cd\"";

If multi_string_to_csv() is called on multi_string above, you would obtain csv_string.

Parameters:
[out] | csvbuf | The buffer to place the CSV string in. Can be NULL if only teh size of the needed buffer is required.
[in,out] | pcb_csvbuf | On entry, points to a khm_int32 that holds the size of the buffer pointed to by csvbuf. On exit, gets the number of bytes writted to csvbuf or the required size of csvbuf if the buffer is too small or csvbuf is NULL.
[in] | ms | The mutli string to convert to a CSV.
Return values:
KHM_ERROR_SUCCESS | The multi string was successfully converted to a CSV string. The number of bytes written is in pcb_csvbuf. The count includes the terminating NULL.
KHM_ERROR_TOO_LONG | The buffer was too small or csvbuf was NULL. The required number of bytes in the buffer is in pcb_csvbuf.
KHM_ERROR_INVALID_PARAM | One or more parameters were ivnalid.
See also:
csv_to_multi_string()

Generated on Mon Oct 22 22:56:46 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Synchronization

Synchronization
[Utilities]

Data Structures

struct | rw_lock_t
A read/write lock. More...

Typedefs

typedef rw_lock_t | RWLOCK
typedef rw_lock_t * | PRWLOCK

Functions

KHMEXP void KHMAPI | InitializeRwLock (PRWLOCK pLock)
Initialize a read/write lock.
KHMEXP void KHMAPI | DeleteRwLock (PRWLOCK pLock)
Delete a read/write lock.
KHMEXP void KHMAPI | LockObtainRead (PRWLOCK pLock)
Obtains a read lock on the read/write lock.
KHMEXP void KHMAPI | LockReleaseRead (PRWLOCK pLock)
Relase a read lock obtained on a read/write lock.
KHMEXP void KHMAPI | LockObtainWrite (PRWLOCK pLock)
Obtains a write lock on the read/write lock.
KHMEXP void KHMAPI | LockReleaseWrite (PRWLOCK pLock)
Relase a write lock obtained on a read/write lock.

Function Documentation

KHMEXP void KHMAPI DeleteRwLock ( PRWLOCK pLock )

Delete a read/write lock.

Once the application is done using the read/write lock, it must be deleted with a call to DeleteRwLock()

KHMEXP void KHMAPI InitializeRwLock ( PRWLOCK pLock )

Initialize a read/write lock.

A lock must be initialized before it can be used. Initializing the lock does not grant the caller any locks on the object.

KHMEXP void KHMAPI LockObtainRead ( PRWLOCK pLock )

Obtains a read lock on the read/write lock.

Multiple readers can obtain read locks on the same r/w lock. However, if any thread attempts to obtain a write lock on the object, it will wait until all readers have released the read locks.

Call LockReleaseRead() to release the read lock. While the same thread may obtain multiple read locks on the same object, each call to LockObtainRead() must have a corresponding call to LockReleaseRead() to properly relinquish the lock.

See also:
LockReleaseRead()

KHMEXP void KHMAPI LockObtainWrite ( PRWLOCK pLock )

Obtains a write lock on the read/write lock.

Only a single writer is allowed to lock a single r/w lock. However, if any thread attempts to obtain a read lock on the object, it will wait until the writer has released the lock.

Call LockReleaseWrite() to release the write lock. While the same thread may obtain multiple write locks on the same object, each call to LockObtainWrite() must have a corresponding call to LockReleaseWrite() to properly relinquish the lock.

See also:
LockReleaseWrite()

KHMEXP void KHMAPI LockReleaseRead ( PRWLOCK pLock )

Relase a read lock obtained on a read/write lock.

Each call to LockObtainRead() must have a corresponding call to LockReleaseRead(). Once all read locks are released, any threads waiting on write locks on the object will be woken and assigned a write lock.

See also:
LockObtainRead()

KHMEXP void KHMAPI LockReleaseWrite ( PRWLOCK pLock )

Relase a write lock obtained on a read/write lock.

Each call to LockObtainWrite() must have a corresponding call to LockReleaseWrite(). Once the write lock is released, any threads waiting for read or write locks on the object will be woken and assigned the proper lock.

See also:
LockObtainWrite()

Generated on Mon Oct 22 22:56:47 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: rw_lock_t Struct Reference

rw_lock_t Struct Reference
[Synchronization]

#include <sync.h>

Detailed Description

A read/write lock.

A classic read/write lock. Allows multiple readers or a single writer to access a protected object. Readers will wait for any pending writer to release the lock, while a writer will wait for any pending readers to release the lock.

Data Fields

int | locks
int | status
CRITICAL_SECTION | cs
HANDLE | readwx
HANDLE | writewx
DWORD | writer

The documentation for this struct was generated from the following file:
  • sync.h
Generated on Mon Oct 22 22:56:49 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: NetIDMgr Module Manager

NetIDMgr Module Manager

Modules

Registration
Internationalization support
NetIDMgr Plugin Callbacks

Data Structures

struct | kmm_plugin_reg
Plugin registration. More...
struct | kmm_plugin_info
Plugin information. More...
struct | kmm_module_reg
Module registration. More...
struct | kmm_module_info
Module information record. More...

Limits

#define | KMM_MAXCCH_NAME 256
Maximum number of characters in a name in KMM including the terminating NULL.
#define | KMM_MAXCB_NAME (sizeof(wchar_t) * KMM_MAXCCH_NAME)
Maximum number of bytes in a name in KMM including the terminating NULL.
#define | KMM_MAXCCH_DESC 512
Maximum number of characters in a description in KMM including the terminating NULL.
#define | KMM_MAXCB_DESC (sizeof(wchar_t) * KMM_MAXCCH_NAME)
Maximum number of bytes in a description in KMM including the terminating NULL.
#define | KMM_MAXCCH_VENDOR 256
Maximum number of characters in a vendor string in KMM including the terminating NULL.
#define | KMM_MAXCB_VENDOR (sizeof(wchar_t) * KMM_MAXCCH_VENDOR)
Maximum number of bytes in a vendor string in KMM including the terminating NULL.
#define | KMM_MAXCCH_SUPPORT 256
Maximum number of characters in a support URI in KMM including the terminating NULL.
#define | KMM_MAXCB_SUPPORT (sizeof(wchar_t) * KMM_MAXCCH_SUPPORT)
Maximum number of bytes in a vendor string in KMM including the terminating NULL.
#define | KMM_MAX_DEPENDENCIES 8
Maximum number of dependencies per plugin.
#define | KMM_MAX_DEPENDANTS 32
Maximum number of dependants per plugin.
#define | KMM_MAXCCH_DEPS (KMM_MAXCCH_NAME * KMM_MAX_DEPENDENCIES + 1)
Maximum number of characters a dependency string including trailing double NULL.
#define | KMM_MAXCB_DEPS (sizeof(wchar_t) * KMM_MAXCCH_DEPS)
Maximum number of bytes in a dependency string including trailing double NULL.

Plugin types

#define | KHM_PITYPE_CRED 1
A credentials provider.
#define | KHM_PITYPE_IDENT 2
A identity provider.
#define | KHM_PITYPE_CONFIG 3
A configuration provider.
#define | KHM_PITYPE_MISC 4
Undefined plugin type.

Flags for kmm_load_module()

#define | KMM_LM_FLAG_SYNC 1
Load synchronously.
#define | KMM_LM_FLAG_NOLOAD 2
Do not load.

Defines

#define | KMM_PLUGIN_FLAG_DISABLED 0x00000400
The plugin is disabled.

Typedefs

typedef khm_handle | kmm_module
A handle to a module.
typedef khm_handle | kmm_plugin
A handle to a plugin.

Enumerations

enum _kmm_plugin_states {
KMM_PLUGIN_STATE_FAIL_INIT = -6, KMM_PLUGIN_STATE_FAIL_UNKNOWN = -5, KMM_PLUGIN_STATE_FAIL_MAX_FAILURE = -4, KMM_PLUGIN_STATE_FAIL_NOT_REGISTERED = -3,
KMM_PLUGIN_STATE_FAIL_DISABLED = -2, KMM_PLUGIN_STATE_FAIL_LOAD = -1, KMM_PLUGIN_STATE_NONE = 0, KMM_PLUGIN_STATE_PLACEHOLDER,
KMM_PLUGIN_STATE_REG, KMM_PLUGIN_STATE_PREINIT, KMM_PLUGIN_STATE_HOLD, KMM_PLUGIN_STATE_INIT,
KMM_PLUGIN_STATE_RUNNING, KMM_PLUGIN_STATE_EXITED
}
Plugin states. More...
enum KMM_MODULE_STATES {
KMM_MODULE_STATE_FAIL_INCOMPAT = -12, KMM_MODULE_STATE_FAIL_INV_MODULE = -11, KMM_MODULE_STATE_FAIL_UNKNOWN = -10, KMM_MODULE_STATE_FAIL_MAX_FAILURE = -9,
KMM_MODULE_STATE_FAIL_DUPLICATE = -8, KMM_MODULE_STATE_FAIL_NOT_REGISTERED = -7, KMM_MODULE_STATE_FAIL_NO_PLUGINS = -6, KMM_MODULE_STATE_FAIL_DISABLED = -5,
KMM_MODULE_STATE_FAIL_LOAD = -4, KMM_MODULE_STATE_FAIL_INVALID = -3, KMM_MODULE_STATE_FAIL_SIGNATURE = -2, KMM_MODULE_STATE_FAIL_NOT_FOUND = -1,
KMM_MODULE_STATE_NONE = 0, KMM_MODULE_STATE_PREINIT, KMM_MODULE_STATE_INIT, KMM_MODULE_STATE_INITPLUG,
KMM_MODULE_STATE_RUNNING, KMM_MODULE_STATE_EXITPLUG, KMM_MODULE_STATE_EXIT, KMM_MODULE_STATE_EXITED
}
Module states. More...

Functions

KHMEXP void KHMAPI | kmm_init (void)
Start the Module Manager.
KHMEXP void KHMAPI | kmm_exit (void)
Stop the Module Manager.
KHMEXP kmm_plugin KHMAPI | kmm_this_plugin (void)
Return the plugin handle for the current plugin.
KHMEXP kmm_module KHMAPI | kmm_this_module (void)
Return the module handle for the current module.
KHMEXP khm_int32 KHMAPI | kmm_load_module (wchar_t *modname, khm_int32 flags, kmm_module *result)
Load a module.
KHMEXP khm_int32 KHMAPI | kmm_hold_module (kmm_module module)
Hold a handle to a module.
KHMEXP khm_int32 KHMAPI | kmm_release_module (kmm_module m)
Release a handle to a module.
KHMEXP khm_int32 KHMAPI | kmm_get_module_state (kmm_module m)
Query the state of a module.
KHMEXP khm_int32 KHMAPI | kmm_unload_module (kmm_module module)
Unload a module.
KHMEXP khm_int32 KHMAPI | kmm_load_default_modules (void)
Loads the default modules as specified in the configuration.
KHMEXP khm_boolean KHMAPI | kmm_load_pending (void)
Checks whether there are any pending loads.
KHMEXP HMODULE KHMAPI | kmm_get_hmodule (kmm_module m)
Returns the Windows module handle from a handle to a NetIDMgr module. Although it is possible to obtain the Windows module handle and use it to call Windows API functions, it is not recommended to do so. This is because that might cause the state of the module to change in ways which are inconsistent from the internal data structures that kmm maintains.
KHMEXP khm_int32 KHMAPI | kmm_hold_plugin (kmm_plugin p)
Hold a plugin.
KHMEXP khm_int32 KHMAPI | kmm_release_plugin (kmm_plugin p)
Release a plugin.
KHMEXP khm_int32 KHMAPI | kmm_provide_plugin (kmm_module module, kmm_plugin_reg *plugin)
Provide a plugin.
KHMEXP khm_int32 KHMAPI | kmm_get_plugin_state (wchar_t *plugin)
Query the state of a plugin.

Define Documentation

#define KHM_PITYPE_CONFIG 3

A configuration provider.

See also:
pi_pt_conf for more information.

#define KHM_PITYPE_CRED 1

A credentials provider.

See also:
Credential Provider for more information.

#define KHM_PITYPE_IDENT 2

A identity provider.

See also:
Credential Provider for more information

#define KHM_PITYPE_MISC 4

Undefined plugin type.

The plugin doesn't provide any credential type.

#define KMM_LM_FLAG_NOLOAD 2

Do not load.

Indicates that the module shouldn't actually be loaded. If the specified module name identifies a module that has already been loaded, then the function returns a held handle to the existing module (use kmm_release_module() to free the handle). Otherwise, the function returns KHM_ERROR_NOT_FOUND.

#define KMM_LM_FLAG_SYNC 1

Load synchronously.

If this flag is set, then the function waits for the module to be loaded. The default is to load the module asynchronously.

When loading a module asynchronously, the kmm_load_module() function returns KHM_ERROR_SUCCESS and exits without waiting for the module to load. If result is not NULL, it will receive a valid handle to the module.

When loading a module synchronously, kmm_load_module() will wait for the module to completely load. If it fails to load properly, it will return an error code and set result to NULL.

#define KMM_PLUGIN_FLAG_DISABLED 0x00000400

The plugin is disabled.

This flag will be set in the flags field of the kmm_plugin_info structure for a plugin that has been marked as disabled. If the plugin is currently running, but marked as disabled for future sessions, then this bit will be set in flags , but the state of the plugin will indicate that the plugin is running.

Enumeration Type Documentation

enum _kmm_plugin_states

Plugin states.

Enumerator:
KMM_PLUGIN_STATE_FAIL_INIT | Failed to initialize
KMM_PLUGIN_STATE_FAIL_UNKNOWN | Failed due to unknown reasons
KMM_PLUGIN_STATE_FAIL_MAX_FAILURE | The plugin has reached the maximum number of failures and cannot be initialized until the failure count is reset
KMM_PLUGIN_STATE_FAIL_NOT_REGISTERED | Failed because the plugin was not registered and automatic registration failed.
KMM_PLUGIN_STATE_FAIL_DISABLED | Failed because plugin was disabled by the user.
KMM_PLUGIN_STATE_FAIL_LOAD | The plugin failed to load due to some unknown reason.
KMM_PLUGIN_STATE_NONE | Unknown state
KMM_PLUGIN_STATE_PLACEHOLDER | Placeholder. The plugin hasn't been provided by anyone yet, but the plugin record has been created to keep track of dependencies.
KMM_PLUGIN_STATE_REG | The plugin is registered but not initialized
KMM_PLUGIN_STATE_PREINIT | The plugin is in the process of being initialized
KMM_PLUGIN_STATE_HOLD | On hold. One or more dependencies of this plugin has not been resolved
KMM_PLUGIN_STATE_INIT | The plugin was initialized
KMM_PLUGIN_STATE_RUNNING | The plugin is running
KMM_PLUGIN_STATE_EXITED | The plugin has been stopped.

enum KMM_MODULE_STATES

Module states.

Enumerator:
KMM_MODULE_STATE_FAIL_INCOMPAT | The library containing the module was not compatible with this version of NetIDMgr.
KMM_MODULE_STATE_FAIL_INV_MODULE | The library containing the module was invalid.
KMM_MODULE_STATE_FAIL_UNKNOWN | Module could not be loaded due to unknown reasons.
KMM_MODULE_STATE_FAIL_MAX_FAILURE | The module has failed too many times already. Not attempting to restart it again
KMM_MODULE_STATE_FAIL_DUPLICATE | An attempt was made to load the same module twice.
KMM_MODULE_STATE_FAIL_NOT_REGISTERED | The module is not found among the registered module list
KMM_MODULE_STATE_FAIL_NO_PLUGINS | The module provided no plugins, or all the plugins that are provided are disabled
KMM_MODULE_STATE_FAIL_DISABLED | Module is disabled and cannot be loaded
KMM_MODULE_STATE_FAIL_LOAD | The module failed to initialize
KMM_MODULE_STATE_FAIL_INVALID | The module was invalid. Typically caused by the required entrypoints not being present
KMM_MODULE_STATE_FAIL_SIGNATURE | The module failed to load due to an unverifiable signature
KMM_MODULE_STATE_FAIL_NOT_FOUND | The module was not found
KMM_MODULE_STATE_NONE | Unknown state. The handle is possibly invalid
KMM_MODULE_STATE_PREINIT | The module is being loaded. init_module() hasn't been called yet
KMM_MODULE_STATE_INIT | In init_module()
KMM_MODULE_STATE_INITPLUG | Initializing plugins
KMM_MODULE_STATE_RUNNING | Running
KMM_MODULE_STATE_EXITPLUG | Currently exiting plugins
KMM_MODULE_STATE_EXIT | Currently exiting
KMM_MODULE_STATE_EXITED | Exited

Function Documentation

KHMEXP void KHMAPI kmm_exit ( void )

Stop the Module Manager.

Note:
Only called by the NetIDMgr core.

KHMEXP khm_int32 KHMAPI kmm_get_module_state ( kmm_module m )

Query the state of a module.

When loading a module asynchronously you can query the state of the loading process using this. The return value is a status indicator.

Returns:
The return value is one of the KMM_MODULE_STATES enumerations.

KHMEXP khm_int32 KHMAPI kmm_get_plugin_state ( wchar_t * plugin )

Query the state of a plugin.

Returns:
One of _kmm_plugin_states

KHMEXP khm_int32 KHMAPI kmm_hold_module ( kmm_module module )

Hold a handle to a module.

Use kmm_release_module() to release the hold.

KHMEXP khm_int32 KHMAPI kmm_hold_plugin ( kmm_plugin p )

Hold a plugin.

Obtains a hold on a plugin. The plugin handle will remain valid until the hold is released with a call to kmm_release_plugin(). No guarantees are made on the handle once the handle is released.

KHMEXP void KHMAPI kmm_init ( void )

Start the Module Manager.

Note:
Only called by the NetIDMgr core.

KHMEXP khm_int32 KHMAPI kmm_load_default_modules ( void )

Loads the default modules as specified in the configuration.

The configuration can specify the default set of modules to load. This function dispatches the necessary message for loading these modules and reutnrs.

KHMEXP khm_int32 KHMAPI kmm_load_module | ( | wchar_t * | modname,
 |  | khm_int32 | flags,
 |  | kmm_module * | result
 | ) |  |

Load a module.

The modulename parameter specifies a module to load. Depending on the configuration, not all of the plugins that are provided by the module may be loaded. If no plugins are successfully loaded, the module will be immediately unloaded.

If the module is currently loaded or is being loaded, then a valid handle to the existing module is returned.

When called with KMM_LM_FLAG_SYNC, the function does not return until the module and the associated plugins are all initialized, or an error occurs.

If the KMM_LM_FLAG_NOLOAD flag is set, then a handle to an existing instance of the module will be returned. If the module hasn't been loaded yet, then no handle is returned and the function returns KHM_ERROR_NOT_FOUND.

See the associated NetIDMgr Module Manager documentation on the sequence of events associated with loading a module.

Parameters:
[in] | modulename | Name of the module. The module should have been registered under this name prior to the call.
[in] | flags | Combination of KMM_LM_FLAG_*
[out] | result | Receives a handle to the loaded module. If the result is not required, set this to NULL. If result is not NULL, and km_load_module() returns KHM_ERROR_SUCCESS, then kmm_release_module() must be called to release the handle to the module. Otherwise, result receives NULL. If a handle is returned, it will be valid regardless of whether the module fails to load or not. You can use kmm_get_module_state() to query the progress of the loading process. See KMM_LM_FLAG_SYNC.
Return values:
KHM_ERROR_SUCCESS | The call succeeded. If KMM_LM_FLAG_SYNC was specified, this means that the module was successfully loaded. Otherwise, it only means that the module has been queued up for loading. Use kmm_get_module_state() to determine if it was successfully loaded. If result is not NULL, a valid handle is returned.
KHM_ERROR_EXISTS | The module is already loaded or has been already queued for loading. If result is not NULL, a valid handle to the existing module instance is returned.
KHM_ERROR_NOT_FOUND | If called with KMM_LM_FLAG_NOLOAD, indicates that the module has not been loaded. Otherwise only returned when called with KMM_LM_FLAG_SYNC. The module image was not found. No handle is returned.
KHM_ERROR_INVALID_SIGNATURE | Only returned when called with KMM_LM_FLAG_SYNC. The module was signed with an invalid certificate. No handle is returned.
KHM_ERROR_UNKNOWN | Only returned when called with KMM_LM_FLAG_SYNC. Some other error has occured. No handle is returned.
See also:
Module Load Sequence

KMM_LM_FLAG_SYNC, KMM_LM_FLAG_NOLOAD

KHMEXP khm_boolean KHMAPI kmm_load_pending ( void )

Checks whether there are any pending loads.

Returns TRUE if there are modules still waiting to be loaded.

KHMEXP khm_int32 KHMAPI kmm_provide_plugin | ( | kmm_module | module,
 |  | kmm_plugin_reg * | plugin
 | ) |  |

Provide a plugin.

This function must be called for each plugin that the module provides.

Note that this function returns immediately and does not initialize the plugin. All plugins that are provided by a module will be initialized once the init_module() function returns. If the plugin has dependencies, it will be kept in a held state until the plugins that it depends on are successfully initialized. If the dependencies are not resolved (the dependent plugins are not loaded), then plugin will not be initialized.

If the plugin is not registered and plugin contains enough information to perform the registration, then it will be automatically registered. However, if the plugin is not registered and cannot be registered using the provided information, the plugin will not be initialized properly. Note that automatic registration will always register the plugin in the user configuration store.

The name and msg_proc members of plugin are required to have valid values. The icon member may optionally be specified. The other fields can be specified if the plugin should be automatically registered, however, the module field will be ignored and will be determined by the module handle.

Parameters:
[in] | module | Handle to this module that is providing the plugin.
[in] | plugin | A plugin descriptor.
Return values:
KHM_ERROR_SUCCESS | Succeeded.
KHM_ERROR_INVALID_OPERATION | The function was not called during init_module()
KHM_ERROR_INVALID_PARAM | One or more parameters were invalid
KHM_ERROR_DUPLICATE | The plugin was already provided
Note:
This can only be called when handing init_module()

KHMEXP khm_int32 KHMAPI kmm_release_module ( kmm_module m )

Release a handle to a module.

Release a held referece to a module that was returned in a call to kmm_load_module().

KHMEXP khm_int32 KHMAPI kmm_release_plugin ( kmm_plugin p )

Release a plugin.

Releases a hold on a plugin obtained through a call to kmm_hold_plugin(). The plugin handle should no longer be considered valied once this is called.

KHMEXP kmm_module KHMAPI kmm_this_module ( void )

Return the module handle for the current module.

The returned handle represents the module which owns the current thread. The returned handle must be released by calling kmm_release_module()

KHMEXP kmm_plugin KHMAPI kmm_this_plugin ( void )

Return the plugin handle for the current plugin.

The returned handle represents the plugin which owns the current thread. The returned handle must be released by calling kmm_release_plugin(). Returns NULL if the current thread is not owned by any plugin.

KHMEXP khm_int32 KHMAPI kmm_unload_module ( kmm_module module )

Unload a module.

See the associated NetIDMgr Module Manager documentation on the sequence of events associated with unloading a module.

See also:
Unload sequence

Generated on Mon Oct 22 22:56:47 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Registration

Registration
[NetIDMgr Module Manager]

Detailed Description

The functions for managing plugin and module registration. These functions are also available as static linked libraries for use by external applications which must register or unregister plugins or modules.

Functions

KHMEXP khm_int32 KHMAPI | kmm_get_plugin_config (wchar_t *plugin, khm_int32 flags, khm_handle *result)
Obtain the configuration space for a named plugin.
KHMEXP khm_int32 KHMAPI | kmm_get_module_config (wchar_t *module, khm_int32 flags, khm_handle *result)
Obtain the configuration space for a named module.
KHMEXP khm_int32 KHMAPI | kmm_get_plugins_config (khm_int32 flags, khm_handle *result)
Retrieve a handle to the configuration space for plugins.
KHMEXP khm_int32 KHMAPI | kmm_get_modules_config (khm_int32 flags, khm_handle *result)
Retrieve the handle to the configuration space for modules.
KHMEXP khm_int32 KHMAPI | kmm_get_module_info (wchar_t *module_name, khm_int32 flags, kmm_module_info *buffer, khm_size *cb_buffer)
Return information about a loaded module.
KHMEXP khm_int32 KHMAPI | kmm_get_module_info_i (kmm_module module, kmm_module_info *info)
Get information about a module.
KHMEXP khm_int32 KHMAPI | kmm_release_module_info_i (kmm_module_info *info)
Release module information.
KHMEXP khm_int32 KHMAPI | kmm_get_plugin_info (wchar_t *plugin_name, kmm_plugin_info *buffer, khm_size *cb_buffer)
Obtain information about a plugin.
KHMEXP khm_int32 KHMAPI | kmm_get_plugin_info_i (kmm_plugin p, kmm_plugin_info *info)
Obtain information about a plugin using a plugin handle.
KHMEXP khm_int32 KHMAPI | kmm_release_plugin_info_i (kmm_plugin_info *info)
Release plugin information returned by kmm_get_plugin_info_i.
KHMEXP khm_int32 KHMAPI | kmm_get_next_plugin (kmm_plugin p, kmm_plugin *p_next)
Enumerates plugins.
KHMEXP khm_int32 KHMAPI | kmm_enable_plugin (kmm_plugin p, khm_boolean enable)
Enables or disables a plugin.
KHMEXP khm_int32 KHMAPI | kmm_register_plugin (kmm_plugin_reg *plugin, khm_int32 config_flags)
Register a plugin.
KHMEXP khm_int32 KHMAPI | kmm_register_module (kmm_module_reg *module, khm_int32 config_flags)
Register a module.
KHMEXP khm_int32 KHMAPI | kmm_unregister_plugin (wchar_t *plugin, khm_int32 config_flags)
Unregister a plugin.
KHMEXP khm_int32 KHMAPI | kmm_unregister_module (wchar_t *module, khm_int32 config_flags)
Unregister a module.

Function Documentation

KHMEXP khm_int32 KHMAPI kmm_enable_plugin | ( | kmm_plugin | p,
 |  | khm_boolean | enable
 | ) |  |

Enables or disables a plugin.

This function currently does not take effect immediately. However it marks the plugin as enabled or disabled so that the next time NetIDMgr starts, the module manager will act accordingly.

Parameters:
[in] | p | Handle to the plugin
[in] | enable | If non-zero, the plugin will be marked as enabled. Otherwise the plugin will be marked as disabled.

KHMEXP khm_int32 KHMAPI kmm_get_module_config | ( | wchar_t * | module,
 |  | khm_int32 | flags,
 |  | khm_handle * | result
 | ) |  |

Obtain the configuration space for a named module.

The named module does not have to actually exist. Configuration spaces for modules are based on the basename of the module (including the extension).

Parameters:
[in] | module | Name of the module.
[in] | flags | The flags used to call khc_open_space(). You can use this to specify a particular configuration store if needed.
[out] | result | Receives the handle to a configuration space if successful. Call khc_close_space() to close the handle.
See also:
khc_open_space()

khc_close_space()

KHMEXP khm_int32 KHMAPI kmm_get_module_info | ( | wchar_t * | module_name,
 |  | khm_int32 | flags,
 |  | kmm_module_info * | buffer,
 |  | khm_size * | cb_buffer
 | ) |  |

Return information about a loaded module.

The retrieves a block of information about a module. Refer to kmm_module_info for information about the format of the returned data.

Note that the size of the required buffer is actually greater than the size of the kmm_module_info structure and accomodates the kmm_plugin_info structures and strings required to complete the information block.

Call the function with buffer set to NULL and cb_buffer pointing at a khm_size variable to obtain the required size of the buffer.

Parameters:
[in] | module_name | Name of a module
[in] | flags | Flags indicating which types of information to return
[out] | buffer | Points to a buffer that recieves information. Set this to NULL if only the size of the buffer is required.
[in,out] | On | entry, contains the size of the buffer pointed to by buffer if buffer is not NULL. On exit, contains the required size of the buffer or the number of actual bytes copied.
Return values:
KHM_ERROR_SUCCESS | The requested information was copied
KHM_ERROR_INVALID_PARAM | One of the parameters was invalid
KHM_ERROR_TOO_LONG | The buffer was not large enough or was NULL. The number of bytes requied is in cb_buffer.
KHM_ERROR_NOT_FOUND | The specified module is not a registered module.

KHMEXP khm_int32 KHMAPI kmm_get_module_info_i | ( | kmm_module | module,
 |  | kmm_module_info * | info
 | ) |  |

Get information about a module.

Similar to kmm_get_module_info(), but uses a module handle instead of a name, and uses internal buffers for providing string fields.

The information that is returned should be freed using a call to kmm_release_module_info_i().

See also:
kmm_release_module_info_i()

KHMEXP khm_int32 KHMAPI kmm_get_modules_config | ( | khm_int32 | flags,
 |  | khm_handle * | result
 | ) |  |

Retrieve the handle to the configuration space for modules.

The configuration space for modules is a container which hold the configuration subspaces for all the modules. Each module registration ends up in this subspace.

Parameters:
[in] | flags | The flags to pass in to the call to khc_open_space(). The flags can be used to select a specific configuration store if needed.
[out] | result | Receives a handle to the configuration space. Call khc_close_space() to close the handle.
See also:
khc_open_space()

khc_close_space()

KHMEXP khm_int32 KHMAPI kmm_get_next_plugin | ( | kmm_plugin | p,
 |  | kmm_plugin * | p_next
 | ) |  |

Enumerates plugins.

Enumerates through known plugins. This list may not include plugins which were not loaded by NetIDMgr in this session.

If the call is successful, a handle to the next plugin in the list will be placed in p_next. The returned handle must be freed with a call to kmm_release_plugin().

If the p parameter is set to NULL, then the first plugin handle will be placed in p_next. The handles will not be returned in any specific order. In addition, the enumeration may not include all known plugins if the list of plugins changes during enumeration.

KHMEXP khm_int32 KHMAPI kmm_get_plugin_config | ( | wchar_t * | plugin,
 |  | khm_int32 | flags,
 |  | khm_handle * | result
 | ) |  |

Obtain the configuration space for a named plugin.

Note that the named plugin does not have to actually exist. Configuration spaces for plugins are based solely on the plugin name and hence can be accessed regardless of whether the specific plugin is loaded or not.

Parameters:
[in] | flags | Controls the options for opening the configuration space. If KHM_FLAG_CREATE is specified, then the configuration space for the plugin named plugin wil be created if it doesn't already exist. The flags parameter is directly passed into a call to khc_open_space().
[in] | plugin | Name of the plugin. The name can not contain slashes.
[out] | result | Receives a configuration space handle. The calling application should free the handle using khc_close_space().
See also:
khc_open_space()

khc_close_space()

KHMEXP khm_int32 KHMAPI kmm_get_plugin_info | ( | wchar_t * | plugin_name,
 |  | kmm_plugin_info * | buffer,
 |  | khm_size * | cb_buffer
 | ) |  |

Obtain information about a plugin.

Retrieve a block of information about a plugin. See kmm_plugin_info for details about what information can be returned. Note that some fields may not be available if the module is not loaded.

Note that the size of the required buffer is greater than the size of the kmm_plugin_info structure and accounts for strings as well. Call kmm_get_plugin_info() with buffer set to NULL and cb_buffer set to point to a variable of type khm_size to obtain the required size of the structure.

Parameters:
[in] | plugin_name | Name of the plugin
[out] | buffer | The buffer to receive the plugin information. Set to NULL if only the size of the buffer is required.
[in,out] | cb_buffer | On entry, points to variable that specifies the size of the buffer pointed to by buffer is buffer is not NULL. On exit, holds the number of bytes copied or the required size of the buffer.
Return values:
KHM_ERROR_SUCCESS | The requested information was successfully copied to the buffer
KHM_ERROR_TOO_LONG | The buffer was either NULL or insufficient to hold the requested information. The required size of the buffer was stored in cb_buffer
KHM_ERROR_INVALID_PARAM | One or more parameters were invlaid.
KHM_ERROR_NOT_FOUND | The specified plugin was not found among the registered plugins.

KHMEXP khm_int32 KHMAPI kmm_get_plugin_info_i | ( | kmm_plugin | p,
 |  | kmm_plugin_info * | info
 | ) |  |

Obtain information about a plugin using a plugin handle.

Similar to kmm_get_plugin_info() but uses a plugin handle instead of a plugin name. If the call is successful, the info structure will be filled with information about the plugin. The returned info should not be modified in any way and may contain pointers to internal buffers.

The returned information must be released with a call to kmm_release_plugin_info_i().

KHMEXP khm_int32 KHMAPI kmm_get_plugins_config | ( | khm_int32 | flags,
 |  | khm_handle * | result
 | ) |  |

Retrieve a handle to the configuration space for plugins.

The configuration space for plugins is a container which holds the configuration subspaces for all the plugins. This is the config space which must be used to load a configuration space for a plugin.

Parameters:
[in] | flags | The flags to pass in to the call to khc_open_space(). The flags can be used to select a specific configuration store if needed.
[out] | result | Receives a handle to the configuration space. Call khc_close_space() to close the handle
See also:
khc_open_space()

khc_close_space()

KHMEXP khm_int32 KHMAPI kmm_register_module | ( | kmm_module_reg * | module,
 |  | khm_int32 | config_flags
 | ) |  |

Register a module.

The module parameter specifies the parameters for the module registration.

The plugin_info member should point to an array of kmm_plugin_info structures unless the n_plugins member is zero, in which case plugin_info can be NULL. Plugins can be registered separately using kmm_register_plugin().

Parameters:
[in] | module | Information about the module. The name and path fields are required. The plugin_info field can only be NULL if n_plugins is zero.
[in] | config_flags | Flags used to call khc_open_space(). This can be used to choose the configuration store in which the module registration will be performed.

KHMEXP khm_int32 KHMAPI kmm_register_plugin | ( | kmm_plugin_reg * | plugin,
 |  | khm_int32 | config_flags
 | ) |  |

Register a plugin.

The plugin member defines the plugin to be registered. The msg_proc and icon members of the structure are ignored.

At the time kmm_register_plugin() is called, the module specified by module member of the plugin parameter must have been already registered. Otherwise the function call fails.

If the plugin has already been registered, then all the fields in the plugin registration will be updated to be in sync with the information provided in the plugin parameter. The failure counts and associated statistics will not be reset when the configuration information is updated.

If the plugin has not been registered, the a new registration entry is created in the configuration space indicated by the config_flags parameter. In addition, the plugin will be added to the list of plugins associated with the owning module.

Note that the module that owns the plugin must be registered in the same configuration store as the plugin.

Parameters:
[in] | plugin | Registration info for the plugin. The msg_proc and icon members are ignored. All other fields are required. The description member should be localized to the system locale when registering a plugin in the machine configuration store and should be localized to the user locale when registering a plugin in the user configuration store.
[in] | config_flags | Flags for the configuration provider. These flags are used verbatim to call khc_open_space(), hence they may be used to pick whether or not the registration is per machine or per user.
See also:
kmm_register_module()

KHMEXP khm_int32 KHMAPI kmm_release_module_info_i ( kmm_module_info * info )

Release module information.

Releases the information returned by a previous call to kmm_get_module_info_i(). The contents of the kmm_module_info structure should not have been modified in any way between calling kmm_get_module_info_i() and kmm_release_module_info_i().

KHMEXP khm_int32 KHMAPI kmm_release_plugin_info_i ( kmm_plugin_info * info )

Release plugin information returned by kmm_get_plugin_info_i.

The information returned by kmm_get_plugin_info_i() should not be modified in any way before calling kmm_release_plugin_info_i(). Once the call completes, the contents of info will be initialized to zero.

KHMEXP khm_int32 KHMAPI kmm_unregister_module | ( | wchar_t * | module,
 |  | khm_int32 | config_flags
 | ) |  |

Unregister a module.

Registration information associated with the module as well as all the plugins provided by the module will be removed from the configuration store.

Parameters:
[in] | module | Names the module to be removed
[in] | config_flags | Flags used to call khc_open_space(). Can be used to choose the configuration store affected by the call.
Note:
kmm_unregister_module() has no effect on the loaded state of the module. The caller should make sure that the module is unloaded and in a state where it can be unregistered.

KHMEXP khm_int32 KHMAPI kmm_unregister_plugin | ( | wchar_t * | plugin,
 |  | khm_int32 | config_flags
 | ) |  |

Unregister a plugin.

Registration information associated with the plugin will be removed. In addtion, the plugin will be removed from the list of plugins provided by the owner module.

Parameters:
[in] | plugin | Names the plugin to be removed
[in] | config_flags | Flags used to call khc_open_space(). Can be used to choose the configuraiton store that is affected by the call.
Note:
kmm_unregister_plugin() has no effect on whether the plugin is loaded or not. The caller must make sure that the plugin is unloaded and the associated module is either also unloaded or in a state where the plugin can be unregistered.

Generated on Mon Oct 22 22:56:47 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Internationalization support

Internationalization support
[NetIDMgr Module Manager]

Detailed Description

See Localization for more information about internationalization.

Data Structures

struct | kmm_module_locale
Locale descriptor record. More...

Convenience Macros

#define | kmm_LoadAccelerators(module, lpTableName) (LoadAccelerators(kmm_get_resource_hmodule(module), lpTableName))
Convenience macro for using calling LoadAccelerators using a module handle.
#define | kmm_LoadBitmap(module, lpBitmapName) (LoadBitmap(kmm_get_resource_hmodule(module), lpBitmapName))
Convenience macro for using calling LoadBitmap using a module handle.
#define | kmm_LoadImage(module, lpszName, uType, cxDesired, cyDesired, fuLoad) (LoadImage(kmm_get_resource_hmodule(module), lpszName, uType, cxDesired, cyDesired, fuLoad))
Convenience macro for using calling LoadImage using a module handle.
#define | kmm_LoadCursor(module, lpCursorName) (LoadCursor(kmm_get_resource_hmodule(module), lpCursorName))
Convenience macro for using calling LoadCursor using a module handle.
#define | kmm_LoadIcon(module, lpIconName) (LoadIcon(kmm_get_resource_hmodule(module), lpIconName))
Convenience macro for using calling LoadIcon using a module handle.
#define | kmm_LoadMenu(module, lpMenuName) (LoadMenu(kmm_get_resource_hmodule(module), lpMenuName))
Convenience macro for using calling LoadMenu using a module handle.
#define | kmm_LoadString(module, uID, lpBuffer, nBufferMax) (LoadString(kmm_get_resource_hmodule(module), uID, lpBuffer, nBufferMax))
Convenience macro for using calling LoadString using a module handle.

Defines

#define | LOCALE_DEF(language_id, filename, flags) {language_id, filename, flags}
#define | KMM_MLOC_FLAG_DEFAULT 1
Default (fallback) locale.

Functions

KHMEXP khm_int32 KHMAPI | kmm_set_locale_info (kmm_module module, kmm_module_locale *locales, khm_int32 n_locales)
Sets the locale for a loaded module.
KHMEXP HMODULE KHMAPI | kmm_get_resource_hmodule (kmm_module m)
Return the Windows module handle of the resource library of a NetIDMgr module.

Define Documentation

#define kmm_LoadAccelerators | ( | module,
 |  | lpTableName | ) | (LoadAccelerators(kmm_get_resource_hmodule(module), lpTableName))

Convenience macro for using calling LoadAccelerators using a module handle.

Parameters:
[in] module A handle to a loaded module. The corresponding resource module will be located through a call to kmm_get_resource_hmodule()

#define kmm_LoadBitmap | ( | module,
 |  | lpBitmapName | ) | (LoadBitmap(kmm_get_resource_hmodule(module), lpBitmapName))

Convenience macro for using calling LoadBitmap using a module handle.

Parameters:
[in] module A handle to a loaded module. The corresponding resource module will be located through a call to kmm_get_resource_hmodule()

#define kmm_LoadCursor | ( | module,
 |  | lpCursorName | ) | (LoadCursor(kmm_get_resource_hmodule(module), lpCursorName))

Convenience macro for using calling LoadCursor using a module handle.

Parameters:
[in] module A handle to a loaded module. The corresponding resource module will be located through a call to kmm_get_resource_hmodule()

#define kmm_LoadIcon | ( | module,
 |  | lpIconName | ) | (LoadIcon(kmm_get_resource_hmodule(module), lpIconName))

Convenience macro for using calling LoadIcon using a module handle.

Parameters:
[in] module A handle to a loaded module. The corresponding resource module will be located through a call to kmm_get_resource_hmodule()

#define kmm_LoadImage | ( | module,
 |  | lpszName,
 |  | uType,
 |  | cxDesired,
 |  | cyDesired,
 |  | fuLoad | ) | (LoadImage(kmm_get_resource_hmodule(module), lpszName, uType, cxDesired, cyDesired, fuLoad))

Convenience macro for using calling LoadImage using a module handle.

Parameters:
[in] module A handle to a loaded module. The corresponding resource module will be located through a call to kmm_get_resource_hmodule()

#define kmm_LoadMenu | ( | module,
 |  | lpMenuName | ) | (LoadMenu(kmm_get_resource_hmodule(module), lpMenuName))

Convenience macro for using calling LoadMenu using a module handle.

Parameters:
[in] module A handle to a loaded module. The corresponding resource module will be located through a call to kmm_get_resource_hmodule()

#define kmm_LoadString | ( | module,
 |  | uID,
 |  | lpBuffer,
 |  | nBufferMax | ) | (LoadString(kmm_get_resource_hmodule(module), uID, lpBuffer, nBufferMax))

Convenience macro for using calling LoadString using a module handle.

Parameters:
[in] module A handle to a loaded module. The corresponding resource module will be located through a call to kmm_get_resource_hmodule()

Function Documentation

KHMEXP HMODULE KHMAPI kmm_get_resource_hmodule ( kmm_module m )

Return the Windows module handle of the resource library of a NetIDMgr module.

NetIDMgr allows the specification of an alternate resource library that will be used to load localized resources from. This function returns a handle to this library.

While you can use the convenience macros to access resources in a localization library using the module handle, it is recommended, for performance reasons, to use this function to obtain the handle to the resource library and then use that handle in calls to LoadString, LoadImage etc. directly.

KHMEXP khm_int32 KHMAPI kmm_set_locale_info | ( | kmm_module | module,
 |  | kmm_module_locale * | locales,
 |  | khm_int32 | n_locales
 | ) |  |

Sets the locale for a loaded module.

The given locale records are searched in the given order until a locale that matches the current user locale is found. If no locales match, then the first locale with the KMM_MLOC_FLAG_DEFAULT flag set will be loaded. If no locales have that flag set, then the first locale is loaded.

You can obtain a handle to the loaded library using kmm_get_resource_hmodule(). This function does not return until a matched library is loaded.

Note that the kmm_module_locale structure only specifies a module name for the resource module. This resource module must exist in the same directory as the module.

Parameters:
[in] | module | The module handle
[in] | locales | An array of kmm_module_locale objects
[in] | n_locales | The number of objects in the array pointed to by locales
Return values:
KHM_ERROR_SUCCESS | Succeeded.
KHM_ERROR_NOT_FOUND | A matching locale resource library was not found.
KHM_ERROR_INVALID_OPERATION | The function was called on a module which is currently not being initalized.
See also:
Localization

kmm_get_resource_hmodule()

Note:
This can only be called when handing init_module()

Generated on Mon Oct 22 22:56:47 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: kmm_module_locale Struct Reference

kmm_module_locale Struct Reference
[Internationalization support]

#include <kmm.h>

Detailed Description

Locale descriptor record.

See kmm_set_locale()

Data Fields

khm_ui_4 language
wchar_t * filename
khm_int32 flags

Field Documentation

khm_ui_4 kmm_module_locale::language

A language ID. On Windows, you can use the MAKELANGID macro to generate this value.

wchar_t* kmm_module_locale::filename

The filename corresponding to this language. Use NULL to indicate that resources for this language are to be found in the main module.

khm_int32 kmm_module_locale::flags

Flags. Combination of KMM_MLOC_FLAG_*

The documentation for this struct was generated from the following file:
  • kmm.h
Generated on Mon Oct 22 22:56:48 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: NetIDMgr Plugin Callbacks

NetIDMgr Plugin Callbacks
[NetIDMgr Module Manager]

Detailed Description

See the following related documentation pages for more information about NetIDMgr plugins.

These are prototypes of functions that must be implemented by a NetIDMgr plugin.

  • plugins

Defines

#define | EXP_INIT_MODULE "_init_module@4"
#define | EXP_EXIT_MODULE "_exit_module@4"

Typedefs

typedef khm_int32(KHMAPI * | init_module_t )(kmm_module)
Type for init_module().
typedef kmq_callback_t | _plugin_proc_t
Type for init_plugin().
typedef khm_int32(KHMAPI * | exit_module_t )(kmm_module)
Type for exit_module().

Functions

KHMEXP_EXP khm_int32
KHMAPI 		init_module (kmm_module h_module)
Initialize the module.
KHMEXP_EXP khm_int32
KHMAPI 		_plugin_proc (khm_int32 msg_type, khm_int32 msg_subtype, khm_ui_4 uparam, void *vparam)
Plugin procedure.
KHMEXP_EXP khm_int32
KHMAPI 		exit_module (kmm_module h_module)
Exit a module.

Function Documentation

KHMEXP_EXP khm_int32 KHMAPI _plugin_proc | ( | khm_int32 | msg_type,
 |  | khm_int32 | msg_subtype,
 |  | khm_ui_4 | uparam,
 |  | void * | vparam
 | ) |  |

Plugin procedure.

This is the message processor for a plugin. See Plug-ins for more information.

Essentially, this is a message subscriber for KMQ messages.

KHMEXP_EXP khm_int32 KHMAPI exit_module ( kmm_module h_module )

Exit a module.

This is the last callback function that the NetIDMgr module manager calls before unloading the module. When this function is called, all of the plugins for the module have already been stopped. However, any localization libraries that were loaded as a result of init_module() calling kmm_set_locale_info() will still be loaded. These localization libraries will be unloaded immediately after this callback returns.

Use this callback to perform any required cleanup tasks. However, it is advisable that each plugin perform its own cleanup tasks, since each plugin may be stopped independently of others.

Returns:
The return value of this function is ignored.
Note:
This callback is not required.

KHMEXP_EXP khm_int32 KHMAPI init_module ( kmm_module h_module )

Initialize the module.

This is the first callback function to be called in a module. Perform all the required intialization when this is called. As mentioned in plugins, you should not attempt to call any NetIDMgr API function from DLLMain or other initialization code other than this one.

You should use this call back to register the plugins that will be implemented in this module and to notify the plugin manager of any resource libraries that this module will use.

Call:

  • kmm_set_locale() : to set the notify the plugin manager of the locale specifc resource libraries that are used by this module.
  • kmm_provide_plugin() : to register each plugin that is implemented in this module.

This function is called in the context of the current user, from the plug-in manager thread. This same thread is used by the plug-in manager to load and initialize all the modules for a session.

The name of the callback must be init_module(). The calling convention is KHMAPI, which is currently __stdcall.

If this function does not register any plugins, the plugin manager will immediately call exit_module() and unload the module even if the init_module() function completes successfully.

Returns:
Return the following values to indicate whether the module successfully initialized or not.
  • KHM_ERROR_SUCCESS : Succeeded. The module manager will call init_plugin() for each of the registered plugins for the module.
  • any other error code: Signals that the module did not successfully initialize. The plugin manager will immediately call exit_module() and then unload the module.
Note:
This callback is required.

Generated on Mon Oct 22 22:56:47 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: kmm_plugin_reg Struct Reference

kmm_plugin_reg Struct Reference
[NetIDMgr Module Manager]

#include <kmm.h>

Detailed Description

Plugin registration.

See also:
khm_cred_provider

Data Fields

wchar_t * | name
wchar_t * | module
khm_int32 type
khm_int32 flags
kmq_callback_t msg_proc
wchar_t * | dependencies
wchar_t * | description
HICON | icon

Field Documentation

wchar_t* kmm_plugin_reg::name

Name of the plugin. Maximum of KMM_MAXCCH_NAME characters including the terminating NULL. Required.

wchar_t* kmm_plugin_reg::module

Name of module that owns the plugin. Maximum of KMM_MAXCCH_NAME characters including terminating NULL. Required.

khm_int32 kmm_plugin_reg::type

Type plugin type. One of KHM_PITYPE_*. Required.

khm_int32 kmm_plugin_reg::flags

Unused. Set to 0

kmq_callback_t kmm_plugin_reg::msg_proc

Message processor. Required.

wchar_t* kmm_plugin_reg::dependencies

Dependencies. Note that this is a multi string. (you can use the KHC multi string functions to manipulate multi strings or to convert a comma separated list of dependencies to a multi string). Each string in the multi string is a name of a plugin that this plugin depends on. Optional (set to NULL if this plugin has no dependencies). Maximum of KMM_MAXCCH_DEPS characters including terminating double NULL.

wchar_t* kmm_plugin_reg::description

Description of the plugin. Maximum of KMM_MAXCCH_DESC characters including the terminating NULL. Localized. Optional (set to NULL if not provided)

HICON kmm_plugin_reg::icon

Icon used to represent the plugin. Optional. (set to NULL if not provided)

The documentation for this struct was generated from the following file:
  • kmm.h
Generated on Mon Oct 22 22:56:48 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: kmm_plugin_info Struct Reference

kmm_plugin_info Struct Reference
[NetIDMgr Module Manager]

#include <kmm.h>

Detailed Description

Plugin information.

Data Fields

kmm_plugin_reg reg
khm_int32 state
khm_int32 failure_count
FILETIME failure_time
khm_int32 failure_reason
kmm_plugin h_plugin
khm_int32 flags

Field Documentation

kmm_plugin_reg kmm_plugin_info::reg

Registration info

khm_int32 kmm_plugin_info::state

Current status of the plugin. One of _kmm_plugin_states

khm_int32 kmm_plugin_info::failure_count

Number of recorded failures in the plugin

FILETIME kmm_plugin_info::failure_time

Time of first recorded failure

khm_int32 kmm_plugin_info::failure_reason

The reason for the first recorded failure

kmm_plugin kmm_plugin_info::h_plugin

Handle to plugin

khm_int32 kmm_plugin_info::flags

Flags for the plugin. Currently this can only specify KMM_PLUGIN_FLAG_DISABLED.

The documentation for this struct was generated from the following file:
  • kmm.h
Generated on Mon Oct 22 22:56:48 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: kmm_module_reg Struct Reference

kmm_module_reg Struct Reference
[NetIDMgr Module Manager]

#include <kmm.h>

Detailed Description

Module registration.

Data Fields

wchar_t * | name
wchar_t * | path
wchar_t * | description
wchar_t * | vendor
wchar_t * | support
khm_int32 n_plugins
kmm_plugin_reg * plugin_reg_info

Field Documentation

wchar_t* kmm_module_reg::name

Identifier for the module

wchar_t* kmm_module_reg::path

Full pathname to module binary

wchar_t* kmm_module_reg::description

Description of module

wchar_t* kmm_module_reg::vendor

Vendor/copyright string

wchar_t* kmm_module_reg::support

Support URL/contact

khm_int32 kmm_module_reg::n_plugins

Number of plugins that are active

kmm_plugin_reg* kmm_module_reg::plugin_reg_info

Array of kmm_plugin_reg records for each active plugin

The documentation for this struct was generated from the following file:
  • kmm.h
Generated on Mon Oct 22 22:56:48 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: kmm_module_info Struct Reference

kmm_module_info Struct Reference
[NetIDMgr Module Manager]

#include <kmm.h>

Detailed Description

Module information record.

Data Fields

kmm_module_reg reg
khm_ui_4 language
khm_int32 state
khm_version file_version
khm_version product_version
khm_int32 failure_count
FILETIME failure_time
khm_int32 failure_reason
kmm_module h_module

Field Documentation

kmm_module_reg kmm_module_info::reg

Registration info

khm_ui_4 kmm_module_info::language

Currently loaded langugage

khm_int32 kmm_module_info::state

Current status of the module

khm_version kmm_module_info::file_version

File version for the module

khm_version kmm_module_info::product_version

Product version for the module

khm_int32 kmm_module_info::failure_count

Number of times the module has failed to load

FILETIME kmm_module_info::failure_time

Time of first recorded failure

khm_int32 kmm_module_info::failure_reason

Reason for first failure. One of the module status values

kmm_module kmm_module_info::h_module

Handle to the module.

The documentation for this struct was generated from the following file:
  • kmm.h
Generated on Mon Oct 22 22:56:48 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: NetIDMgr Error Reporting

NetIDMgr Error Reporting

Detailed Description

Error reporting functions provide a mechanism to construct meaningful and user friendly error reports for the user.

Unlike most of the other NetIDMgr API's, the error reporting APIs are lightweight and usually do not return an error value. This is mostly because, these functions are called after an error occurs.

Modules

Standard Facility IDs

Data Structures

struct | kherr_param
struct | kherr_event
An event. More...
struct | kherr_context
An error context. More...

Customizable macros

#define | KHERR_FACILITY NULL
The default facility when reporting errors.
#define | KHERR_FACILITY_ID 0
The default facility ID when reporting errors.

Defines

#define | KHERR_EVENT_MAGIC 0x0423e84f
#define | KHERR_CONTEXT_MAGIC 0x34f3238c
#define | KHERR_MAXCCH_STRING 1024
Maximum length of a string field in characters including terminating NULL.
#define | KHERR_MAXCB_STRING (KHERR_MAXCCH_STRING * sizeof(wchar_t))
Maximum length of a string field in bytes including terminating NULL.
#define | _reportf_ex kherr_reportf_ex
#define | _reportf kherr_reportf
#define | _int32(i) kherr_val(KEPT_INT32, (khm_ui_8) i)
#define | _uint32(ui) kherr_val(KEPT_UINT32, (khm_ui_8) ui)
#define | _int64(i) kherr_val(KEPT_INT64, (khm_ui_8) i)
#define | _uint64(ui) kherr_val(KEPT_UINT64, (khm_ui_8) ui)
#define | _cstr(cs) kherr_val(KEPT_STRINGC, (khm_ui_8) cs)
#define | _tstr(ts) kherr_val(KEPT_STRINGT, (khm_ui_8) ts)
#define | _cptr(p) kherr_val(KEPT_PTR, (khm_ui_8) p)
#define | _vnull() kherr_val(KEPT_NONE, 0)
#define | _dupstr(s) kherr_dup_string(s)
#define | _report_cs0(severity, long_description) kherr_report((severity), NULL, KHERR_FACILITY, NULL, (long_description), NULL, KHERR_FACILITY_ID, 0, _vnull(), _vnull(), _vnull(), _vnull(), 0, NULL)
#define | _report_cs1(severity, long_description, p1) kherr_report((severity), NULL, KHERR_FACILITY, NULL, (long_description), NULL, KHERR_FACILITY_ID, 0, p1, _vnull(), _vnull(), _vnull(), 0, NULL)
#define | _report_cs2(severity, long_description, p1, p2) kherr_report((severity), NULL, KHERR_FACILITY, NULL, (long_description), NULL, KHERR_FACILITY_ID, 0, p1, p2, _vnull(), _vnull(), 0, NULL)
#define | _report_cs3(severity, long_description, p1, p2, p3) kherr_report((severity), NULL, KHERR_FACILITY, NULL, (long_description), NULL, KHERR_FACILITY_ID, 0, p1, p2, p3, _vnull(), 0, NULL)
#define | _report_cs4(severity, long_description, p1, p2, p3, p4) kherr_report((severity), NULL, KHERR_FACILITY, NULL, (long_description), NULL, KHERR_FACILITY_ID, 0, p1, p2, p3, p4, 0, NULL)
#define | _report_sr0(severity, long_desc_id) kherr_report((severity), NULL, KHERR_FACILITY, NULL, MAKEINTRESOURCE(long_desc_id), NULL, KHERR_FACILITY_ID, 0, _vnull(), _vnull(), _vnull(), _vnull(), KHERR_RF_RES_LONG_DESC, KHERR_HMODULE)
#define | _report_sr1(severity, long_desc_id, p1) kherr_report((severity), NULL, KHERR_FACILITY, NULL, MAKEINTRESOURCE(long_desc_id), NULL, KHERR_FACILITY_ID, 0, p1, _vnull(), _vnull(), _vnull(), KHERR_RF_RES_LONG_DESC, KHERR_HMODULE)
#define | _report_sr2(severity, long_desc_id, p1, p2) kherr_report((severity), NULL, KHERR_FACILITY, NULL, MAKEINTRESOURCE(long_desc_id), NULL, KHERR_FACILITY_ID, 0, p1, p2, _vnull(), _vnull(), KHERR_RF_RES_LONG_DESC, KHERR_HMODULE)
#define | _report_sr3(severity, long_desc_id, p1, p2, p3) kherr_report((severity), NULL, KHERR_FACILITY, NULL, MAKEINTRESOURCE(long_desc_id), NULL, KHERR_FACILITY_ID, 0, p1, p2, p3, _vnull(), KHERR_RF_RES_LONG_DESC, KHERR_HMODULE)
#define | _report_sr4(severity, long_desc_id, p1, p2, p3, p4) kherr_report((severity), NULL, KHERR_FACILITY, NULL, MAKEINTRESOURCE(long_desc_id), NULL, KHERR_FACILITY_ID, 0, p1, p2, p3, p4, KHERR_RF_RES_LONG_DESC, KHERR_HMODULE)
#define | _report_mr0(severity, long_desc_msg_id) kherr_report((severity), NULL, KHERR_FACILITY, NULL, (wchar_t *)(long_desc_msg_id), NULL, KHERR_FACILITY_ID, 0, _vnull(), _vnull(), _vnull(), _vnull(), KHERR_RF_MSG_LONG_DESC, KHERR_HMODULE)
#define | _report_mr1(severity, long_desc_msg_id, p1) kherr_report((severity), NULL, KHERR_FACILITY, NULL, (wchar_t *)(long_desc_msg_id), NULL, KHERR_FACILITY_ID, 0, p1, _vnull(), _vnull(), _vnull(), KHERR_RF_MSG_LONG_DESC, KHERR_HMODULE)
#define | _report_mr2(severity, long_desc_msg_id, p1, p2) kherr_report((severity), NULL, KHERR_FACILITY, NULL, (wchar_t *)(long_desc_msg_id), NULL, KHERR_FACILITY_ID, 0, p1, p2, _vnull(), _vnull(), KHERR_RF_MSG_LONG_DESC, KHERR_HMODULE)
#define | _report_mr3(severity, long_desc_msg_id, p1, p2, p3) kherr_report((severity), NULL, KHERR_FACILITY, NULL, (wchar_t *)(long_desc_msg_id), NULL, KHERR_FACILITY_ID, 0, p1, p2, p3, _vnull(), KHERR_RF_MSG_LONG_DESC, KHERR_HMODULE)
#define | _report_mr4(severity, long_desc_msg_id, p1, p2, p3, p4) kherr_report((severity), NULL, KHERR_FACILITY, NULL, (wchar_t *)(long_desc_msg_id), NULL, KHERR_FACILITY_ID, 0, p1, p2, p3, p4, KHERR_RF_MSG_LONG_DESC, KHERR_HMODULE)
#define | _report_ts0(severity, long_desc_ptr) kherr_report((severity), NULL, KHERR_FACILITY, NULL, (long_desc_ptr), NULL, KHERR_FACILITY_ID, 0, _vnull(), _vnull(), _vnull(), _vnull(), KHERR_RF_FREE_LONG_DESC, NULL)
#define | _report_ts1(severity, long_desc_ptr, p1) kherr_report((severity), NULL, KHERR_FACILITY, NULL, (long_desc_ptr), NULL, KHERR_FACILITY_ID, 0, p1, _vnull(), _vnull(), _vnull(), KHERR_RF_FREE_LONG_DESC, NULL)
#define | _report_ts2(severity, long_desc_ptr, p1, p2) kherr_report((severity), NULL, KHERR_FACILITY, NULL, (long_desc_ptr), NULL, KHERR_FACILITY_ID, 0, p1, p2, _vnull(), _vnull(), KHERR_RF_FREE_LONG_DESC, NULL)
#define | _report_ts3(severity, long_desc_ptr, p1, p2, p3) kherr_report((severity), NULL, KHERR_FACILITY, NULL, (long_desc_ptr), NULL, KHERR_FACILITY_ID, 0, p1, p2, p3, _vnull(), KHERR_RF_FREE_LONG_DESC, NULL)
#define | _report_ts4(severity, long_desc_ptr, p1, p2, p3, p4) kherr_report((severity), NULL, KHERR_FACILITY, NULL, (long_desc_ptr), NULL, KHERR_FACILITY_ID, 0, p1, p2, p3, p4, KHERR_RF_FREE_LONG_DESC, NULL)
#define | _suggest_cs(cs, sid) kherr_suggest((cs), (sid), KHERR_RF_CSTR_SUGGEST)
#define | _suggest_ts(ts, sid) kherr_suggest((ts), (sid), KHERR_RF_FREE_SUGGEST)
#define | _suggest_sr(sr, sid) kherr_suggest(MAKEINTRESOURCE(sr), (sid), KHERR_RF_RES_SUGGEST)
#define | _suggest_mr(mr, sid) kherr_suggest((wchar_t *)(DWORD_PTR)(mr), (sid), KHERR_RF_MSG_SUGGEST)
#define | _location(l) kherr_location(l)
#define | _facility(f, fid) kherr_facility((f),(fid))
#define | _describe kherr_set_desc_event
#define | _del_event kherr_del_last_event
#define | _begin_task kherr_push_new_context
#define | _end_task kherr_pop_context
#define | _progress(num, denom) kherr_set_progress((num),(denom))
#define | _resolve kherr_evaluate_last_event

Typedefs

typedef enum
tag_kherr_severity 		kherr_severity
typedef enum
tag_kherr_suggestion 		kherr_suggestion
typedef khm_ui_4 | kherr_serial
Serial number for error contexts.
typedef void(KHMAPI * | kherr_ctx_handler )(enum kherr_ctx_event, kherr_context *)
Context event handler.

Enumerations

enum kherr_parm_types {
KEPT_NONE = 0, KEPT_INT32 = 1, KEPT_UINT32, KEPT_INT64,
KEPT_UINT64, KEPT_STRINGC, KEPT_STRINGT, KEPT_PTR
}
The default module handle. More...
enum tag_kherr_severity {
KHERR_FATAL = 0, KHERR_ERROR, KHERR_WARNING, KHERR_INFO,
KHERR_DEBUG_1 = 64, KHERR_DEBUG_2 = 65, KHERR_DEBUG_3 = 66, KHERR_RESERVED_BANK = 127,
KHERR_NONE = 128
}
Severity levels. More...
enum tag_kherr_suggestion {
KHERR_SUGGEST_NONE = 0, KHERR_SUGGEST_ABORT, KHERR_SUGGEST_RETRY, KHERR_SUGGEST_IGNORE,
KHERR_SUGGEST_INTERACT, KHERR_SUGGEST_OTHER
}
Suggestions. More...
enum kherr_event_flags {
KHERR_RF_CSTR_SHORT_DESC = 0x00000000, KHERR_RF_RES_SHORT_DESC = 0x00000001, KHERR_RF_MSG_SHORT_DESC = 0x00000002, KHERR_RF_FREE_SHORT_DESC = 0x00000004,
KHERR_RFMASK_SHORT_DESC = 0x00000007, KHERR_RF_CSTR_LONG_DESC = 0x00000000, KHERR_RF_RES_LONG_DESC = 0x00000008, KHERR_RF_MSG_LONG_DESC = 0x00000010,
KHERR_RF_FREE_LONG_DESC = 0x00000020, KHERR_RFMASK_LONG_DESC = 0x00000038, KHERR_RF_CSTR_SUGGEST = 0x00000000, KHERR_RF_RES_SUGGEST = 0x00000040,
KHERR_RF_MSG_SUGGEST = 0x00000080, KHERR_RF_FREE_SUGGEST = 0x00000100, KHERR_RFMASK_SUGGEST = 0x000001C0, KHERR_RF_STR_RESOLVED = 0x00010000,
KHERR_RF_CONTEXT_FOLD = 0x00020000, KHERR_RF_INERT = 0x00040000, KHERR_RF_COMMIT = 0x00080000
}
Flags for kherr_event. More...
enum kherr_context_flags {
KHERR_CF_NONE = 0x00000000, KHERR_CF_DIRTY = 0x00000001, KHERR_CF_OWN_PROGRESS = 0x00000002, KHERR_CF_UNBOUND = 0x00000004,
KHERR_CF_TRANSITIVE = 0x00000008, KHERR_CFMASK_INITIAL = 0x0000000a
}
enum kherr_ctx_event {
KHERR_CTX_BEGIN = 0x00000001, KHERR_CTX_DESCRIBE = 0x00000002, KHERR_CTX_END = 0x00000004, KHERR_CTX_ERROR = 0x00000008,
KHERR_CTX_EVTCOMMIT = 0x00000010, KHERR_CTX_NEWCHILD = 0x00000020, KHERR_CTX_FOLDCHILD = 0x00000040, KHERR_CTX_PROGRESS = 0x00000080
}
Context event. More...

Functions

KHMEXP void KHMAPI | kherr_add_ctx_handler (kherr_ctx_handler h, khm_int32 filter, kherr_serial serial)
Add a context event handler.
KHMEXP void KHMAPI | kherr_remove_ctx_handler (kherr_ctx_handler h, kherr_serial serial)
Remove a context event handler.
KHMEXP kherr_event
*KHMAPI 		kherr_report (kherr_severity severity, const wchar_t *short_desc, const wchar_t *facility, const wchar_t *location, const wchar_t *long_desC, const wchar_t *suggestion, khm_int32 facility_id, kherr_suggestion suggestion_id, kherr_param p1, kherr_param p2, kherr_param p3, kherr_param p4, khm_int32 flags, HMODULE h_module)
Report an error.
KHMEXP kherr_event
*__cdecl 		kherr_reportf_ex (kherr_severity severity, const wchar_t *facility, khm_int32 facility_id, HMODULE hModule, const wchar_t *long_desc_fmt,...)
Report a formatted message.
KHMEXP kherr_event
*__cdecl 		kherr_reportf (const wchar_t *long_desc_fmt,...)
Report a formatted message.
KHMEXP kherr_param | kherr_dup_string (const wchar_t *s)
Create a parameter out of a transient string.
__inline KHMEXP
kherr_param 		kherr_val (khm_octet ptype, khm_ui_8 pvalue)
KHMEXP void KHMAPI | kherr_suggest (wchar_t *suggestion, khm_int32 suggestion_id, khm_int32 flags)
Set the suggestion and suggestion identifier for the last event.
KHMEXP void KHMAPI | kherr_location (wchar_t *location)
Set the location string for the last event.
KHMEXP void KHMAPI | kherr_facility (wchar_t *facility, khm_int32 facility_id)
Set the facility string and identifier for the last event.
KHMEXP void KHMAPI | kherr_set_desc_event (void)
Marks the last event as the descriptor event for the current error context.
KHMEXP void KHMAPI | kherr_del_last_event (void)
Delete the last event.
KHMEXP kherr_context
*KHMAPI 		kherr_create_new_context (khm_int32 flags)
Create a new context.
KHMEXP void KHMAPI | kherr_hold_context (kherr_context *c)
Obtain a hold on a context.
KHMEXP void KHMAPI | kherr_release_context (kherr_context *c)
Release a context.
KHMEXP void KHMAPI | kherr_push_new_context (khm_int32 flags)
Push an empty context.
KHMEXP void KHMAPI | kherr_push_context (kherr_context *c)
Push a context.
KHMEXP void KHMAPI | kherr_pop_context (void)
Pop a context.
KHMEXP kherr_context
*KHMAPI 		kherr_peek_context (void)
Retrieve the current error context.
KHMEXP khm_boolean KHMAPI | kherr_is_error (void)
Check if the current error context indicates an error.
KHMEXP khm_boolean KHMAPI | kherr_is_error_i (kherr_context *c)
Check if an error context indicates an error.
KHMEXP void KHMAPI | kherr_clear_error (void)
Clear the error state of the current context.
KHMEXP void KHMAPI | kherr_clear_error_i (kherr_context *c)
Clear the error state of an error context.
KHMEXP void KHMAPI | kherr_set_progress (khm_ui_4 num, khm_ui_4 denom)
Set the progress meter of the current error context.
KHMEXP void KHMAPI | kherr_get_progress (khm_ui_4 *num, khm_ui_4 *denom)
Get the progress meter of the current error context.
KHMEXP void KHMAPI | kherr_get_progress_i (kherr_context *c, khm_ui_4 *num, khm_ui_4 *denom)
Get the progress meter of an error context.
KHMEXP kherr_event
*KHMAPI 		kherr_get_first_event (kherr_context *c)
Get the first event in a context.
KHMEXP kherr_event
*KHMAPI 		kherr_get_next_event (kherr_event *e)
Get the next event.
KHMEXP kherr_event
*KHMAPI 		kherr_get_prev_event (kherr_event *e)
Get the previous event.
KHMEXP kherr_event
*KHMAPI 		kherr_get_last_event (kherr_context *c)
Get the last event in an error context.
KHMEXP kherr_context
*KHMAPI 		kherr_get_first_context (kherr_context *c)
Get the first child context of a context.
KHMEXP kherr_context
*KHMAPI 		kherr_get_next_context (kherr_context *c)
Get the next sibling context of a context.
KHMEXP kherr_event
*KHMAPI 		kherr_get_desc_event (kherr_context *c)
Get the desciption event for the context.
KHMEXP kherr_event
*KHMAPI 		kherr_get_err_event (kherr_context *c)
Get the error event for the context.
KHMEXP void KHMAPI | kherr_evaluate_event (kherr_event *e)
Evaluate an event.
KHMEXP void KHMAPI | kherr_evaluate_last_event (void)
Evaluate the last event.

Define Documentation

#define KHERR_FACILITY NULL

The default facility when reporting errors.

When including this header file, if the KHERR_FACILITY macro is defined to be a wide character string, then it will be used as the default facility when for the convenience macros. All of the calls to the convenience macros in the source file would then have that facility.

If left undefined, the convenience macros will leave the facility value undefined.

#define KHERR_FACILITY_ID 0

The default facility ID when reporting errors.

When including this header file, if the KHERR_FACILITY_ID macro is defined to be non-zero, then it will be used as the default facility identifier for the convenience macros. All of the calls to the convenience macros in the source file would then have that facility identifier.

The default value of 0 means that the facility is undefined.

Typedef Documentation

typedef void(KHMAPI * kherr_ctx_handler)(enum kherr_ctx_event, kherr_context *)

Context event handler.

Context event handlers are invoked when specific events occur with respect to an error context. The kherr_ctx_event parameter specifies which event occurred using one of the event values described in the enumeration. The error context in which this event occurred is specified by the kherr_context pointer.

Note that if the handler needs to keep track of the error context for later processing, it also needs to keep track of the serial field of the error context. The same context object may be reused, but the serial number is guaranteed to be unique.

See also:
kherr_add_ctx_handler()

Enumeration Type Documentation

enum kherr_context_flags

Enumerator:
KHERR_CF_NONE | None.
KHERR_CF_DIRTY | Used Internally. Denotes that the err_event and severity may need to be recalculated. Cannot be set as an initial flag.
KHERR_CF_OWN_PROGRESS | The context maintains its own progress meter as opposed to one that is derived from child contexts.
KHERR_CF_UNBOUND | Unbound context. The context can't be used to log events. Call kherr_push_context() to associate the context with the global context hierarchy. Cannot be set as an initial flag.
KHERR_CF_TRANSITIVE | Transitive. The context is automatically made the current context for all other threads that handle messages sent or posted by threads whose current error context is this one.
KHERR_CFMASK_INITIAL | Allowed initial flags

enum kherr_ctx_event

Context event.

See also:
kherr_add_ctx_handler()
Enumerator:
KHERR_CTX_BEGIN | A new context was created
KHERR_CTX_DESCRIBE | A context was described
KHERR_CTX_END | A context was closed
KHERR_CTX_ERROR | A context switched to an error state
KHERR_CTX_EVTCOMMIT | A event was committed into the context
KHERR_CTX_NEWCHILD | A new child context was created
KHERR_CTX_FOLDCHILD | A child context was folded
KHERR_CTX_PROGRESS | Progress marker updated for context

enum kherr_event_flags

Flags for kherr_event.

Each set of flags that define the type of resource for one value is mutually exclusive.

Enumerator:
KHERR_RF_CSTR_SHORT_DESC | Short description is a constant string
KHERR_RF_RES_SHORT_DESC | Short description is a string resource
KHERR_RF_MSG_SHORT_DESC | Short description is a message resource
KHERR_RF_FREE_SHORT_DESC | Short description is an allocated string
KHERR_RF_CSTR_LONG_DESC | Long description is a constant string
KHERR_RF_RES_LONG_DESC | Long description is a string resource
KHERR_RF_MSG_LONG_DESC | Long description is a message resouce
KHERR_RF_FREE_LONG_DESC | Long description is an allocated string
KHERR_RF_CSTR_SUGGEST | Suggestion is a constant string
KHERR_RF_RES_SUGGEST | Suggestion is a string resource
KHERR_RF_MSG_SUGGEST | Suggestion is a message resource
KHERR_RF_FREE_SUGGEST | Suggestion is an allocated string
KHERR_RF_STR_RESOLVED | The string resources in the event have been resolved.
KHERR_RF_CONTEXT_FOLD | The event is a representation of a folded context.
KHERR_RF_INERT | Inert event. The event has already been dealt with and is no longer considered significant.
KHERR_RF_COMMIT | Committed event. The commit handlers for this event have already been called.

enum kherr_parm_types

The default module handle.

KHERR_HMODULE (undefined)

When including this header file, if the KHERR_HMODULE macro is defined to be an identifier that holds the module handle, then the convenience macros that specify a module handle will use it.

A default value is not defined for KHERR_HMODULE. Any attempt to invoke any of the convenience macros that use it should generate a compile time error.

Parameter types

Enumerator:
KEPT_STRINGC | String constant
KEPT_STRINGT | String. Will be freed using free() when the event is freed
KEPT_PTR | Pointer type.

enum tag_kherr_severity

Severity levels.

Larger the value, the less severe it is.

Enumerator:
KHERR_FATAL | Fatal error.
KHERR_ERROR | Non-fatal error. We'll probably survive. See the suggested action.
KHERR_WARNING | Warning. Something almost broke or soon will. See the suggested action.
KHERR_INFO | Informational. Something happened that we would like you to know about.
KHERR_DEBUG_1 | Verbose debug level 1 (high) Events at this severity level are not required to be based on localized strings.
KHERR_DEBUG_2 | Verbose debug level 2 (medium) Events at this severity level are not required to be based on localized strings.
KHERR_DEBUG_3 | Verbose debug level 3 (low) Events at this severity level are not required to be based on localized strings.
KHERR_RESERVED_BANK | Internal use
KHERR_NONE | Nothing interesting has happened so far

enum tag_kherr_suggestion

Suggestions.

Enumerator:
KHERR_SUGGEST_NONE | No suggestions.
KHERR_SUGGEST_ABORT | Abort whatever it was you were trying. It's not gonna work.
KHERR_SUGGEST_RETRY | Retry. It might work the second or third time over
KHERR_SUGGEST_IGNORE | Ignore. It might go away.
KHERR_SUGGEST_INTERACT | Further user interaction is necessary to resolve the situation. The suggest string in the event should be prompted to the user.
KHERR_SUGGEST_OTHER | Something else.

Function Documentation

KHMEXP void KHMAPI kherr_add_ctx_handler | ( | kherr_ctx_handler | h,
 |  | khm_int32 | filter,
 |  | kherr_serial | serial
 | ) |  |

Add a context event handler.

An application can register an event handler that gets notified of events that pertain to error contexts. More than one handler can be registered. The order in which the handlers are called is undefined for any specific event.

These event occur in the context of individual application threads. The handler will be called from within the thread that caused the event. Therefore it is important that the handler is both reentrant and returns quickly.

The events that the handler will be notified of are explained below:

KHERR_CTX_BEGIN: Notification that a new context was created. A pointer to the context will be supplied to the handler. The supplied pointer should not be used to obtain a hold on the context, as it will prevent the context from being closed.

KHERR_CTX_DESCRIBE: The thread called kherr_set_desc_event() to set the description of a context. Once again, the pointer should not be used to obtain a hold on the context.

KHERR_CTX_ERROR: The last event that was reported for the context was an error event (the severity was was equal or higher than KHERR_ERROR). The pointer may be used to obtain a hold on the context. However, it is the application's resonsibility to make sure that the hold is released later. Otherwise the event will never be closed.

KHERR_CTX_END: Closure. This event is signalled when the last open handle to the context is closed and there is no thread that is currently active which has this context in its error context stack. At the time the handler is invoked, the context is still intact. The pointer that is supplied should not be used to obtain a handle on the context.

KHERR_CTX_EVTCOMMIT: An event was committed into the error context. An event is committed when another event is reported after the event, or if the context is closed. Since the last event that is reported can still be modified by adding new information, the event remains open until it is no longer the last event or the context is no longer active. When this notification is received, the last event in the context's event queue is the event that was committed.

Parameters:
[in] | h | Context event handler, of type kherr_ctx_handler
[in] | filter | A combination of kherr_ctx_event values indication which notifications should be sent to the handler. If a filter value of zero is provided, all of the events will be sent to the handler.
[in] | serial | The serial number of the error context that should be tracked. If this is zero, all error contexts can trigger the handler.

KHMEXP kherr_context* KHMAPI kherr_create_new_context ( khm_int32 flags )

Create a new context.

The created context is not bound to any thread or any context hierarchy. Hence it cannot be used to capture any events until it is used in a call to kherr_push_context().

Release the returned context pointer with a call to kherr_release_context().

Parameters:
[in] flags Initial flags for the context. Combination of kherr_context_flags
Note:
This function is for internal use only.

KHMEXP void KHMAPI kherr_del_last_event ( void )

Delete the last event.

The event that will be deleted is the last event reported by the calling thread.

KHMEXP kherr_param kherr_dup_string ( const wchar_t * s )

Create a parameter out of a transient string.

A parameter is created by duplicating the string that is passed into the function. If the string exceeds KHERR_MAXCCH_STRING, then only the first part of the string that fits within the limit is duplicated.

The resulting kherr_param must be passed in to kherr_report(). The event logging framework will free the duplicated string once the data is no longer required.

KHMEXP void KHMAPI kherr_evaluate_event ( kherr_event * e )

Evaluate an event.

When an event is reported, all the parameters and resource references that were passed to kherr_report() are kept as-is until the actual string values are required by the error reporting library. However, if the string fields are required before then, an application can call kherr_evaluate_event() to get them.

This function does the following:

  • Load any referenced string or message resources that are referenced in the event's short description, long description or suggestion.

  • Expand any inserts using the parameters that were passed in.

  • Free up allocated strings in for the descriptions or suggestion fields and any parameters.

  • Update the string fields in the event to contain the newly generated strings.

KHMEXP void KHMAPI kherr_evaluate_last_event ( void )

Evaluate the last event.

Same as kherr_evaluate_event(), but operates on the last event logged by the current thread.

See also:
kherr_evaluate_event()

KHMEXP void KHMAPI kherr_facility | ( | wchar_t * | facility,
 |  | khm_int32 | facility_id
 | ) |  |

Set the facility string and identifier for the last event.

The event that will be modified is the last event reported by the calling thread.

KHMEXP kherr_event* KHMAPI kherr_get_desc_event ( kherr_context * c )

Get the desciption event for the context.

The description event is the event that was denoted using kherr_set_desc_event() as the event which describes the context.

The returned pointer is only valid as long as there is a hold on c. Once the context is released with a call to kherr_release_context() all pointers to events in the context becomes invalid.

KHMEXP kherr_event* KHMAPI kherr_get_err_event ( kherr_context * c )

Get the error event for the context.

The error event for a context is the last event that had the highest severity level.

The returned pointer is only valid as long as there is a hold on c. Once the context is released with a call to kherr_release_context() all pointers to events in the context becomes invalid.

KHMEXP kherr_context* KHMAPI kherr_get_first_context ( kherr_context * c )

Get the first child context of a context.

Contexts are arranged in a hiearchy. This function returns the first child of an error context. Use kherr_get_next_context() to obtain the other contexts. If c is NULL, this returns the first root level context.

The returned pointer must be released with a call to kherr_release_context()

KHMEXP kherr_event* KHMAPI kherr_get_first_event ( kherr_context * c )

Get the first event in a context.

The returned pointer is only valid as long as there is a hold on c. Once the context is released with a call to kherr_release_context() all pointers to events in the context become invalid.

In addition, the last event in a context may still be "active". A thread can still modify the last event as long as the context is active.

See also:
kherr_get_next_event(), kherr_get_prev_event(), kherr_get_last_event()

KHMEXP kherr_event* KHMAPI kherr_get_last_event ( kherr_context * c )

Get the last event in an error context.

Returns a pointer to the last error event that that was reported to the context c.

The returned pointer is only valid as long as there is a hold on the error context. Once the context is released with a call to kherr_release_context(), all pointers to events in the context become invalid.

In addtion, the last event in a context may still be "active". A thread can still modify the last event as long as the context is active.

See also:
kherr_get_first_event(), kherr_get_next_event(), kherr_get_prev_event()

KHMEXP kherr_context* KHMAPI kherr_get_next_context ( kherr_context * c )

Get the next sibling context of a context.

The returned pointer must be released with a call to kherr_release_context()

See also:
kherr_get_first_context()

KHMEXP kherr_event* KHMAPI kherr_get_next_event ( kherr_event * e )

Get the next event.

Call kherr_get_first_event() to obtain the first event in a context. Subsequent calls to kherr_get_next_event() will yield other events in the order in which they were reported. The list ends when kherr_get_next_event() returns NULL.

The returned pointer is only valid as long as there is a hold on c. Once the context is released with a call to kherr_release_context() all pointers to events in the context become invalid.

In addition, the last event in a context may still be "active". A thread can still modify the last event as long as the context is active.

See also:
kherr_get_first_event(), kherr_get_prev_event(), kherr_get_last_event()

KHMEXP kherr_event* KHMAPI kherr_get_prev_event ( kherr_event * e )

Get the previous event.

Returns a pointer to the event that was reported in the context containing e prior to e being reported.

The returned pointer is only valid as long as there is a hold on the error context. Once the context is released with a call to kherr_release_context() all pointers to events in the context become invalid.

In addition, the last event in a context may still be "active". A thread can still modify the last event as long as the context is active.

See also:
kherr_get_first_event(), kherr_get_next_event(), kherr_get_last_event()

KHMEXP void KHMAPI kherr_get_progress | ( | khm_ui_4 * | num,
 |  | khm_ui_4 * | denom
 | ) |  |

Get the progress meter of the current error context.

This is equivalent to calling kherr_get_progress_i() for the current error context. I.e. :

    kherr_context * ctx;

    ctx = kherr_peek_context();
    kherr_get_progress_i(ctx, &num, &denom);
    kherr_release_context(ctx);

See also:
kherr_get_progress_i()

KHMEXP void KHMAPI kherr_get_progress_i | ( | kherr_context * | c,
 |  | khm_ui_4 * | num,
 |  | khm_ui_4 * | denom
 | ) |  |

Get the progress meter of an error context.

The progress meter for the current context can be set by calling kherr_set_progress() (or using the _progress macro). The progress value returned by this function is as follows:

If one or more of the following conditions are true, then the returned progress values are the values set for the context using the most recent call to kherr_set_progress():

  • if the numerator and the denominator are non-zero

  • if the KHERR_CF_OWN_PROGRESS flag is set for the context.

Otherwise, the function will calculate the progress by enumerating all the child context for the context and summing up the normalized numerators and the denominators for them.

KHMEXP khm_boolean KHMAPI kherr_is_error ( void )

Check if the current error context indicates an error.

Returns:
TRUE if there is an error. FALSE otherwise.
See also:
kherr_analyze()

KHMEXP khm_boolean KHMAPI kherr_is_error_i ( kherr_context * c )

Check if an error context indicates an error.

Returns:
TRUE if there is an error. FALSE otherwise.
See also:
kherr_analyze()

KHMEXP void KHMAPI kherr_location ( wchar_t * location )

Set the location string for the last event.

The event that will be modified is the last event reported by the calling thread.

KHMEXP kherr_context* KHMAPI kherr_peek_context ( void )

Retrieve the current error context.

The returned pointer must be released with a call to kherr_release_context().

KHMEXP void KHMAPI kherr_pop_context ( void )

Pop a context.

Remove the current error context from the thread's context stack. If no other open handles exist to the error context, this causes the error context to collapse into it's parent context or vanish entirely unless the context contains an error.

See also:
kherr_push_context() for more information about thread specific context stacks.

KHMEXP void KHMAPI kherr_push_context ( kherr_context * c )

Push a context.

Each thread has a stack of error contexts. The topmost one is current. The thread can push or pop contexts on to the stack independently of the hierarchy of contexts (the only exception, as explained below is when the context that is being pushed is unbound).

If the context being pushed by kherr_push_context() is unbound, then it will be attached to the current context of the thread as a child. Once the new context is pushed to the top of the stack, it will become the current context for the thread.

The calling thread must call kherr_pop_context() to remove the context from the top of the stack. Each call to kherr_push_new_context() or kher_push_context() must have a corresponding kherr_pop_context() call.

When the thread terminates, all of the contexts in the thread's context stack will be automatically removed.

See also:
kherr_pop_context()

KHMEXP void KHMAPI kherr_push_new_context ( khm_int32 flags )

Push an empty context.

Creates an empty context, adds it as a child of the current thread's error context. If the current thread does not have an error context, then the created error context will be a root level context.

The new context will be the current error context for the calling thread.

Parameters:
[in] flags Initial flags for the context. Combination of kherr_context_flags
See also:
kherr_push_new_context() for more information about thread specific context stacks.

KHMEXP void KHMAPI kherr_remove_ctx_handler | ( | kherr_ctx_handler | h,
 |  | kherr_serial | serial
 | ) |  |

Remove a context event handler.

Undoes what was done with kherr_add_ctx_handler()

See also:
kherr_add_ctx_handler()

KHMEXP kherr_event* KHMAPI kherr_report | ( | kherr_severity | severity,
 |  | const wchar_t * | short_desc,
 |  | const wchar_t * | facility,
 |  | const wchar_t * | location,
 |  | const wchar_t * | long_desC,
 |  | const wchar_t * | suggestion,
 |  | khm_int32 | facility_id,
 |  | kherr_suggestion | suggestion_id,
 |  | kherr_param | p1,
 |  | kherr_param | p2,
 |  | kherr_param | p3,
 |  | kherr_param | p4,
 |  | khm_int32 | flags,
 |  | HMODULE | h_module
 | ) |  |

Report an error.

Creates an event, fills in the details specified in the arguments, and adds it to the current error context.

If the current thread does not have an error context, no reporting happens. However, if any of the supplied strings or parameters are marked as allocated, they will be freed before the function returns.

Certain parameters that expect strings can instead be given string resources, message resources or allocated strings in addition to constant string. By default, the parameters are expected to be constant strings.

Allocated strings: The application can allocate memory for a string. Since the application is not notified when the event is no longer used and freed, it must indicate that the string is an allocated string by setting the appropriate flag in the flags parameter. When the event is no longer used, the memory pointed to by the relevant pointer will be freed through a call to free(). Not all string parameters take allocated strings. See individual parameter documentation for details.

String resources: On WIN32, string resources can be passed in to kherr_report() using the MAKEINTRESOURCE macro. However, the application must specify that the parameter is a string resource using the appropriate flag in the flags parameter. The error reporting engine will expand the string against the module handle passed in the h_module parameter when the value of the string is required. Not all string parameters take string resources. See individual parameter documentation for details. Strings loaded through string resources cannot be longer than KHERR_MAXCCH_STRING in characters inclusive of terminating NULL.

Message resources: On WIN32, message resources can be passed in to kherr_report() by specifying the message ID where it ordinarily expects a pointer to a constant string. The application must indicate that the string is a message resource by using the appropriate flag in the flags parameter. When the value of the string is needed, it is expanded against the module handle passed in the h_module parameter using the message ID. Not all string parameters take message resources. See individual parameter documentation for details. Note that the facility and severity values associated with a message resource are ignored. Strings loaded through message resources cannot be longer than KHERR_MAXCCH_STRING in characters inclusive of terminating NULL.

Formatted fields: Parameters that are formatted can have can have parameter inserts like in printf(). However, specifying inserts is different from printf() and follows the conventions used in WIN32 API FormatMessage(). This is because for localized strings, the order of the parameters in the string may be different. See the documentation for FormatMessage() for details on the format string. The same set of parameters (i.e. p1, p2, p3, p4) is used for all formatted strings with appropriate marshalling for 64 bit types. The size of the string after expansion must not exceed 65536 bytes inclusive of terminating NULL.

Parameters:
[in] | severity | One of kherr_severity_level
[in] | short_desc | Short description or title (localized). Can be a string resource, message resource, allocated string or constant string. The flags parameter should indicate the type of string used.
[in] | facility | Facility name of the reporter (not localized)
[in] | location | Usually the function name or such of where the event occured (not localized)
[in] | long_desc | Long description of event (localized, formatted). Can be a string resource, message resource, allocated string or constant string. The flags parameter should indicate the type of string used.
[in] | suggestion | Suggested action to correct situation, if applicable (localized). Can be a string resource, message resource, allocated string or constant string. The flags parameter should indicate the type of string used.
[in] | facility_id | Identifier of facility. Application defined.
[in] | suggestion_id | One of the suggestion identifiers from kherr_suggestion_ids
[in] | p1 | First parameter. Used for formatting.
[in] | p2 | Second parameter. Used for formatting.
[in] | p3 | Third parameter. Used for formatting.
[in] | p4 | Fourth parameter. Used for formatting.
[in] | flags | Flags. See kherr_report_flags
[in] | h_module | Handle to a module that resolves any string or message resources used for the short_description , long_desc or suggestion parameters. This parameter is only available on WIN32.
Note:
With the exception of parameters of type KEPT_STRINGT and parameters which are flagged for freeing using the flags parameter, all other string parameters are assumed to be pointers to constant strings. The strings are not copied and the pointers are used as is. Also, no clean-up is performed when the event is freed other than that implied by flags.

KHMEXP kherr_event* __cdecl kherr_reportf | ( | const wchar_t * | long_desc_fmt,
 |  |  | ...
 | ) |  |

Report a formatted message.

The format string long_desc_fmt should be a string constant and the format specifiers follow that of sprintf. This creates an event with the long description set to the expansion of the format string against the arguments.

KHMEXP kherr_event* __cdecl kherr_reportf_ex | ( | kherr_severity | severity,
 |  | const wchar_t * | facility,
 |  | khm_int32 | facility_id,
 |  | HMODULE | hModule,
 |  | const wchar_t * | long_desc_fmt,
 |  |  | ...
 | ) |  |

Report a formatted message.

The format string long_desc_fmt should be a string constant and the format specifiers follow that of sprintf. This creates an event with the long description set to the expansion of the format string against the arguments.

KHMEXP void KHMAPI kherr_set_desc_event ( void )

Marks the last event as the descriptor event for the current error context.

Note that marking an event as the descriptor event has the effect of removing the event from event queue. The event will henceforth be used as the descriptor for the context. The only effective fields of a descriptor event are short_desc, long_desc, facility, facility_id and the parameters which are used for resolving formatted strings in the aforementioned fields.

Upon calling kherr_set_desc_event(), the event will be automatically evaluated as if kherr_evaluate_event() was called.

The event that will be referenced is the last event reported by the calling thread.

KHMEXP void KHMAPI kherr_set_progress | ( | khm_ui_4 | num,
 |  | khm_ui_4 | denom
 | ) |  |

Set the progress meter of the current error context.

Setting denom to zero removes the progress meter.

KHMEXP void KHMAPI kherr_suggest | ( | wchar_t * | suggestion,
 |  | khm_int32 | suggestion_id,
 |  | khm_int32 | flags
 | ) |  |

Set the suggestion and suggestion identifier for the last event.

The event that will be modified is the last event reported by the calling thread.

Generated on Mon Oct 22 22:56:47 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Standard Facility IDs

Standard Facility IDs
[NetIDMgr Error Reporting]

Defines

#define | KHM_FACILITY_KMM 1
#define | KHM_FACILITY_KCDB 2
#define | KHM_FACILITY_UI 3
#define | KHM_FACILITY_KRB5 64
#define | KHM_FACILITY_KRB4 65
#define | KHM_FACILITY_AFS 66
#define | KHM_FACILITY_USER 128

Generated on Mon Oct 22 22:56:47 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: kherr_event Struct Reference

kherr_event Struct Reference
[NetIDMgr Error Reporting]

#include <kherr.h>

Detailed Description

An event.

Public Member Functions

LDCL (struct tag_kherr_event)

Data Fields

khm_int32 magic
DWORD | thread_id
const wchar_t * | short_desc
const wchar_t * | facility
const wchar_t * | location
const wchar_t * | long_desc
const wchar_t * | suggestion
kherr_severity | severity
khm_int32 facility_id
kherr_suggestion | suggestion_id
int | flags
kherr_param | p1
kherr_param | p2
kherr_param | p3
kherr_param | p4
DWORD | time_ticks
FILETIME | time_ft
HMODULE | h_module

Field Documentation

khm_int32 kherr_event::magic

Magic number. Always set to KHERR_EVENT_MAGIC

DWORD kherr_event::thread_id

The thread which reported this event.

const wchar_t* kherr_event::short_desc

Short description or title (localized)

const wchar_t* kherr_event::facility

Facility name of the reporter (not localized)

const wchar_t* kherr_event::location

Location. Usually the function name or such of where the event occured (not localized)

const wchar_t* kherr_event::long_desc

A long description of what went wrong (localized, formatted)

const wchar_t* kherr_event::suggestion

A suggested way to fix it (localized,formatted)

kherr_severity kherr_event::severity

Severity level. One of the severity levels listed in enumeration kherr_severity

khm_int32 kherr_event::facility_id

Left to the application to interpret

kherr_suggestion kherr_event::suggestion_id

One of the suggestion ID's from the enumeration kherr_suggestion

int kherr_event::flags

Flags.

kherr_param kherr_event::p1

Parameter 1 for formatting

kherr_param kherr_event::p2

Parameter 2 for formatting

kherr_param kherr_event::p3

Parameter 3 for formatting

kherr_param kherr_event::p4

Parameter 4 for formatting

DWORD kherr_event::time_ticks

Time at which event was reported (as returned by GetTickCount().

FILETIME kherr_event::time_ft

Time at which event was reported. Current system time as FILETIME.

HMODULE kherr_event::h_module

Handle to the module which should resolve any unresolved resources references above.

The documentation for this struct was generated from the following file:
  • kherr.h
Generated on Mon Oct 22 22:56:48 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: kherr_context Struct Reference

kherr_context Struct Reference
[NetIDMgr Error Reporting]

#include <kherr.h>

Detailed Description

An error context.

Public Member Functions

TDCL (struct tag_kherr_context)
QDCL (struct tag_kherr_event)

Data Fields

khm_int32 magic
kherr_serial serial
kherr_severity severity
khm_int32 flags
khm_ui_4 refcount
kherr_event * desc_event
kherr_event * err_event
khm_ui_4 progress_num
khm_ui_4 progress_denom

Field Documentation

khm_int32 kherr_context::magic

Magic number. Always set to KHERR_CONTEXT_MAGIC

kherr_serial kherr_context::serial

Context instance serial number. Context objects themselves may be reused for different contexts as they are freed and reallocated. However every instance of a context is guaranteed to have a unique serial number as specified in this field. If an external entity wants to keep track of the context, it should keep track of the serial number as well as the pointer to the context object.

kherr_severity kherr_context::severity

Severity level. One of the severity levels listed below. This is the severity level of the context and is the maximum severity level of all the events in the queue of events.

khm_int32 kherr_context::flags

Flags. Used internally.

khm_ui_4 kherr_context::refcount

Reference count. Used internally

kherr_event* kherr_context::desc_event

Description event. The event that describes the error context. This points to an event that is not in the event queue.

kherr_event* kherr_context::err_event

Significant event. The last one that caused the severity level to be what it is right now. This points to an event that is listed in the event queue for this context.

khm_ui_4 kherr_context::progress_num

Progress numerator

khm_ui_4 kherr_context::progress_denom

Progress denominator

The documentation for this struct was generated from the following file:
  • kherr.h
Generated on Mon Oct 22 22:56:48 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Data Structures

Network Identity Manager Data Structures

Here are the data structures with brief descriptions:
kcdb_attrib | Credential attribute descriptor
kcdb_cred_comp_field | Defines a sort criterion for kcdb_cred_comp_generic()
kcdb_cred_comp_order | Defines the sort criteria for kcdb_cred_comp_generic()
kcdb_cred_request | Generic credentials request
kcdb_credtype | Credential type descriptor
kcdb_ident_name_xfer | Name transfer structure
kcdb_type | A data type descriptor
kconf_schema | Configuration schema descriptor record
kherr_context | An error context
kherr_event | An event
khm_version | Generic version type
khui_action | An action
khui_action_context | Action context
khui_action_ref | A reference to an action
khui_config_init_data | Initialization data passed in to a subpanel
khui_config_node_reg | Registration information for a configuration node
khui_control_row | Internal use
khui_header | Outline header
khui_htwnd_link | A hyperlink
khui_menu_def | Menu definition
khui_new_creds | New credentials acquisition blob
khui_new_creds_by_type | A descriptor of a panel in the new credentials acquisition tab
khui_new_creds_prompt | A custom prompt
khui_property_page | A property sheet page
khui_property_sheet | A property sheet
khui_tracker | Tracker data
kmm_module_info | Module information record
kmm_module_locale | Locale descriptor record
kmm_module_reg | Module registration
kmm_plugin_info | Plugin information
kmm_plugin_reg | Plugin registration
kmq_message | A single message
kmq_message_ref | Message reference
kmq_msg_subscription | Message subscription
kmq_msg_type | A message type
kmq_queue | Message queue
kmq_response | A single response
rw_lock_t | A read/write lock
Generated on Mon Oct 22 22:56:47 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: kmq_message_ref Struct Reference

kmq_message_ref Struct Reference

#include <kmqinternal.h>

Detailed Description

Message reference.

Public Member Functions

LDCL (struct tag_kmq_message_ref)

Data Fields

kmq_message * msg
kmq_callback_t recipient

Field Documentation

kmq_message* kmq_message_ref::msg

Message that we are referring to

kmq_callback_t kmq_message_ref::recipient

The recipient of the message

The documentation for this struct was generated from the following file:
  • kmqinternal.h
Generated on Mon Oct 22 22:56:48 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: kmq_msg_subscription Struct Reference

kmq_msg_subscription Struct Reference

#include <kmqinternal.h>

Detailed Description

Message subscription.

A subscription binds a recipient with a message type. These are specific to a thread. I.e. a subscription that was made in one thread will not receive messages in the context of another thread.

Public Member Functions

LDCL (struct tag_kmq_msg_subscription)

Data Fields

khm_int32 magic
khm_int32 type
khm_int32 rcpt_type
union {
kmq_callback_t cb
HWND hwnd
} recipient
kmq_queue * queue

Field Documentation

khm_int32 kmq_msg_subscription::magic

Magic number. Should always be KMQ_MSG_SUB_MAGIC

khm_int32 kmq_msg_subscription::type

Type of message

khm_int32 kmq_msg_subscription::rcpt_type

Type of recipient. One of KMQ_RCPTTYPE_CB or KMQ_RCPTTYPE_HWND

kmq_callback_t kmq_msg_subscription::cb

Callback if the subscription is of callback type

HWND kmq_msg_subscription::hwnd

Window handle if the subscription is a windows message type

kmq_queue* kmq_msg_subscription::queue

Associated queue

The documentation for this struct was generated from the following file:
  • kmqinternal.h
Generated on Mon Oct 22 22:56:49 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: kmq_msg_type Struct Reference

kmq_msg_type Struct Reference

#include <kmqinternal.h>

Detailed Description

A message type.

Public Member Functions

LDCL (struct tag_kmq_msg_type)

Data Fields

khm_int32 id
kmq_msg_subscription * subs
kmq_msg_completion_handler completion_handler
wchar_t * name

Field Documentation

khm_int32 kmq_msg_type::id

Identifier for the message type.

kmq_msg_subscription* kmq_msg_type::subs

The list of subscriptions

kmq_msg_completion_handler kmq_msg_type::completion_handler

Completion handler for the message type

wchar_t* kmq_msg_type::name

Name of the message type for named types. Message type names are language independant.

The documentation for this struct was generated from the following file:
  • kmqinternal.h
Generated on Mon Oct 22 22:56:49 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: kmq_queue Struct Reference

kmq_queue Struct Reference

#include <kmqinternal.h>

Detailed Description

Message queue.

Each thread gets its own message queue. When a message is broadcast to which there is a subscriber in a particular thread, a reference to the message is placed in the message queue of the thread. The dispatch procedure then dispatches the message as described in the message reference.

Public Member Functions

QDCL (kmq_message_ref)
LDCL (struct tag_kmq_queue)

Data Fields

kmq_thread_id | thread
CRITICAL_SECTION | cs
HANDLE | wait_o
khm_int32 load
kmq_timer | last_post
khm_int32 flags

Member Function Documentation

kmq_queue::QDCL ( kmq_message_ref )

Queue of message references

Field Documentation

kmq_thread_id kmq_queue::thread

The thread id

khm_int32 kmq_queue::load

Number of messages waiting to be processed on this message queue.

kmq_timer kmq_queue::last_post

Time the last message was received

khm_int32 kmq_queue::flags

Flags. Currently, it's just KMQ_QUEUE_FLAG_DELETED

The documentation for this struct was generated from the following file:
  • kmqinternal.h
Generated on Mon Oct 22 22:56:49 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Data Fields

  • All
  • Functions
  • Variables
  • a
  • b
  • c
  • d
  • e
  • f
  • h
  • i
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w

Here is a list of all documented struct and union fields with links to the struct/union documentation for each field:

- a -

  • aborted : kmq_message
  • action : khui_action_ref
  • alt_id : kcdb_attrib
  • attr_id : khui_header
  • attrib : kcdb_cred_comp_field
  • aux : khm_version , khui_new_creds_by_type
Generated on Mon Oct 22 22:56:47 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Page Index

Network Identity Manager Related Pages

Here is a list of all related documentation pages:
  • Credentials Providers
  • Network Identity Manager Modules and Plug-ins
  • User Interface Topics
Generated on Mon Oct 22 22:56:49 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Credentials Providers

Credentials Providers

Contents

  • Data types in Network Identity Manager
  • Handling credentials provider messages
  • Managed credential acquisition
  • Property Pages for Credentials
Generated on Mon Oct 22 22:56:44 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Data types in Network Identity Manager

Credentials Providers

Data types in Network Identity Manager

Network Identity Manager's Credentials Database supports several useful data types. In addition, plug-ins can define custom data types. Only a few operations are expected of these data types since the core KCDB delegates fine grained operations to other entities that understand the underlying format.

A field in a credential can have any one of these data types, but it must have some data type. Each value can be at most KCDB_TYPE_MAXCB bytes in length regardless of the data type.

Some data types have a fixed size (such as Int32), while others are variable size. The required memory for each field in a credential is allocated as needed.

Data types

Descriptions of individual data types are below.

Individual data types

Void

Type identifier : KCDB_TYPE_VOID

The Void data type is used to indicate that the associated object does not contain any data.

String

Type identifier : KCDB_TYPE_STRING

A unicode string that is terminated with a unicode NULL (L'\0'). By default, the type has the following flags:

KCDB_TYPE_FLAG_CB_AUTO

This is because, as long as the string is terminated with a unicode NULL, the length of the string, and therefore it's size in bytes, can be inferred from the data itself.

Date

Type identifier : KCDB_TYPE_DATE

Dates and times in Network Identity Manager are stored in FILETIME structures. Utility functions are provided for converting from other formats such as time_t.

Interval

Type identifier : KCDB_TYPE_INTERVAL

Stores an interval of time. Stored as a 64-bit signed integer. The string representation of this data type is different from the Date data type and designates an interval of time.

The special value _I64_MAX (which is defined in limits.h as 0x7fffffffffffffff, or in other words, the largest positive value that can be stored in a 64-bit signed integer) is used to represent an interval of unknown length.

The string representations of a data value of Interval type are defined as follows for English (US):

  • "(Unknown)" if the value is _I64_MAX

  • "(Expired)" if the value is less than zero

  • "%d days %d hours" if the value is greater than 24 hours

  • "%d hours %d mins" if the value is greater than 1 hour

  • "%d mins %d secs" if the value is greater than 1 minute

  • "%d seconds" otherwise

Int32

Type identifier : KCDB_TYPE_INT32

A signed 32-bit integer.

Int64

Type identifier : KCDB_TYPE_INT64

A signed 64-bit integer.

Data

Type identifier : KCDB_TYPE_DATA

Raw data. Can contain a byte stream. This data type can be used by plug-ins to associate raw data with a credential. However, there is no built-in string representation for this data type. As such, this is not meant to be used for storing anything that has to be displayed to the user verbatim.

Custom data types

Custom data type call backs

Custom data types in the Network Identity Manager Credentials Database are defined using kcdb_type structures that must include several callback functions. The expected behavior of these callback functions is documented below.

toString

      khm_int32   toString(
        const void * data,
        khm_int32 cb_data,
        wchar_t *buffer,
        khm_int32 *pcb_buffer,
        khm_int32 flags);

Produce the localized string representation of the object pointed to by data. The size of the data block is specified by the cb_data parameter. If the data type specified the KCDB_TYPE_FLAG_CB_AUTO flag then cb_data can be KCDB_CBSIZE_AUTO, in which case the size of the data block is to be inferred.

toString should assume that the block of data pointed to by data is valid for this data type.

The pcb_buffer parameter is always a valid pointer to an khm_int32 variable.

The buffer parameter is a pointer to a wchar_t buffer which is to receive the unicode string representing the object. buffer may be NULL, in which case the required size of the buffer should be returned in pcb_buffer. In this case, the function should return KHM_ERROR_TOO_LONG.

If the buffer parameter is not NULL and the pcb_buffer specifies that the buffer is large enough to hold the string representation, the function should copy the string representation to the buffer, set the pcb_buffer to the number of bytes that were copied including the terminating NULL, and return KHM_ERROR_SUCCESS.

If the buffer parameter is not NULL and the pcb_buffer specifies a buffer that is not large enough, the function should set pcb_buffer to the required size (including the terminating NULL) and then return KHM_ERROR_TOO_LONG.

comp

      khm_int32 comp(
        const void * data1,
        khm_int32 cb_data1,
        const void * data2,
        khm_int32 cb_d2);

Compares two objects and returns a value indicating the relative ordering.

Since the KCDB does not interpret any data type, it relies on a loose definition of what a relative ordering is. It is left up to each data type callback to interpret what 'ascending' and 'descending' mean.

The return value r should be as follows:

r < 0 : if data1 < data2

r > 0 : if data1 > data2

r = 0 : if data1 = data2 or no relative ordering can be determined for the two objects data1 and data2.

The function should assume that both objects are valid for this data type.

The size specifiers cb_data1 and cb_data2 can (either or both) be KCDB_CBSIZE_AUTO if the data type specified KCDB_TYPE_FLAG_CB_AUTO flag.

dup

      khm_int32 dup(
        const void * d_src,
        khm_int32 cb_src,
        void * d_dst,
        khm_int32 * pcb_dst);

Duplicate an object. The object pointed to by d_src is to be copied to the buffer pointed to by d_dst. The function is to assume that d_src object is valid. The size specifier cb_src may be KCDB_CBSIZE_AUTO if KCDB_TYPE_FLAG_CB_AUTO was specified for the data type.

If d_dst pointer is NULL, then the required buffer size should be returned in pcb_dst. In this case, the function itself should return KHM_ERROR_TOO_LONG. The same behavior should occur if d_dst is non NULL and pcb_dst indicates that the buffer is not sufficient.

If d_dst is not NULL and pcb_dst indicates that the buffer is sufficient, then a copy of the object in d_src should be placed in d_dst. The function shold return KHM_ERROR_SUCCESS and set pcb_dst to the number of bytes that were copied.

This callback will only be called when the credentials database is retrieving objects from the outside. Once it receives an object it may be copied or moved as required. Hence the object should not assume to reside in a specific location of memory. Also, dup is not intended to perform such functions as reference counting which require knowledge of a precise number of instances of an object, as the credentials database may copy the object simply by copying the block of memory.

Note that whenever pcb_dst is to be set, it MUST be set to a valid byte count. It can not be assigned KCDB_CBSIZE_AUTO even if the data type supports it. The pcb_dst parameter is used internally to allocate memory for the object.

isValid

      khm_boolean isValid(
        const void * data,
        khm_int32 cb_data);

Checks if the object pointed to by the data pointer is a valid object for this data type. If the data type specified the KCDB_TYPE_CB_AUTO flag, then the cb_data parameter may be KCDB_CBSIZE_AUTO, in which the size of the object should be inferred from the data.

The function should be able to determine the validity of the object and return TRUE if it is valid. Return FALSE if it isn't, or if the size of the object can not be inferred from the given data, or if the inferred size exceeds KCDB_TYPE_MAXCB.

Generated on Mon Oct 22 22:56:44 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Handling credentials provider messages

Credentials Providers

Handling credentials provider messages

A credentials provider plug-in receives a number of messages during the course of execution. This section describes the appropriate ways of handling these messages.

  • System mesages
  • Credential messages
    • Listing Credentials
    • Credential Acquisition Message Sequence
    • Destroying Credentials
    • Importing Credentials
    • Property Pages

System mesages

There are only two system messages that a credentials provider needs to handle. Both of these are explained elsewhere as they deal with initialization and uninitialization of the plug-in. See the following two sections for details on handling these messages.

  • <KMSG_SYSTEM,KMSG_SYSTEM_INIT> Initialization
  • <KMSG_SYSTEM,KMSG_SYSTEM_EXIT> Uninitialization

Credential messages

Listing Credentials

When the Network Identity Manager application needs to refresh the list of credentials that credentials providers are aware of, it sends out a <KMSG_CRED, KMSG_CRED_REFRESH> message.

Each credentials provider is expected to populate a credential set with the credentials that it is aware of and call kcdb_credset_collect() or kcdb_credset_collect_filtered() to merge the credentials into the root credentials set.

In addition to responding to <KMSG_CRED, KMSG_CRED_REFRESH>, each credentials provider is expected to list and merge their credentials during the following events:

  • When the plug-in is initialized, during <KMSG_SYSTEM, KMSG_SYSTEM_INIT>

  • When the plug-in obtains new credentials during the new credentials acquisition sequence and whenever the plug-in becomes aware of new credentials.

Credential Acquisition Message Sequence

The aquisition of new or renewed credentials is conducted via a sequence of messages. Details of handling this sequence is explained in the section Managed credential acquisition .

Destroying Credentials

When a request is received to destroy credentials, Network Identity Manager sends out a <KMSG_CRED, KMSG_CRED_DESTROY_CRED> message. The vparam member of the message will point to a khui_action_context structure that describes which credentials are being destroyed. The plug-in is expected to destroy any credentials that were provided by the plug-in which are included in the user interface context.

See also:
Using Contexts

Importing Credentials

The import action is typically used to request that plug-ins import any relevant credentials from the Windows LSA cache. This typically only applies to plug-ins that provide Kerberos credentials and is not discussed in detail.

Property Pages

Credentials providers are also expected to participate in the user interface when the user makes a request to view the properties of a credential or identity.

  • <KMSG_CRED, KMSG_CRED_PP_BEGIN>
  • <KMSG_CRED, KMSG_CRED_PP_PRECREATE>
  • <KMSG_CRED, KMSG_CRED_PP_END>
  • <KMSG_CRED, KMSG_CRED_PP_DESTROY>

Details about handling this sequence of messages is discussed in Property Pages for Credentials .

Address Change Notification

When the Network Identity Manager detects that that IP address of the machine has changed, it will issue a <KMSG_CRED, KMSG_CRED_ADDR_CHANGE>. Handling this notification is optional and is only necessary for credentials providers which are affected by IP address changes. This is just a notification and the plug-in is not expected to take any special action.
Generated on Mon Oct 22 22:56:44 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Managed credential acquisition

Credentials Providers

Managed credential acquisition

Credential providers and identity providers must participate in managed credential acquisition in order to respond to the user's requests to obtain new credentials for an identity or to renew credentials for an existing identity.

There are two major processes that result in managed credential acuqisition. One is the acquisition of credentials, while the other is credential renewal. During a renewal, existing credentials are used to obtain new credentials which expire later than the existing credential. Typically, the identity provider performs the task of obtaining renewed initial credentials while the other credential providers obtain new credentials based on these initial credentials.

New Credentials

When a user initiates the process of initial credential acquisition, Network Identity Manager broadcasts a <KMSG_CRED,KMSG_CRED_NEW_CREDS> message. Credential providers which need to participate in the credential acquisition should respond to this message as detailed in Responding to credential acquisition messages.

Renew Credentials

Network Identity Manager broadcasts a <KMSG_CRED,KMSG_CRED_RENEW_CREDS> message to initiate the process of renewing credentials. This may be triggered automatically or by a user action. Credential providers which need to participate in the renewal should respond to this message as detailed in Responding to credential acquisition messages.

The following pages provide detailed information:

  • Handling new credentials acquisition
  • Writing the dialog procedure for a cred type panel
Generated on Mon Oct 22 22:56:44 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Handling new credentials acquisition

Credentials Providers » Managed credential acquisition

Handling new credentials acquisition

The process of acquiring credentials happens as follows:

  • Network Identity Manager creates a khui_new_creds object and a credentials acquisition window.

  • <KMSG_CRED,KMSG_CRED_RENEW_CREDS> or <KMSG_CRED,KMSG_CRED_NEW_CREDS> is sent to all the credentials providers.

  • The credential providers create the panels (where appropriate) for customizing their respective credential types. The type, panel and any dependency information is populated into a khui_new_creds_by_type structure and added to the khui_new_creds structure. (See khui_cw_add_type()).

  • <KMSG_CRED, KMSG_CRED_DIALOG_PRESTART> is sent to all the credentials providers.

  • <KMSG_CRED, KMSG_CRED_DIALOG_START> is sent to all the credentials providers.

  • The dialog for obtaining credentials is displayed. Notifications between the main dialog and the individual panels are done through KHUI_WM_NC_NOTIFY messages to the dialog procedures.

  • Once the dialog processing is done, a WMNC_DIALOG_PREPROCESS message is sent to the dialog procedure.

  • Network Identity Manager posts <KMSG_CRED,KMSG_CRED_DIALOG_PROCESS> message to all the credentials providers. Each provider should check if the user cancelled the dialog or indicated that the new credentials should be obtained and act accordingly. The result field of the khui_new_creds structure will be set to either KHUI_NC_RESULT_PROCESS or KHUI_NC_RESULT_CANCEL to indicate whether the user wishes to acquire credentials or cancel the operation.

  • Once all the plug-ins have processed the <KMSG_CRED, KMSG_CRED_DIALOG_PROCESS> message, the application checks whether the new credentials dialog should continue processing, or whether the dialog should be closed. If the dialog should continue processing, then the dialog returns to the state it was in prior to the WMNC_DIALOG_PREPROCESS message was sent. If the dialog should be closed, then a <KMSG_CRED, KMSG_CRED_END> message is sent.

  • A <KMSG_CRED, KMSG_CRED_END> message signals the end of the credentials acquisition process. Each credentials provider is responsible for removing the khui_new_creds_by_type structre from the khui_new_creds structure and freeing up any resources it allocated earlier in preparation for obtaining new credentials.

Responding to credential acquisition messages

<::KMSG_CRED,::KMSG_CRED_NEW_CREDS> and <::KMSG_CRED,::KMSG_CRED_RENEW_CREDS> Messages

The credential acquisition messages are <KMSG_CRED,KMSG_CRED_NEW_CREDS> and <KMSG_CRED, KMSG_CRED_RENEW_CREDS>. They are structured as follows:

  • type : KMSG_CRED
  • subtype: KMSG_CRED_NEW_CREDS or KMSG_CRED_RENEW_CREDS
  • uparam : 0 (unused)
  • vparam : a pointer to a khui_new_creds structure.

The vparam parameter of the message, as shown above, is a pointer to a khui_new_creds structure. You can use the subtype field of this structure to determine whether this is a new credentials acquisition or a renewal.

In response to this message, a credentials provider is expected to provide a configuration panel which the user can use to customize how the credentials of this type are to be obtained. The panel is described by the khui_new_creds_by_type structure.

Specifying the credentials type panel

The credentials type panel is used by the user to customize how credentials of the specified type are to be obtained. The khui_new_creds_by_type structure that describes the panel can be used to specify a number of parameters that guide how the panel is to be displayed in the new credentials acquisition dialog.

The name field defines a localized string that will be displayed in the tab control that houses the panel. If it is NULL, then the name of the credentials type is used. Optionally, an icon can be specified in the icon field which will appear alongside the name. A tooltip may be provided in the tooltip field which will be displayed when the user hovers the mouse over the tab.

In order to assert that the tab appears at a specific position in the list of tabs, you can specify a positive number in the ordinal field. Zero does not count as a valid ordinal. The panels with positive ordinals are arranged first in increasing order of ordinal (conflicts are resolved by sorting along the name). Then the panels without a positive ordianl are arranged behind these in increasing order of name.

Currently, the credentials provider must specify a dialog template that will be used to create the embedded dialog for configuring new credentials for the type. This is done by setting the khui_new_creds_by_type::h_module, khui_new_creds_by_type::dlg_proc and khui_new_creds_by_type::dlg_template fields.

Following is example code which suggests how this could be done:

       // Message handling code for KMSG_CRED_NEW_CREDS or
       // KMSG_CRED_INIT_CREDS
       ...
       khui_new_creds * c;
       khui_new_creds_by_type * t;

       c = (khui_new_creds *) vparam;
       t = PMALLOC(sizeof(*t));
       ZeroMemory(t, sizeof(*t));

       t->type = my_cred_type;

       // set look and feel params
       t->ordinal = 3; // third in line
       t->name = L"My panel name";
       t->icon = LoadIcon(my_hInstance, MAKEINTRESOURCE(IDI_PANEL_ICON));
       t->tooltip = L"Configure credentials of my type";

       // specify the dialog template to use
       t->h_module = my_hInstance;
       t->dlg_proc = my_dialog_procedure;
       t->dlg_template = MAKEINTRESOURCE(IDD_NEW_CREDS);

       if(KHM_FAILED(khui_cw_add_type(c,t))) {
           // handle error
       }

It is important to note that the khui_new_creds_by_type pointer that is passed into khui_cw_add_type() points to an allocated block of memory which should remain in memory until <KMSG_CRED,KMSG_CRED_END> message is received.

For information on how the dialog procedure should be written, see Writing the dialog procedure for a cred type panel .

Generated on Mon Oct 22 22:56:44 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Writing the dialog procedure for a cred type panel

Credentials Providers » Managed credential acquisition

Writing the dialog procedure for a cred type panel

Once each credentials provider has had a chance to add a credentials type panel for the new credentials dialog, the application will attempt to create all the dialog panels. It will use the dialog template and the dialog procedure specified in the dlg_proc and dlg_template members of the khui_new_creds_by_type structure.

The credentials type panel will be an ordinary dialog that is created as a child of the new credentials window. Therefore, the dialog template should have the WS_CHILD style and the WS_EX_CONTROLPARENT extended style set so that the main dialog procedure can correctly navigate the child dialog.

Handling Messages

WM_INITDIALOG

When the application creates a credentials type panel dialog, it passes a pointer to the khui_new_creds structure as the LPARAM parameter. This can be used to query for the credentials type panel for the plug-in, as follows:

    // Handler for WM_INITDIALOG:
    // HWND hwnd, WPARAM wParam and LPARAM lParam

    khui_new_creds *         nc = NULL;
    khui_new_creds_by_type * nct = NULL;

    // We can define and use a structure like the following to
    // maintain the data that will be used to drive the dialog user
    // interface and to store credentials type settings:
    struct nc_dialog_data *  d = NULL;

    nc = (khui_new_creds *) lParam;

    // Now we can use nc to query for our credentials type structure
    khui_cw_find_type(nc, credtype_id, &nct);

    assert(nct);

    // The dialog data structure should live until we receive
    // WM_DESTROY.
    d = malloc(sizeof(*d));
    ZeroMemory(d, sizeof(*d));

    d->nc = nc;
    d->nct = nct;

    // Store it as our user data for the dialog.
    SetWindowLongPtr(hwnd, DWLP_USER, (LPARAM) d);

    // The aux member of the khui_new_creds_by_type structure is
    // reserved for use by the credentials provider.  We can use it to
    // store our dialog data.  This way, the dialog procedure and the
    // plug-in thread can both access it and use it to store
    // credential options for use when obtaining credentials.  The
    // dialog and the dialog data exist until KMSG_CRED_END is sent.
    nct->aux = (LPARAM) d;

    // We should return FALSE here to indicate that we don't want to
    // set keyboard focus to this dialog yet.  The application will
    // attempt to create all the credentials type panels as well as
    // the other child dialogs used for the new credentials opeartion.
    return FALSE;

WM_NC_NOTIFY

WM_NC_NOTIFY is a special window message that Network Identity Manager uses to communicate with credentials type panels. The messages are listed in the khui_wm_nc_notifications enumeration. The format of the message is as follows:

  • uMsg : KHUI_WM_NC_NOTIFY
  • HIWORD(wParam) : one of khui_wm_nc_notifications
  • LPARAM : pointer to the khui_new_creds structure (except where noted)

The WM_NC_NOTIFY notifications that a credentials provider is expected to handle are the following:

  • WMNC_IDENTITY_CHANGE

The primary identity has changed.

The khui_new_creds structure contains a list of identities to which the current operation should be applied. In its current implementation, only the first identity in this list is used. Therefore, the list will contain at most one identity. It is possible for the list to be empty (for example, if the user hasn't selected an identity yet).

When handling this notification, the plug-in should check the n_identities member of the khui_new_creds structure to see whether there are any identities selected. This value would be either zero or one. If it is non-zero, then a handle to the selected identity will be in khui_new_creds::identities[0].

Plug-ins typically use this notfication to load identity specific settings when a new identity is selected.

This notification is sent to all the credentials type panels.

  • WMNC_DIALOG_MOVE

The new credentials window has moved.

This message is sent to all the credentials type panels when the new credentials window is being moved. It will be sent continuously if the user is dragging the window. Plug-ins rarely need to know their position on the screen. However, if there are any other windows that were created by the plug-in, such as floating controls or tooltips, they may need to be repositioned in response to this message.

Sent to all the credentials type panels.

  • WMNC_UPDATE_CREDTEXT

Update the credentials text associated with a panel.

During the new credentials operation, each plug-in is expected to maintain a textual representation of the credentials that the plug-in expects to obtain for the selected identity. It can, alternatively, be used to indicate the state of the credentials type in respect to the selected identity (for example, whether the credentials type is disabled for the identity and why).

This text is not visible when the new credentials window is in basic mode, but it is visible when the window is in advanced mode. The following image shows the expanded new credentials window including the credentials text from a several plug-ins:

Once this message is received, each plug-in should construct its credentials text string and store it in the credtext member of its khui_new_creds_by_type structure as shown in the sample code below:

      // Handler for window message WM_NC_NOTIFY with
      // HWND hwnd, WPARAM wParam and LPARAM lParam

      // This structure holds the dialog data for the panel.  We
      // assume it has 'nc' and 'nct' fields that point to the
      // khui_new_creds and khui_new_creds_by_type structures
      // respectively.

      ...
      struct nc_dialog_data * d;
      ...

      // Retrieve the data structure from the dialog user data.
      d = (struct nc_dialog_data *) GetWindowLongPtr(hwnd, DWLP_USER);

      switch (HIWORD(wParam)) {
      case WMNC_UPDATE_CREDTEXT:
        {
          wchar_t buffer[KHUI_MAXCCH_LONG_DESC];
          size_t cb_size;

          // we are being requested to update the credentials text. We
          // already allocated a buffer when we created the nct
          // structure.  So we can just set the text here.

          // The credentials text should reflect the credentials that
          // will be obtained when the new credentials operation
          // completes.

          assert(d && d->nc && d->nct);

          if (d->nct->credtext) {
              free(d->nct->credtext);
              d->nct->credtext = NULL;
          }

          // We only display something if there is a selected identity
          if (d->nc->n_identities > 0) {
            StringCbPrintf(buffer, sizeof(buffer),
                           L"<p>My Credentials<tab>: %s</p>",
                           get_credential_name(d));
            StringCbLength(buffer, sizeof(buffer), &cb_size);
            cb_size += sizeof(wchar_t); // account for the terminating NULL

            d->nct->credtext = malloc(cb_size);
            if (d->nct->credtext) {
               StringCbCopy(d->nct->credtext, cb_size, buffer);
            }
          }

          break;
        }

      ... // Handler other notifications
      }

The text that is specified as the credentials text is formatted hypertext. For more information about support for formatting and hypertext and handling hyperlinks, see khui_htwnd.

Note:
When this message is sent to the new credentials window, the application will send the WMNC_UPDATE_CREDTEXT message to all the credential type panels and update the credential text window.

  • WMNC_CREDTEXT_LINK

A hyperlink was activated.

Sent to a panel dialog procedure when a user clicks an embedded link in the credentials text that belongs to that panel. The lParam parameter of the message is a pointer to a khui_htwnd_link structure describing the link.

See also:
khui_htwnd
Note:
The lParam parameter does not point to a khui_new_creds structure for this message.

  • WMNC_DIALOG_PREPROCESS

The credentials acquisition process is about to start.

Sent to all the credentials type panels to notify them that the credentials acquisition process will start. Once all plug-ins have handled the notification, the application will start sending out <KMSG_CRED, KMSG_CRED_PROCESS> messages to the credentials providers which are participating in the new credentials operation.

Other notes

Generated on Mon Oct 22 22:56:44 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Property Pages for Credentials

Credentials Providers

Property Pages for Credentials

This section describes the logistics of property pages. When a user selects the 'Properties' option from a menu (either the File menu or a context menu), then a KHUI_ACTION_PROPERTIES action is triggered. This is handled by the credentials window and triggers the launch of a property sheet if there is a valid context to extract properties from.

Sequence of actions:

  • KHUI_ACTION_PROPERTIES action is triggered.

  • The main window dispatches the action to the credentials window.

  • If there is a valid context, then the credentials window calls khui_ps_create_sheet() to create an empty property sheet structure of type khui_property_sheet. The ctx member of the structure is populated with the property context obtained through khui_context_get().

In addition to the ctx member, depending on the scope of the context, other fields of the khui_property_sheet structure could also be set:

  • For KHUI_SCOPE_IDENT, the identity field will be set to the selected identity.

  • For KHUI_SCOPE_CREDTYPE, the identity field will be set to the selected identity, and the credtype field will be set to the selected credential type.

  • For KHUI_SCOPE_CRED, in addition to the identity and credtype fields being set as above, the cred field will be set to a handle to the credential.

  • A global message is broadcast of type <KMSG_CRED,KMSG_CRED_PP_BEGIN> with the parameter blob that is a pointer to the khui_property_sheet structure.

  • Subscribers to <KMSG_CRED> messages handle the message, check the khui_property_sheet structure and determine whether or not and what type property pages to add to the property sheet. New property sheets are added by calling khui_ps_add_page().

The following code shows how this message might be handled.

       // Message handler code for KMSG_CRED_PP_BEGIN

       khui_property_sheet * ps;
       PROPSHEETPAGE       * psp;     // from prsht.h

       if (ps->credtype == credtype_id &&
           ps->cred) {

           // We have been requested to show a property sheet for one of
           // our credentials.

           // The PROPSHEETPAGE structure has to exist until we remove the
           // property sheet page when we are handling KMSG_CRED_PP_END.

           psp = malloc(sizeof(*psp));
           ZeroMemory(p, sizeof(*psp));

           psp->dwSize = sizeof(*psp);
           psp->dwFlags = 0;

           // hResModule is the handle to the resource module
           psp->hInstance = hResModule;

           // IDD_PP_CRED is the dialog template for our property page
           psp->pszTemplate = MAKEINTRESOURCE(IDD_PP_CRED);

           // pp_cred_dlg_proc is the message handler for our property
           // page.  See the Platform SDK for details.
           psp->pfnDlgProc = pp_cred_dlg_proc;

           // We can pass the khui_property_sheet structure as the
           // lParam for the message handler so it knows the scope of
           // the property sheet.
           psp->lParam = (LPARAM) ps;

           // Finally, add a property page for our credential type
           // stored in credtype_id.  Note that only one property page
           // can be added per credential type.

           khui_ps_add_page(ps, credtype_id, 0, psp, NULL);

           return KHM_ERROR_SUCCESS;
       }

  • Once all the plug-ins have had a chance to add their property sheets, a <KMSG_CRED,KMSG_CRED_PP_PRECREATE> message is broadcast. This is a chance for the property page providers to do any processing before the property page is created.

  • The property sheet is created and made visible with a call to khui_ps_show_sheet().

  • The Network Identity Manager message loop takes over. Further interaction including notifications of 'Ok','Cancel','Apply' and other property sheet related actions are handled through WIN32 messages to the window procedure of the property sheet and the message handlers for the individual property pages.

  • Once the user closes the property sheet, a <KMSG_CRED,KMSG_CRED_PP_END> message is sent to all subscribers. Individual subscribers who added pages to the property sheet must free up any associated resources at this point.

Continuing our example from above, the following code could be used to handle this message:

     // Handler for KMSG_CRED_PP_END

     khui_property_page * p = NULL;

     // If a property sheet was added by us, this call would get
     // a handle to the property page structure.

     if (KHM_SUCCEEDED(khui_ps_find_page(ps, credtype_id, &p))) {

         // It is safe to assume that the property page window has
         // been destroyed by the time we receive KMSG_CRED_PP_END.
         // So we can free the PROPSHEETPAGE structure we allocated
         // above.

         if (p->p_page)
             free(p->p_page);
         p->p_page = NULL;

         // The property page structure we added will automatically
         // be removed and freed by the application.
     }

     return KHM_ERROR_SUCCESS;

  • All the khui_property_page structures that were allocated as well as the khui_property_sheet structure are freed up with a call to khui_ps_destroy_sheet().

Note:
The maximum number of property sheets that can be open at one time is currently set to 256. Each property sheet can have a maximum of 16 property pages.
Generated on Mon Oct 22 22:56:44 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Network Identity Manager Modules and Plug-ins

Network Identity Manager Modules and Plug-ins

The Network Identity Manager application does not include any ability to manage any specific type of credential. Instead it exposes a framework on which plug-ins can be implemented to manage credentials.

Plug-ins and localization are handled by the Network Identity Manager Module Manager API.

The following sections describe plug-ins in detail:

  • Plug-in Framework
  • Plug-in Types
  • Structure of a module
  • Localization
Generated on Mon Oct 22 22:56:44 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Plug-in Framework

Network Identity Manager Modules and Plug-ins

Plug-in Framework

Introduction to Plug-ins, Modules and Messages

Plug-ins

A plug-in is a package that implements a defined API that will perform credentials management or related tasks on behalf of Network Identity Manager.

The Network Identity Manager architecture is message based. The core of each plug-in is a message handler. The plug-in integrates with the application by subscribing to, and handling specific types of messages.

The plug-in message handler runs in its own thread and receive asynchronous messages. There are exceptions, such as when one plug-in requires another plug-in to handle a specific message before it can handle the message. In addition, during certain operations that require user interaction, each plug-in can delegate code that will run in the main application thread (the user interface thread) to process window messages.

Modules

One or more plug-ins can be bundled together into a module. A module is a dynamically loadable library which exports a specific set of callbacks. Currently, the only two required callbacks for a module are :

  • init_module(), and
  • exit_module()

For more information about how a module is structured, see Structure of a module .

Messages and Message Queues

An integral part of this framework is the messaging system. Most of the communication between the Network Identity Manager application and plug-ins is conducted through passing messages.

A message has a type and subtype and is denoted in this documentation as < message_type, message_subtype>. For example, when a plug-in is loaded, the first message it receives is < KMSG_SYSTEM, KMSG_SYSTEM_INIT >.

Each thread in the application, specially threads that were created for individual plug-in messages handlers, has an associated message queue that stores and manages all the messages that have been sent to subscribers in that thread.

The most common recipient of a message is a message callback function (see kmq_callback_t ). The message handler for a plug-in is one such example. A message callback function receives the message type, subtype and two optional parameters for the message.

Any acceptable recipient can subscribe to broadcast messages of any type. Once subscribed, whenever a message of that type is broadcast, the message will get queued on the corresponding message queue. Then, one of the dispatch functions can dispatch the message to the correct callback function. (see kmq_dispatch).

Next Module Manager ...

Generated on Mon Oct 22 22:56:44 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Module Manager

Network Identity Manager Modules and Plug-ins » Plug-in Framework

Module Manager

The Module Manager is tasked with loading and unloading modules as well as managing the plug-in message processing.

When a module is successfully loaded, it registers one or more plug-ins. The Module Manager creates a new thread for each of these plug-ins. Then the initialization message to the plug-in is sent and the message dispatch loop is started in this new thread. Having each plug-in in a separate thread prevents one plug-in from "hanging" other plug-ins and the user interface.

Note:
For compatibility with future versions of Network Identity Manager, a plug-in should not depend on the fact that it is running in its own thread.
Read more :
  • Structure of a module

Module Load Sequence

When kmm_load_module() is called to load a specific module, the following sequence of events occur:

  • The registration information for the module is located on the registry key \Software\MIT\NetIDMgr\PluginManager\Modules\[ModuleName].
    See also:
    config
  • The module will not be loaded if one of the following conditions are true:

    • The Disabled value is defined and non-zero.

    • The FailureCount value is defined and exceeds the maximum failure count. By default, the maximum failure count is three, although it can be set by adding the registry value ModuleMaxFailureCount in registry key Software\MIT\NetIDMgr\PluginManager\Modules .

  • The ImagePath value from the registration information is used to locate the module binary. If it is not an absolute path, then the binary is located using the standard system search path starting from the directory in which Network Identity Manager binaries are located.

  • The binary is loaded into the address space of Network Identity Manager along with any dependencies not already loaded.

  • If the Network Identity Manager core binary is signed, then the signature is checked against the system and user certificate stores. If this fails, the module is unloaded. See Unload sequence.

  • The init_module() entry point for the loaded module is called. If this function returns an error or if no plug-ins are registered, then the module is immediately unloaded. See Unload sequence.

    • During processing of init_module(), if any localized resource libraries are specified using kmm_set_locale_info(), then one of the localized libraries will be loaded. See Localization

    • During processing of init_module(), the module registers all the plug-ins that it is implementing by calling kmm_provide_plugin() for each.

  • Once init_module() returns, each plug-in is initialized. The method by which a plug-in is initialized depends on the plug-in type. The initialization code for the plug-in may indicate that it didn't initialize properly, in which case the plug-in is immediately unregistered. No further calls are made to the plug-in.

  • If no plug-in is successfully loaded, the module is unloaded. See Unload sequence.

During normal operation, any registered plug-ins for a module can be unloaded explicitly, or the plug-in itself may signal that it should be unloaded. If at anytime, all the plug-ins for the module are unloaded, then the module itself is also unloaded unless the NoUnload registry value is set in the module key.

Unload sequence

  • For each of the plug-ins that are registered for a module, the exit code is invoked. The method by which this happens depends on the plug-in type. The plug-in is not given a chance to veto the decision to unload. Each plug-in is responsible for performing cleanup tasks, freeing resources and unsubscribing from any message classes that it has subscribed to.

  • Once all the plug-ins have been unloaded, the exit_module() entry point is called for the module.

  • If any localized resource libraries were loaded for the module, they are unloaded.

  • The module is unloaded.

The following diagram illustrates the relationship between modules and plug-ins as implemented in the Kerberos 5 plug-in distributed with Network Identity Manager.

Generated on Mon Oct 22 22:56:44 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Plug-in Types

Network Identity Manager Modules and Plug-ins

Plug-in Types

The types of plug-ins that are currently supported by Network Identity Manager are :

Credential Provider

A credential provider plug-in essentially acts as an interface between Network Identity Manager and some entity which defines the credentials for the purpose of managing those credentials.

There can be more than one credential provider in a module.

Communication

Communication between Network Identity Manager and a credential provider occurs through a message processor. When registering a credential provider, the module initialization code in init_module() specifies KHM_PITYPE_CRED as the type member and sets msg_proc member to a valid message processor in the khm_plugin record.

Initialization

Once init_module() has completed, the module manager sends a <KMSG_SYSTEM,KMSG_SYSTEM_INIT> message to the message processor.

For credential provider plug-ins, <KMSG_SYSTEM,KMSG_SYSTEM_INIT> is guaranteed to be the first message it receives.

The callback function should return KHM_ERROR_SUCCESS if it initializes properly or some other value otherwise. If the return value signals an error, then the plug-in is assumed to have failed initialization and is immediately unloaded.

The message processor is automatically subscribed to the following message types:

  • KMSG_SYSTEM
  • KMSG_KCDB

Although a plug-in can use the <KMSG_SYSTEM,KMSG_SYSTEM_INIT> message enumerate existing credentials in the system, it should not obtain new credentials. This is because other plug-ins that may depend on the new credential messages may not be loaded at this time. See the section on Handling credentials provider messages for more information.

Uninitialization

When the plug-in is to be removed, the module manager sends a <KMSG_SYSTEM,KMSG_SYSTEM_EXIT> to the message processor. The plug-in must perform any necessary shutdown operations, free up resources and unsubscribe from any messages that it has subscribed to.

This message is guaranteed to be the last message received by a credentials manager plug-in if the plug-in unsubsribes from all additional message classes that it subsribed to.

The message types that the message processor is automatically subscribed to (See Initialization) do not have to be unsubscribed from as they are automatically removed.

Other Notes

Since credential managers may receive privileged information, the signature requirements for credential managers are specially strict.
Generated on Mon Oct 22 22:56:44 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Structure of a module

Network Identity Manager Modules and Plug-ins

Structure of a module

A Network Identity Manager module is a dynamically loadable library with a specific set of exported symbols. Each export symbol and general notes about writing a plug-in module are documented below.

Registration and Version Information

[TODO]

Initialization

Do not use DllMain or other system specific callback routines to perform intilization tasks other than creating mutexes, initializing thread local storage and other tasks that must be performed at that stage. Specifically, do not call any Network Identity Manager API functions from within DllMain.

Callbacks

The callbacks that must be implemented by a module are:

  • init_module()
  • exit_module()
Generated on Mon Oct 22 22:56:44 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Localization

Network Identity Manager Modules and Plug-ins

Localization

If a module requires localized resources, it can register the localized resource libraries with the module manager when it receives the init_module() callback. Note that you can only register localized resource libraries during init_module().

The localized resource library is global to a module. Each plug-in is not allowed to define its own localization library, although it is free to load and use any library as it sees fit. The module manager does not manage these libraries for the plug-in.

Specification of localized resources

In order to register localized resource libraries, a module calls kmm_set_locale_info(). The locales parameter to the function holds a pointer to an array of kmm_module_locale records. Each record specifies one language code and a filename of a library that holds the language resources for that language.

It is recommended that you use the LOCALE_DEF convenience macro when defining locale records for use with kmm_set_locale_info(). This will ensure that future changes in the API will only minimally affect your code. For example:

kmm_module_locale my_locales[] = {
LOCALE_DEF(MAKELANGID(LANG_ENGLISH,SUBLANG_ENGLISH_US), L"english.dll", KMM_MLOC_FLAG_DEFAULT),
LOCALE_DEF(MAKELANGID(LANG_DUTCH,SUBLANG_DUTCH), L"dutch.dll", 0),
LOCALE_DEF(MAKELANGID(LANG_SPANISH,SUBLANG_SPANISH_MODERN), L"spanish.dll", 0)
};

int n_locales = sizeof(my_locales)/sizeof(my_locales[0]);

...

kmm_set_locale_info(h_module, my_locales, n_locales);

...

See kmm_set_locale_info() and kmm_module_locale for more info.

Selection of localized resource library

The module manager searches the array of kmm_module_locale objects passed into the kmm_set_locale_info() function for one that matches the current user locale (as opposed to the current system locale). A record matches the locale if it has the same language ID.

If a match is found, that library is selected. Otherwise, the list is searched for one that is compatible with the current user locale. A locale record is compatible with the user locale if the primary language matches.

If a match is still not found, the first record in the locale array that has the KMM_MLOC_FLAG_DEFAULT flag set will be selected.

If a match is still not found, then the kmm_set_locale_info() will return KHM_ERROR_NOT_FOUND.

Using localization

The following convenience macros are available for using a module handle to load resources from the corresponding resource library. However, for performance reasons, it is advisable to obtain a handle to the resource library loaded by the module manager using kmm_get_resource_module() and then use it to access resources using the regular WIN32 API.

  • kmm_LoadAccelerators
  • kmm_LoadBitmap
  • kmm_LoadCursor
  • kmm_LoadIcon
  • kmm_LoadImage
  • kmm_LoadMenu
  • kmm_LoadString
Generated on Mon Oct 22 22:56:44 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: User Interface Topics

User Interface Topics

Contents

  • Actions
  • Menus
  • Contexts
  • khui_htwnd
Generated on Mon Oct 22 22:56:44 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Actions

User Interface Topics

Actions

Generated on Mon Oct 22 22:56:44 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Menus

User Interface Topics

Menus

Generated on Mon Oct 22 22:56:44 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Contexts

User Interface Topics

Contexts

Contents

  • Introduction
  • Using Contexts

Introduction

Several KMSG_CRED messages and many messages depend on the selections that the user has made on the user interface. The UI context functions and data structures provide access to this information.

The Network Identity Manager user interface presents an outline view of all the credentials that were provided by credentials providers. This view consists of headers representing the outline levels and rows representing individual credentials.

Users can make multiple selections of credentials or headers from this view. If all the credentials and subheaders under a particular outline level are selected, then the header itself is automatically selected. There may be multiple disjointed selections of headers and credentials.

In addition, the current cursor position also acts as a selector. The credential or header under the cursor may not actually be selected. The cursor is not the mouse pointer, but the focus rectangle that may be moved either using the keyboard or by clicking on a credential or header.

Thus there are two independent groups of selections:

  • Credentials and headers which are in a selected state at some specific point in time (the current selection).

  • The current credential or selection which the cursor is on (the cursor selection).

There are a few notes on how credentials are selected:

  • An "empty" header (a header that does not contain any credential rows) does not appear in a UI context. However they can appear as the current cursor context.

  • At its current implementation, cursor selections of identity, credential type, and individual credentials are treated as special cases since they are the most common.

How the UI context is used when processing a specific action or message depends on the action or message. If an action operates on a group of credentials, then the current selection may be used, and on the other hand if an action or message relates to just one credential, identity or credential type is invoked, then the cursor selection is invoked.

For example, double-clicking a credential, or right clicking and selecting 'Properties' from the context menu launches the property window for a credential. This operates on the cursor selection since that reflects where the user double clicked. However, choosing 'Destroy' from the context menu invokes a command that can be applied to a group of credential, and hence uses the current selection.

Next: Using Contexts

Generated on Mon Oct 22 22:56:44 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Using Contexts

User Interface Topics » Contexts

Using Contexts

Obtaining the context

Typically, messages sent by actions that rely on UI context will obtain and store the context in a location that is accessible to the handlers of the message.

If a plug-in needs to obtain the UI context, it should do so by calling khui_context_get() and passing in a pointer to a khui_action_context structure.

Once obtained, the contents of the khui_action_context structure should be considered read-only. When the plug-in is done with the structure, it should call khui_context_release(). This cleans up any additional memory allocated for storing the context as well as releasing all the objects that were referenced from the context.

Selection context

The selection context is specified in the khui_action_context structure in the sel_creds and n_sel_creds fields. These combined provide an array of handles to credentials which are selected.

Note:
If n_sel_creds is zero, then sel_creds may be NULL.

Cursor context

The scope of the cursor context is specified in the scope field of the khui_action_context strucutre. The scope can be one of:

  • KHUI_SCOPE_NONE
  • KHUI_SCOPE_IDENT
  • KHUI_SCOPE_CREDTYPE
  • KHUI_SCOPE_GROUP
  • KHUI_SCOPE_CRED

Depending on the scope, several other members of the strucre may also be set.

In general, the cursor context can be a single credential or an entire outline level. Unlike the selection context, since this specifies a single point of selection it can not be disjointed.

The contents of the identity, cred_type, cred, headers and n_headers are described in the documentation of each of the scope values above.

KHUI_SCOPE_GROUP

The KHUI_SCOPE_GROUP scope is the generic scope which describes a cursor selection that can not be simplified into any other scope.

In this case, the selection is described by an array of khui_header elements each of which specify a criterion for narrowing down the selection of credentials. The khui_header structure specifies an attribute in the attr_id field and a value in the data and cb_data fields. The credentials that are selected are those in the root credential set whose repective attributes contain the values specified in each of the khui_header elements.

For example, the following selection:

will result in the following header specification:

    ctx.n_headers = 3;

    ctx.headers[0].attr_id = KCDB_ATTR_LOCATION;
    ctx.headers[0].data = L"grailauth@KHMTEST";
    ctx.headers[0].cb_data = sizeof(L"grailauth@KHMTEST");

    ctx.headers[1].attr_id = KCDB_ATTR_ID;
    ctx.headers[1].data = &handle_to_identity;
    ctx.headers[1].cb_data = sizeof(khm_handle);

    ctx.headers[2].attr_id = KCDB_ATTR_TYPE;
    ctx.headers[2].data = &kerberos_5_credtype;
    ctx.headers[2].cb_data = sizeof(khm_int32);

Note:
The attribute that is used to specify the header is not the display attribute, but the canonical attribute. For example, in the above, the second header was actually KCDB_ATTR_ID_NAME. But KCDB_ATTR_ID was used since that is the canonical source for KCDB_ATTR_ID_NAME. See kcdb_attrib for more information on canonical attributes.
Generated on Mon Oct 22 22:56:44 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Alphabetical List

Network Identity Manager Data Structure Index

K | R

K
kconf_schema khui_config_node_reg khui_property_page kmq_message
kcdb_attrib kherr_context khui_control_row khui_property_sheet kmq_message_ref
kcdb_cred_comp_field kherr_event khui_header khui_tracker kmq_msg_subscription
kcdb_cred_comp_order khm_version khui_htwnd_link kmm_module_info kmq_msg_type
kcdb_cred_request khui_action khui_menu_def kmm_module_locale kmq_queue
kcdb_credtype khui_action_context khui_new_creds kmm_module_reg kmq_response
kcdb_ident_name_xfer khui_action_ref khui_new_creds_by_type kmm_plugin_info
R
kcdb_type khui_config_init_data khui_new_creds_prompt kmm_plugin_reg rw_lock_t

K | R

Generated on Mon Oct 22 22:56:47 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Data Fields

  • All
  • Functions
  • Variables
  • a
  • b
  • c
  • d
  • e
  • f
  • h
  • i
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w

Here is a list of all documented struct and union fields with links to the struct/union documentation for each field:

- l -

  • language : kmm_module_info , kmm_module_locale
  • last_post : kmq_queue
  • LDCL() : kmq_message
  • listener : khui_action
  • load : kmq_queue
  • location : kherr_event
  • long_desc : kcdb_credtype , kherr_event , khui_config_node_reg , kcdb_attrib
Generated on Mon Oct 22 22:56:47 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Data Fields

  • All
  • Functions
  • Variables
  • a
  • b
  • c
  • d
  • e
  • f
  • h
  • i
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w

Here is a list of all documented struct and union fields with links to the struct/union documentation for each field:

- m -

  • magic : kmq_msg_subscription , khui_action_context , kherr_event , kherr_context , khui_new_creds
  • major : khm_version
  • max : khui_tracker
  • min : khui_tracker
  • minor : khm_version
  • mode : khui_new_creds
  • module : kmm_plugin_reg
  • msg : kmq_message_ref
  • msg_proc : kmm_plugin_reg
Generated on Mon Oct 22 22:56:47 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Data Fields

  • All
  • Functions
  • Variables
  • a
  • b
  • c
  • d
  • e
  • f
  • h
  • i
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w

Here is a list of all documented struct and union fields with links to the struct/union documentation for each field:

- n -

  • n_headers : khui_action_context
  • n_identities : khui_new_creds
  • n_items : khui_menu_def
  • n_pages : khui_property_sheet
  • n_plugins : kmm_module_reg
  • n_prompts : khui_new_creds
  • n_sel_creds : khui_action_context
  • n_type_deps : khui_new_creds_by_type
  • n_types : khui_new_creds
  • name : khui_config_node_reg , khui_new_creds_by_type , kmm_plugin_reg , kmm_module_reg , kconf_schema , kcdb_cred_request , kcdb_attrib , khui_action , kcdb_credtype , kmq_msg_type
  • name_alt : kcdb_ident_name_xfer
  • name_dest : kcdb_ident_name_xfer
  • name_src : kcdb_ident_name_xfer
  • nc : khui_new_creds_by_type
  • nc_identities : khui_new_creds
  • nc_items : khui_menu_def
  • nc_prompts : khui_new_creds
  • nc_types : khui_new_creds
  • nCompleted : kmq_message
  • nFailed : kmq_message
  • nSent : kmq_message
Generated on Mon Oct 22 22:56:47 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Data Fields

  • All
  • Functions
  • Variables
  • a
  • b
  • c
  • d
  • e
  • f
  • h
  • i
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w

Here is a list of all documented struct and union fields with links to the struct/union documentation for each field:

- o -

  • order : kcdb_cred_comp_field
  • ordinal : khui_new_creds_by_type
Generated on Mon Oct 22 22:56:47 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Data Fields

  • All
  • Functions
  • Variables
  • a
  • b
  • c
  • d
  • e
  • f
  • h
  • i
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w

Here is a list of all documented struct and union fields with links to the struct/union documentation for each field:

- b -

  • banner : khui_new_creds
Generated on Mon Oct 22 22:56:47 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Data Fields

  • All
  • Functions
  • Variables
  • a
  • b
  • c
  • d
  • e
  • f
  • h
  • i
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w

Here is a list of all documented struct and union fields with links to the struct/union documentation for each field:

- c -

  • caption : khui_action
  • cb : kmq_msg_subscription
  • cb_data : khui_header
  • cb_name_dest : kcdb_ident_name_xfer
  • cb_vparam : khui_action_context
  • cmd : khui_action , khui_menu_def
  • comp : kcdb_type
  • completion_handler : kmq_msg_type
  • compute_cb : kcdb_attrib
  • compute_max_cbsize : kcdb_attrib
  • compute_min_cbsize : kcdb_attrib
  • cred : khui_action_context , khui_property_sheet
  • cred_type : khui_action_context
  • credset : khui_action_context
  • credtext : khui_new_creds_by_type
  • credtype : khui_property_sheet
  • cs : khui_new_creds
  • ctx : khui_property_sheet , khui_new_creds
  • ctx_node : khui_config_init_data
  • current : khui_tracker
Generated on Mon Oct 22 22:56:47 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Data Fields

  • All
  • Functions
  • Variables
  • a
  • b
  • c
  • d
  • e
  • f
  • h
  • i
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w

Here is a list of all documented struct and union fields with links to the struct/union documentation for each field:

- d -

  • data : khui_action , khui_header
  • def : khui_new_creds_prompt
  • dependencies : kmm_plugin_reg
  • desc_event : kherr_context
  • description : kmm_module_reg , kconf_schema , kmm_plugin_reg
  • dest_credset : kcdb_cred_request
  • dlg_proc : khui_new_creds_by_type , khui_config_node_reg
  • dlg_template : khui_config_node_reg , khui_new_creds_by_type
  • dup : kcdb_type
Generated on Mon Oct 22 22:56:47 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Data Fields

  • All
  • Functions
  • Variables
  • a
  • b
  • c
  • d
  • e
  • f
  • h
  • i
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w

Here is a list of all documented struct and union fields with links to the struct/union documentation for each field:

- e -

  • err_ctx : kmq_message
  • err_event : kherr_context
Generated on Mon Oct 22 22:56:47 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Data Fields

  • All
  • Functions
  • Variables
  • a
  • b
  • c
  • d
  • e
  • f
  • h
  • i
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w

Here is a list of all documented struct and union fields with links to the struct/union documentation for each field:

- f -

  • facility : kherr_event
  • facility_id : kherr_event
  • failure_count : kmm_module_info , kmm_plugin_info
  • failure_reason : kmm_plugin_info , kmm_module_info
  • failure_time : kmm_module_info , kmm_plugin_info
  • file_version : kmm_module_info
  • filename : kmm_module_locale
  • flags : kmq_queue , kcdb_attrib , kherr_event , kmm_plugin_info , kherr_context , kmm_plugin_reg , kmm_module_locale , khui_config_node_reg , khui_new_creds_prompt , khui_new_creds_by_type , khui_action_ref
Generated on Mon Oct 22 22:56:47 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Data Fields

  • All
  • Functions
  • Variables
  • a
  • b
  • c
  • d
  • e
  • f
  • h
  • i
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w

Here is a list of all documented struct and union fields with links to the struct/union documentation for each field:

- h -

  • h_module : khui_config_node_reg , khui_new_creds_by_type , kherr_event , kmm_module_info
  • h_plugin : kmm_plugin_info
  • header : khui_property_sheet
  • headers : khui_action_context
  • hwnd : kmq_msg_subscription , khui_new_creds , khui_property_sheet
  • hwnd_page : khui_property_sheet
  • hwnd_panel : khui_new_creds_by_type
  • hwnd_tc : khui_new_creds_by_type
Generated on Mon Oct 22 22:56:47 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Data Fields

  • All
  • Functions
  • Variables
  • a
  • b
  • c
  • d
  • e
  • f
  • h
  • i
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w

Here is a list of all documented struct and union fields with links to the struct/union documentation for each field:

- i -

  • ib_disabled : khui_action
  • ib_hot : khui_action
  • ib_icon : khui_action
  • ib_icon_dis : khui_action
  • ib_normal : khui_action
  • icon : khui_new_creds_by_type , kmm_plugin_reg
  • id : kcdb_attrib , kmq_msg_type , khui_htwnd_link
  • id_len : khui_htwnd_link
  • ident_aux : khui_new_creds
  • ident_cb : khui_new_creds
  • identities : khui_new_creds
  • identity : khui_action_context , khui_property_sheet , kcdb_cred_request
  • ih_topic : khui_action
  • index : khui_new_creds_prompt
  • int_buf : khui_action_context
  • int_cb_buf : khui_action_context
  • int_cb_used : khui_action_context
  • is_caption : khui_action
  • is_equal : kcdb_credtype
  • is_tooltip : khui_action
  • isValid : kcdb_type
  • items : khui_menu_def
Generated on Mon Oct 22 22:56:47 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Data Fields

  • All
  • Functions
  • Variables
  • a
  • b
  • c
  • d
  • e
  • f
  • h
  • i
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w

Here is a list of all documented struct and union fields with links to the struct/union documentation for each field:

- p -

  • p1 : kherr_event
  • p2 : kherr_event
  • p3 : kherr_event
  • p4 : kherr_event
  • p_action : khui_action_ref
  • param : khui_htwnd_link
  • param_len : khui_htwnd_link
  • password : khui_new_creds
  • patch : khm_version
  • path : kmm_module_reg
  • plugin_reg_info : kmm_module_reg
  • pname : khui_new_creds
  • product_version : kmm_module_info
  • progress_denom : kherr_context
  • progress_num : kherr_context
  • prompt : khui_new_creds_prompt
  • prompts : khui_new_creds
Generated on Mon Oct 22 22:56:47 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Data Fields

  • All
  • Functions
  • Variables
  • a
  • b
  • c
  • d
  • e
  • f
  • h
  • i
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w

Here is a list of all documented struct and union fields with links to the struct/union documentation for each field:

- q -

  • QDCL() : kmq_queue
  • queue : kmq_msg_subscription
Generated on Mon Oct 22 22:56:47 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Data Fields

  • All
  • Functions
  • Variables
  • a
  • b
  • c
  • d
  • e
  • f
  • h
  • i
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w

Here is a list of all documented struct and union fields with links to the struct/union documentation for each field:

- r -

  • r : khui_htwnd_link
  • rcpt_type : kmq_msg_subscription
  • recipient : kmq_message_ref
  • ref_node : khui_config_init_data
  • refcount : kmq_message , kherr_context
  • reg : kmm_module_info , kmm_plugin_info
  • reserved1 : khui_action
  • reserved2 : khui_action
  • reserved3 : khui_action
  • response : khui_new_creds
  • responses : kmq_message
  • result : khui_new_creds , kcdb_ident_name_xfer
Generated on Mon Oct 22 22:56:47 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Data Fields

  • All
  • Functions
  • Variables
  • a
  • b
  • c
  • d
  • e
  • f
  • h
  • i
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w

Here is a list of all documented struct and union fields with links to the struct/union documentation for each field:

- s -

  • scope : khui_action_context
  • semaphore : kcdb_cred_request
  • serial : kherr_context
  • set_default : khui_new_creds
  • severity : kherr_event , kherr_context
  • short_desc : kcdb_credtype , khui_config_node_reg , kherr_event , kcdb_attrib
  • state : khui_action , khui_menu_def , kmm_plugin_info , kmm_module_info
  • status : khui_property_sheet
  • sub : kcdb_credtype
  • subs : kmq_msg_type
  • subtype : khui_new_creds , kmq_message
  • suggestion : kherr_event
  • suggestion_id : kherr_event
  • support : kmm_module_reg
Generated on Mon Oct 22 22:56:47 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Data Fields

  • All
  • Functions
  • Variables
  • a
  • b
  • c
  • d
  • e
  • f
  • h
  • i
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w

Here is a list of all documented struct and union fields with links to the struct/union documentation for each field:

- t -

  • this_node : khui_config_init_data
  • thread : kmq_queue
  • thread_id : kherr_event
  • time_ft : kherr_event
  • time_ticks : kherr_event
  • timeExpire : kmq_message
  • timeSent : kmq_message
  • tooltip : khui_action , khui_new_creds_by_type
  • toString : kcdb_type
  • type : kcdb_attrib , kmq_message , kconf_schema , khui_action , kmm_plugin_reg , kmq_msg_subscription , khui_new_creds_prompt , kcdb_cred_request , khui_new_creds_by_type
  • type_deps : khui_new_creds_by_type
  • type_subs : khui_new_creds
  • types : khui_new_creds
Generated on Mon Oct 22 22:56:47 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Data Fields

  • All
  • Functions
  • Variables
  • a
  • b
  • c
  • d
  • e
  • f
  • h
  • i
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w

Here is a list of all documented struct and union fields with links to the struct/union documentation for each field:

- u -

  • uparam : kmq_message
Generated on Mon Oct 22 22:56:47 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Data Fields

  • All
  • Functions
  • Variables
  • a
  • b
  • c
  • d
  • e
  • f
  • h
  • i
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w

Here is a list of all documented struct and union fields with links to the struct/union documentation for each field:

- v -

  • value : kconf_schema , khui_new_creds_prompt
  • vendor : kmm_module_reg
  • vparam : kcdb_cred_request , kmq_message , khui_action_context
Generated on Mon Oct 22 22:56:47 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Data Fields

  • All
  • Functions
  • Variables
  • a
  • b
  • c
  • d
  • e
  • f
  • h
  • i
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w

Here is a list of all documented struct and union fields with links to the struct/union documentation for each field:

- w -

  • wait_o : kmq_message
  • window_title : khui_new_creds
Generated on Mon Oct 22 22:56:47 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Data Fields - Functions

  • All
  • Functions
  • Variables

  • LDCL() : kmq_message
  • QDCL() : kmq_queue
Generated on Mon Oct 22 22:56:47 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Data Fields - Variables

  • All
  • Functions
  • Variables
  • a
  • b
  • c
  • d
  • e
  • f
  • h
  • i
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w

- a -

  • aborted : kmq_message
  • action : khui_action_ref
  • alt_id : kcdb_attrib
  • attr_id : khui_header
  • attrib : kcdb_cred_comp_field
  • aux : khm_version , khui_new_creds_by_type
Generated on Mon Oct 22 22:56:47 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Data Fields - Variables

  • All
  • Functions
  • Variables
  • a
  • b
  • c
  • d
  • e
  • f
  • h
  • i
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w

- l -

  • language : kmm_module_info , kmm_module_locale
  • last_post : kmq_queue
  • listener : khui_action
  • load : kmq_queue
  • location : kherr_event
  • long_desc : kcdb_credtype , kherr_event , khui_config_node_reg , kcdb_attrib
Generated on Mon Oct 22 22:56:48 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Data Fields - Variables

  • All
  • Functions
  • Variables
  • a
  • b
  • c
  • d
  • e
  • f
  • h
  • i
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w

- m -

  • magic : kmq_msg_subscription , khui_action_context , kherr_event , kherr_context , khui_new_creds
  • major : khm_version
  • max : khui_tracker
  • min : khui_tracker
  • minor : khm_version
  • mode : khui_new_creds
  • module : kmm_plugin_reg
  • msg : kmq_message_ref
  • msg_proc : kmm_plugin_reg
Generated on Mon Oct 22 22:56:48 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Data Fields - Variables

  • All
  • Functions
  • Variables
  • a
  • b
  • c
  • d
  • e
  • f
  • h
  • i
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w

- n -

  • n_headers : khui_action_context
  • n_identities : khui_new_creds
  • n_items : khui_menu_def
  • n_pages : khui_property_sheet
  • n_plugins : kmm_module_reg
  • n_prompts : khui_new_creds
  • n_sel_creds : khui_action_context
  • n_type_deps : khui_new_creds_by_type
  • n_types : khui_new_creds
  • name : khui_config_node_reg , khui_new_creds_by_type , kmm_plugin_reg , kmm_module_reg , kconf_schema , kcdb_cred_request , kcdb_attrib , khui_action , kcdb_credtype , kmq_msg_type
  • name_alt : kcdb_ident_name_xfer
  • name_dest : kcdb_ident_name_xfer
  • name_src : kcdb_ident_name_xfer
  • nc : khui_new_creds_by_type
  • nc_identities : khui_new_creds
  • nc_items : khui_menu_def
  • nc_prompts : khui_new_creds
  • nc_types : khui_new_creds
  • nCompleted : kmq_message
  • nFailed : kmq_message
  • nSent : kmq_message
Generated on Mon Oct 22 22:56:48 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Data Fields - Variables

  • All
  • Functions
  • Variables
  • a
  • b
  • c
  • d
  • e
  • f
  • h
  • i
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w

- o -

  • order : kcdb_cred_comp_field
  • ordinal : khui_new_creds_by_type
Generated on Mon Oct 22 22:56:48 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Data Fields - Variables

  • All
  • Functions
  • Variables
  • a
  • b
  • c
  • d
  • e
  • f
  • h
  • i
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w

- b -

  • banner : khui_new_creds
Generated on Mon Oct 22 22:56:47 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Data Fields - Variables

  • All
  • Functions
  • Variables
  • a
  • b
  • c
  • d
  • e
  • f
  • h
  • i
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w

- c -

  • caption : khui_action
  • cb : kmq_msg_subscription
  • cb_data : khui_header
  • cb_name_dest : kcdb_ident_name_xfer
  • cb_vparam : khui_action_context
  • cmd : khui_action , khui_menu_def
  • comp : kcdb_type
  • completion_handler : kmq_msg_type
  • compute_cb : kcdb_attrib
  • compute_max_cbsize : kcdb_attrib
  • compute_min_cbsize : kcdb_attrib
  • cred : khui_action_context , khui_property_sheet
  • cred_type : khui_action_context
  • credset : khui_action_context
  • credtext : khui_new_creds_by_type
  • credtype : khui_property_sheet
  • cs : khui_new_creds
  • ctx : khui_property_sheet , khui_new_creds
  • ctx_node : khui_config_init_data
  • current : khui_tracker
Generated on Mon Oct 22 22:56:47 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Data Fields - Variables

  • All
  • Functions
  • Variables
  • a
  • b
  • c
  • d
  • e
  • f
  • h
  • i
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w

- d -

  • data : khui_action , khui_header
  • def : khui_new_creds_prompt
  • dependencies : kmm_plugin_reg
  • desc_event : kherr_context
  • description : kmm_module_reg , kconf_schema , kmm_plugin_reg
  • dest_credset : kcdb_cred_request
  • dlg_proc : khui_new_creds_by_type , khui_config_node_reg
  • dlg_template : khui_config_node_reg , khui_new_creds_by_type
  • dup : kcdb_type
Generated on Mon Oct 22 22:56:47 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Data Fields - Variables

  • All
  • Functions
  • Variables
  • a
  • b
  • c
  • d
  • e
  • f
  • h
  • i
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w

- e -

  • err_ctx : kmq_message
  • err_event : kherr_context
Generated on Mon Oct 22 22:56:47 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Data Fields - Variables

  • All
  • Functions
  • Variables
  • a
  • b
  • c
  • d
  • e
  • f
  • h
  • i
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w

- f -

  • facility : kherr_event
  • facility_id : kherr_event
  • failure_count : kmm_module_info , kmm_plugin_info
  • failure_reason : kmm_plugin_info , kmm_module_info
  • failure_time : kmm_module_info , kmm_plugin_info
  • file_version : kmm_module_info
  • filename : kmm_module_locale
  • flags : kmq_queue , kcdb_attrib , kherr_event , kmm_plugin_info , kherr_context , kmm_plugin_reg , kmm_module_locale , khui_config_node_reg , khui_new_creds_prompt , khui_new_creds_by_type , khui_action_ref
Generated on Mon Oct 22 22:56:47 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Data Fields - Variables

  • All
  • Functions
  • Variables
  • a
  • b
  • c
  • d
  • e
  • f
  • h
  • i
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w

- h -

  • h_module : khui_config_node_reg , khui_new_creds_by_type , kherr_event , kmm_module_info
  • h_plugin : kmm_plugin_info
  • header : khui_property_sheet
  • headers : khui_action_context
  • hwnd : kmq_msg_subscription , khui_new_creds , khui_property_sheet
  • hwnd_page : khui_property_sheet
  • hwnd_panel : khui_new_creds_by_type
  • hwnd_tc : khui_new_creds_by_type
Generated on Mon Oct 22 22:56:48 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Data Fields - Variables

  • All
  • Functions
  • Variables
  • a
  • b
  • c
  • d
  • e
  • f
  • h
  • i
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w

- i -

  • ib_disabled : khui_action
  • ib_hot : khui_action
  • ib_icon : khui_action
  • ib_icon_dis : khui_action
  • ib_normal : khui_action
  • icon : khui_new_creds_by_type , kmm_plugin_reg
  • id : kcdb_attrib , kmq_msg_type , khui_htwnd_link
  • id_len : khui_htwnd_link
  • ident_aux : khui_new_creds
  • ident_cb : khui_new_creds
  • identities : khui_new_creds
  • identity : khui_action_context , khui_property_sheet , kcdb_cred_request
  • ih_topic : khui_action
  • index : khui_new_creds_prompt
  • int_buf : khui_action_context
  • int_cb_buf : khui_action_context
  • int_cb_used : khui_action_context
  • is_caption : khui_action
  • is_equal : kcdb_credtype
  • is_tooltip : khui_action
  • isValid : kcdb_type
  • items : khui_menu_def
Generated on Mon Oct 22 22:56:48 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Data Fields - Variables

  • All
  • Functions
  • Variables
  • a
  • b
  • c
  • d
  • e
  • f
  • h
  • i
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w

- p -

  • p1 : kherr_event
  • p2 : kherr_event
  • p3 : kherr_event
  • p4 : kherr_event
  • p_action : khui_action_ref
  • param : khui_htwnd_link
  • param_len : khui_htwnd_link
  • password : khui_new_creds
  • patch : khm_version
  • path : kmm_module_reg
  • plugin_reg_info : kmm_module_reg
  • pname : khui_new_creds
  • product_version : kmm_module_info
  • progress_denom : kherr_context
  • progress_num : kherr_context
  • prompt : khui_new_creds_prompt
  • prompts : khui_new_creds
Generated on Mon Oct 22 22:56:48 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Data Fields - Variables

  • All
  • Functions
  • Variables
  • a
  • b
  • c
  • d
  • e
  • f
  • h
  • i
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w

- q -

  • queue : kmq_msg_subscription
Generated on Mon Oct 22 22:56:48 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Data Fields - Variables

  • All
  • Functions
  • Variables
  • a
  • b
  • c
  • d
  • e
  • f
  • h
  • i
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w

- r -

  • r : khui_htwnd_link
  • rcpt_type : kmq_msg_subscription
  • recipient : kmq_message_ref
  • ref_node : khui_config_init_data
  • refcount : kmq_message , kherr_context
  • reg : kmm_module_info , kmm_plugin_info
  • reserved1 : khui_action
  • reserved2 : khui_action
  • reserved3 : khui_action
  • response : khui_new_creds
  • responses : kmq_message
  • result : khui_new_creds , kcdb_ident_name_xfer
Generated on Mon Oct 22 22:56:48 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Data Fields - Variables

  • All
  • Functions
  • Variables
  • a
  • b
  • c
  • d
  • e
  • f
  • h
  • i
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w

- s -

  • scope : khui_action_context
  • semaphore : kcdb_cred_request
  • serial : kherr_context
  • set_default : khui_new_creds
  • severity : kherr_event , kherr_context
  • short_desc : kcdb_credtype , khui_config_node_reg , kherr_event , kcdb_attrib
  • state : khui_action , khui_menu_def , kmm_plugin_info , kmm_module_info
  • status : khui_property_sheet
  • sub : kcdb_credtype
  • subs : kmq_msg_type
  • subtype : khui_new_creds , kmq_message
  • suggestion : kherr_event
  • suggestion_id : kherr_event
  • support : kmm_module_reg
Generated on Mon Oct 22 22:56:48 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Data Fields - Variables

  • All
  • Functions
  • Variables
  • a
  • b
  • c
  • d
  • e
  • f
  • h
  • i
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w

- t -

  • this_node : khui_config_init_data
  • thread : kmq_queue
  • thread_id : kherr_event
  • time_ft : kherr_event
  • time_ticks : kherr_event
  • timeExpire : kmq_message
  • timeSent : kmq_message
  • tooltip : khui_action , khui_new_creds_by_type
  • toString : kcdb_type
  • type : kcdb_attrib , kmq_message , kconf_schema , khui_action , kmm_plugin_reg , kmq_msg_subscription , khui_new_creds_prompt , kcdb_cred_request , khui_new_creds_by_type
  • type_deps : khui_new_creds_by_type
  • type_subs : khui_new_creds
  • types : khui_new_creds
Generated on Mon Oct 22 22:56:48 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Data Fields - Variables

  • All
  • Functions
  • Variables
  • a
  • b
  • c
  • d
  • e
  • f
  • h
  • i
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w

- u -

  • uparam : kmq_message
Generated on Mon Oct 22 22:56:48 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Data Fields - Variables

  • All
  • Functions
  • Variables
  • a
  • b
  • c
  • d
  • e
  • f
  • h
  • i
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w

- v -

  • value : kconf_schema , khui_new_creds_prompt
  • vendor : kmm_module_reg
  • vparam : kcdb_cred_request , kmq_message , khui_action_context
Generated on Mon Oct 22 22:56:48 2007 for Network Identity Manager by Doxygen 1.5.3


Network Identity Manager: Data Fields - Variables

  • All
  • Functions
  • Variables
  • a
  • b
  • c
  • d
  • e
  • f
  • h
  • i
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w

- w -

  • wait_o : kmq_message
  • window_title : khui_new_creds
Generated on Mon Oct 22 22:56:48 2007 for Network Identity Manager by Doxygen 1.5.3