        Program Interface for C2Config Dll's

Written: 7-Feb-95  
Revisions:  none

Overview

    The C2Config utility provides an extensible interface for adding 
    additional security functions to be displayed and controlled from 
    the C2Config list. These functions are provided in the form 
    of a dynamic-link library (DLL) that is referenced in the 
    C2CONFIG.INF file. This file describes the interface requirements
    for these additional functions.

    A C2Config DLL must include the C2DLL.H file for the structure
    definitions used between the main application program and the DLL.
    The DLL must also supply the following exported entry points for use
    by the application (the actual function names may be defined by the
    DLL developer). The following function names will be used in this
    description when referencing the DLL functions.

        GetStatusFunction
        UserInterfaceFunction
        SetStatusFunction

    The actual function names defined in the DLL must be listed in the
    C2CONFIG.INF file for them to be recognized by the application.

GetStatusFunction

    When the application is first started and whenever the Refresh
    display menu item is selected, the  GetStatusFunction for each
    item is called to determine the current status of that item.
    The application calls the function, passing the pointer to a 
    C2DLL_DATA data structure initialized as follows:

        lActionCode     = 0
        lActionValue    = 0
        hWnd            = window handle to main app window
        lC2Compliance   = C2DLL_NOT_SECURE;
        szItemName      = ItemName as read from C2CONFIG.INF file
        szStatusName    = Empty String (all null chars) on first
                            call, previous status on all subsequent
                            calls

    The GetStatusFunction then determines the current state of the
    item it is responsible for and fills in the following fields
    of the C2DLL_DATA structure whose pointer was passed in the 
    argument list:

        lActionCode     =  (not used)
        lActionValue    =  (not used)
        hWnd            =  (not changed)
        lC2Compliance   = Current compliance value
        szItemName      =  (not changed)
        szStatusName    = string describing current status of this
                            item
    
    After detecting the current status of the security item and
    filling in the C2DLL_DATA structure, the function returns the
    WIN32 error status value describing the success or failure of the
    function call. The data returned will be assumed valid only if
    the return status is ERROR_SUCCESS;
    
UserInterfaceFunction

    The User Interface Function is called when the user double-clicks
    or otherwise selects a security item from the list displayed in
    the main application window. The purpose of this function is to
    allow the user to change the current state of the selected item.

    When the item is selected, the function is called, passing a
    pointer to the C2DLL_DATA structure as the only argument. The 
    fields in the structure are initialized as follows:

        lActionCode     = 0
        lActionValue    = 0
        hWnd            = the window handle of the main app window
        lC2Compliance   = the current compliance value as returned by
                            the last GetStatusFunction call
        szItemName      = the name string for this item as read from
                            the C2CONFIG.INF file
        szStatusName    = the string describing the current status of
                            this item as returned by the last call to
                            the GetStatusFunction

    The Display function will present the necessary user interface to
    the user for their input and then fill the following fields of
    the C2DLL_DATA block referenced by the pointer passed in the
    argument list:

        lActionCode     = code describing action to take in order to
                            perform task selected by user. 
                            0 == no change or no action
        lActionValue    = value to be used, if necessary, if the 
                            lActionCode is not 0
        hWnd            =  (not changed)
        lC2Compliance   =  (not changed)
        szItemName      =  (not changed)
        szStatusName    =  (not changed)

    The UserInterfaceFunction returns a Win32 error status value as 
    the return value of the function to indicate if the function was
    successful or not. If the return code is not ERROR_SUCCESS, then
    the returned data is ignored.

SetStatusFunction

    If the lActionCode field in the data structure returned by the
    UserInterfaceFunction is not 0, then the SetStatusFunction is
    called. The C2DLL_DATA structure passed to the SetStatusFunction
    is unchanged from the data returned by the UserInterfaceFunction.

    The SetStatusFunction performs the action defined in the
    lActionCode field of the structure, using the lActionValue
    field as necessary. If the status of the item is changed, then 
    this routine must update the following fields in the data
    structure.

        lActionCode     = set to 0
        lActionValue    = set to 0
        hWnd            =  (not changed)
        lC2Compliance   = set to the current state (as a result of
                            the change)
        szItemName      =  (not changed)
        szStatusName    = set to the current state (as a result of
                            the change)

    The SetStatusFunction returns a Win32 error status code to
    indicate the success or failure of the function, and the list
    entry in the main application window is updated to show the 
    current status of this item.

C2CONFIG.INF

    Each entry in the main application window is described in the
    C2CONFIG.INF file. The file consists of a single section under the
    [C2 Security Items] section heading. Under that section, each
    entry consists of the following elements:

        Item Name   = this is the string to be displayed in the
                        application window under the "Security 
                        Feature" heading. Make sure the text is
                        not so long as to be truncated in the
                        display.

        DLL         = the filename of the DLL that contains the
                        functions that follow in the entry. 
                        The DLL must be located in one of the
                        following directories in order to be
                        recognized by the application:

                            The current directory
                            The WINDOWS (%systemroot%) directory
                            The SYSTEM (%systemroot%\SYSTEM32) directory                                                     
                            The directory containing C2CONFIG.EXE
                            a directory in the "Path"

        QueryFn     = the exported function name found in the DLL
                        file mentioned above that performs the 
                        GetStatusFunction service described above.

        SetFn     = the exported function name found in the DLL
                        file mentioned above that performs the 
                        SetStatusFunction service described above.

        UserInterfaceFn     = the exported function name found in the 
                        DLL file mentioned above that performs the 
                        UserInterfaceFunction service described above.

        RebootIfChanged = "1" if changing this feature requires the
                        system to be restarted in order for the
                        change to take effect. Otherwise, this value 
                        should be a "0".

