windows-xp/Source/XPSP1/NT/net/rras/netsh/ip/sample

/*++

Copyright (c) 1999, Microsoft Corporation

Module Name:

    sample\README

Abstract:

    This file contains a brief description of the sources needed for the
    netsh extension to the sample ip routing protocol.

--*/



Netsh Commands Supported by this Helper...

netsh>routing ip sample



TOP LEVEL COMMANDS
--------------------

routing ip sample>install /?

Usage: install

Parameters:
        None.

Remarks: Installs this routing protocol under IP.

routing ip sample>uninstall /?

Usage: uninstall

Parameters:
        None.

Remarks: Removes this IP routing protocol.


routing ip sample>install /?

Usage: install
        Installs this routing protocol under IP.

routing ip sample>uninstall /?

Usage: uninstall
        Removes this IP routing protocol.


routing ip sample>dump /?

Usage: dump

Parameters:
        None

Remarks: Dumps the configuration for the current context and subcontexts.
         To save the dumped configuration redirect the output to a file.


routing ip sample>help /?

Usage: help

Parameters:
        None

Remarks: Displays help.



ADD COMMANDS
--------------------

routing ip sample>add interface /?

Usage: add interface [name =]<string> [[metric=]<ulong>]

Parameters:
        Tag        Value
        name     - Name of the interface.
        metric   - Metric associated with the interface. (default: 0)

Remarks: Configures SAMPLE on the specified interface.

Examples:
        add interface name="Local Area Connection" metric=10



DELETE COMMANDS
--------------------

routing ip sample>delete interface /?

Usage: delete interface [name =]<string>

Parameters:
        Tag        Value
        name     - Name of the interface.

Remarks: Removes SAMPLE from the specified interface.

Examples:
        delete interface name="Local Area Connection"


SET COMMANDS
--------------------

routing ip sample>set global /?

Usage: set global [[loglevel=]none|error|warn|info]

Parameters:
        Tag        Value
        loglevel - Level at which messages are logged. (default: info)

Remarks:  Sets SAMPLE global configuration parameters.

Examples:
        set global loglevel=none


routing ip sample>set interface /?

Usage: set interface [name =]<string> [[metric=]<ulong>]

Parameters:
        Tag        Value
        name     - Name of the interface.
        metric   - Metric associated with the interface. (default: 0)

Remarks:  Sets SAMPLE configuration parameters for the interface.

Examples:
        set interface name="Local Area Connection" metric=10



SHOW COMMANDS
--------------------

routing ip sample>show global /?

Usage: show global

Parameters:
        None.

Remarks:  Shows SAMPLE global configuration parameters.

Examples:
        show global


routing ip sample>show interface /?

Usage: show interface [[name =]<string>]

Parameters:
        Tag        Value
        name     - Name of the interface. (default: all interfaces)

Remarks: Shows SAMPLE configuration parameters for the interface.

Examples:
        show interface name="Local Area Connection"


routing ip sample>show globalstats /?

Usage: show globalstats [[rr=]<seconds>]

Parameters:
        Tag        Value
        rr         Display refresh rate. (default: no refresh)

Remarks: Shows SAMPLE global statistics.

Examples:
        show globalstats rr=5


routing ip sample>show ifstats /?

Usage: show ifstats [[index=]<ulong>] [[rr=]<seconds>]

Parameters:
        Tag        Value
        index    - Index/Name of the interface. (default: all interfaces)
        rr       - Display refresh rate. (default: no refresh)

Remarks: Shows SAMPLE statistics for the interface.

Examples:
        show ifstats index=1 rr=5


// given that the information presented by this command is available in some
// form in the "netsh interface ip" subcontext; this command may be considered
// redundant.  it was left there since it does little harm...  but u be the
// judge of that.  i'll stop now :)

routing ip sample>show ifbinding /?

Usage: show ifbinding [[index=]<ulong>] [[rr=]<seconds>]

Parameters:
        Tag        Value
        index    - Index/Name of the interface. (default: all interfaces)
        rr       - Display refresh rate. (default: no refresh)

Remarks: Show SAMPLE address bindings for the interface.

Examples:
        show ifbinding index="Local Area Connection" rr=5

---------------------------------------------------------------------------



Source Structure...


common.[hc]

variables and functions common to all contexts...
- DllMain:
        DLL Entry Point
- InitHelperDll:
        Registers helper (loading helper)
- IpsamplemonStartHelper:
        Registers contexts (starting helper)
- {netsh functions}
        Pointers initialized within InitHelperDll



utils.[ch]

data associated with a MIB object...
typedef struct _MAGIC_ENTRY
{
    PWCHAR                              pwszObjectName;
    DWORD                               dwObjectId;
    PGET_INDEX_FUNCTION                 pfnGetIndex;
    DWORD                               dwHeaderMessageId;
    PPRINT_FUNCTION                     pfnPrint;
} MAGIC_ENTRY, *PMAGIC_ENTRY;

utilities used by different contexts...
- IsInterfaceInstalled:
        Whether the interface has been added to the protocol
- VerifyInstalled
        Whether protocol has been installed
- GetIfIndex
        Get interface index from mib interface argument (name or index)
- MibGet
        Get MIB object specified by input key and mode (exact, first, next)
- GetString
        Get 'dump' or 'show' string for the given value.



sample.[ch]

global information for a context...
typedef struct _CONTEXT_ENTRY
{
    // context' identifying string
    PWSTR               pwszName;

    // top level (non group) commands
    ULONG               ulNumTopCmds;
    CMD_ENTRY           *pTopCmds;

    // group commands
    ULONG               ulNumGroupCmds;
    CMD_GROUP_ENTRY     *pGroupCmds;

    // default configuration
    PBYTE               pDefaultGlobal;
    PBYTE               pDefaultInterface;

    // dump function
    PNS_CONTEXT_DUMP_FN pfnDump;
} CONTEXT_ENTRY, *PCONTEXT_ENTRY;


variables and functions specific to the sample context
- g_ceSample:
        sample context entry
- SampleInitialize:
        sample context entry initialization function



samplecfg.[ch]

functions related to sample global and sample interface configuration
- SGC_Make:
        Create the default sample global configuration blob
- SGC_Show:
        Display sample global configuration
        Used for dump as well as show commands
- SGC_Update:
        Updates sample global configuration

- SIC_Make:
        Create the default sample interface configuration blob
- SIC_ShowAll
        Displays sample configuration for all interfaces
        Used for dump as well as show commands
- SIC_Show
        Displays sample configuration for an interface
        Used for dump as well as show commands
- SIC_Update
        Updates sample interface configuration        



samplegetopt.[ch]

command handlers
{
    VerifyInstalled

    PreprocessCommand

    ProcessArguments

    ProcessError

    PerformFunction
}



samplemib.[ch]

command handlers for displaying mib objects {globalstats|ifstats|ifbinding}
{
    VerifyInstalled

    FigureMibObject

    PreprocessCommand

    ProcessArguments

    ProcessError

    for(ever)           // refresh loop
    {
        for(ever)       // display table loop
        {
            MibGet
            MibDisplay
        }
    }
}





README          This file.
makefile        Used unchanged
makefile.sdk    SDK makefile
sources         Build instructions.
ipsamplemn.def  Exported function (InitHelperDll).
ipsamplemn.rc   Resource file.