windows-server-2003/base/pnp/idl/pnp.idl

/*++

Copyright (c) Microsoft Corporation.  All rights reserved.

Module Name:

    pnp.idl

Abstract:

    Contains the PnP APIs which are used to remote the plug-and-play
    APIs to the local or remote server via RPC. Also contains the RPC
    specific data structures for these API.

 **                                                                          **
 ** NEW FUNCTIONS MUST ALWAYS BE ADDED AT THE END OF THE INTERFACE BODY!!!   **
 **                                                                          **
 ** INSERTING THEM IN THE MIDDLE BREAKS BACKWARDS COMPATIBILITY, AS FUNCTION **
 ** CALLS ARE MISMATCHED WHEN CLIENT AND SERVER TALK DIFFERENT REVISIONS OF  **
 ** THE INTERFACE.                                                           **
 **                                                                          **

Author:

    Paula Tomlinson   (paulat)   06-June-1995

Environment:

    User-mode - Win32 - MIDL

Revision History:

    06-June-1995     PaulaT

        Creation and initial implementation.

Notes:

    This version of the pnp interface [version(1.0)] is NOT compatible with any
    version of Windows released prior to Windows 2000.

--*/


//
// Interface Attributes
//

[
    uuid(8D9F4E40-A03D-11CE-8F69-08003E30051B),
    version(1.0),
#ifdef __midl
    ms_union,
#endif // __midl
    pointer_default(unique)
]

//
// Interface Keyword
//

interface pnp

//
// Interface Body
//

{
import "imports.idl"; // import all the include files


//
// PnP Generic Handle used to bind from client to server.  Used by the
// client RPC binding routines PNP_HANDLE_bind, PNP_HANDLE_bind, and the
// obsolete server stubs PNP_Connect, PNP_Disconnect.
//
typedef [handle,unique] LPWSTR PNP_HANDLE;


//
// PnP Context Handles used to maintain client state on the server between
// RPC calls.  Used by server stubs PNP_RegisterNotification,
// PNP_UnregisterNotification.
//
// Note that applying the [context_handle] attribute to a type definition
// implicitly declares a server context rundown routine for that type in the
// server stubs, which must be implemented by the server.
//
typedef [context_handle] void* PNP_NOTIFICATION_CONTEXT;
typedef PNP_NOTIFICATION_CONTEXT *PPNP_NOTIFICATION_CONTEXT;


//
// Interface Function Prototypes
//
// NOTE: The names of the functions are short so that when RPC
// prepends the interface name to the names, they are still unique.
//

//----------------------------------------------------------//
// ** FUNCTIONS BELOW THIS POINT, AS DEFINED BY VERSION     //
//    1.0 OF THE PNP RPC INTERFACE, ARE ONLY AVAILABLE ON:  //
//    WINDOWS 2000 (RTM) OR LATER.                          //
//----------------------------------------------------------//

// these two routines are place holders --------------
CONFIGRET
PNP_Connect(
   [in,string,unique]        PNP_HANDLE UNCServerName
   );

CONFIGRET
PNP_Disconnect(
   [in,string,unique]        PNP_HANDLE UNCServerName
   );
// these two routines are place holders --------------

CONFIGRET
PNP_GetVersion(
   [in]                      handle_t   hBinding,
   [out]                     WORD      *pVersion
   );

CONFIGRET
PNP_GetGlobalState(
   [in]                      handle_t   hBinding,
   [out]                     PULONG     pulState,
   [in]                      ULONG      ulFlags
   );

CONFIGRET
PNP_InitDetection(
   [in]                      handle_t   hBinding
   );

CONFIGRET
PNP_ReportLogOn(
   [in]                      handle_t   hBinding,
   [in]                      BOOL       bAdmin,
   [in]                      DWORD      ProcessID
   );

CONFIGRET
PNP_ValidateDeviceInstance(
   [in]                      handle_t   hBinding,
   [in,string,ref]           LPWSTR     pDeviceID,
   [in]                      ULONG      ulFlags
   );

CONFIGRET
PNP_GetRootDeviceInstance(
   [in]                      handle_t   hBinding,
   [out,string,size_is(ulLength)] LPWSTR  pDeviceID,
   [in]                      ULONG      ulLength
   );

CONFIGRET
PNP_GetRelatedDeviceInstance(
   [in]                      handle_t   hBinding,
   [in]                      ULONG      ulRelationship,
   [in,string,ref]           LPWSTR     pDeviceID,
   [out,string,size_is(*pulLength)] LPWSTR pRelatedDeviceID,
   [in,out]                  PULONG     pulLength,
   [in]                      ULONG      ulFlags
   );

CONFIGRET
PNP_EnumerateSubKeys(
   [in]                      handle_t   hBinding,
   [in]                      ULONG      ulBranch,
   [in]                      ULONG      ulIndex,
   [out,string,size_is(ulLength)] PWSTR Buffer,
   [in]                      ULONG      ulLength,
   [out]                     PULONG     pulRequiredLen,
   [in]                      ULONG      ulFlags
   );

CONFIGRET
PNP_GetDeviceList(
   [in]                     handle_t   hBinding,
   [in,string,unique]       LPCWSTR    pszFilter,
   [out,size_is(*pulLength),length_is(*pulLength)]  LPWSTR Buffer,
   [in,out]                 PULONG     pulLength,
   [in]                     ULONG      ulFlags
   );

CONFIGRET
PNP_GetDeviceListSize(
   [in]                     handle_t   hBinding,
   [in,string,unique]       LPCWSTR    pszFilter,
   [out]                    PULONG     pulLen,
   [in]                     ULONG      ulFlags
   );

CONFIGRET
PNP_GetDepth(
   [in]                     handle_t   hBinding,
   [in,string,ref]          LPCWSTR    pszDeviceID,
   [out]                    PULONG     pulDepth,
   [in]                     ULONG      ulFlags
   );

CONFIGRET
PNP_GetDeviceRegProp(
   [in]                      handle_t   hBinding,
   [in,string,ref]           LPCWSTR    pDeviceID,
   [in]                      ULONG      ulProperty,
   [in,out]                  PULONG     pulRegDataType,
   [out,size_is(*pulTransferLen),length_is(*pulTransferLen)] LPBYTE Buffer,
   [in,out]                  PULONG     pulTransferLen,
   [in,out]                  PULONG     pulLength,
   [in]                      ULONG      ulFlags
   );

CONFIGRET
PNP_SetDeviceRegProp(
   [in]                      handle_t   hBinding,
   [in,string,ref]           LPCWSTR    pDeviceID,
   [in]                      ULONG      ulProperty,
   [in]                      ULONG      ulDataType,
   [in,size_is(ulLength)]    LPBYTE     Buffer,
   [in]                      ULONG      ulLength,
   [in]                      ULONG      ulFlags
   );

CONFIGRET
PNP_GetClassInstance(
   [in]                      handle_t   hBinding,
   [in,string,ref]           LPCWSTR    pDeviceID,
   [out,string,size_is(ulLength)] LPWSTR pszClassInstance,
   [in]                      ULONG      ulLength
   );

CONFIGRET
PNP_CreateKey(
   [in]                      handle_t   hBinding,
   [in,string,ref]           LPCWSTR    pszSubKey,
   [in]                      REGSAM     samDesired,
   [in]                      ULONG      ulFlags
   );

CONFIGRET
PNP_DeleteRegistryKey(
   [in]                      handle_t   hBinding,
   [in,string,ref]           LPCWSTR    pszDeviceID,
   [in,string,ref]           LPCWSTR    pszParentKey,
   [in,string,ref]           LPCWSTR    pszChildKey,
   [in]                      ULONG      ulFlags
   );

CONFIGRET
PNP_GetClassCount(
   [in]                      handle_t   hBinding,
   [out]                     PULONG     pulClassCount,
   [in]                      ULONG      ulFlags
   );

CONFIGRET
PNP_GetClassName(
   [in]                     handle_t   hBinding,
   [in,string,ref]          PCWSTR     pszClassGuid,
   [out,string,size_is(*pulLength)] PWSTR Buffer,
   [in,out]                 PULONG     pulLength,
   [in]                     ULONG      ulFlags
   );

CONFIGRET
PNP_DeleteClassKey(
   [in]                     handle_t   hBinding,
   [in,string,ref]          PCWSTR     pszClassGuid,
   [in]                     ULONG      ulFlags
   );

CONFIGRET
PNP_GetInterfaceDeviceAlias(
   [in]                     handle_t   hBinding,
   [in,string,ref]          PCWSTR     pszInterfaceDevice,
   [in]                     LPGUID     AliasInterfaceGuid,
   [out,string,size_is(*pulTransferLen)] PWSTR pszAliasInterfaceDevice,
   [in,out]                 PULONG     pulLength,
   [in,out]                 PULONG     pulTransferLen,
   [in]                     ULONG      ulFlags
   );

CONFIGRET
PNP_GetInterfaceDeviceList(
   [in]                     handle_t   hBinding,
   [in]                     LPGUID     InterfaceGuid,
   [in,string,unique]       LPCWSTR    pszDeviceID,
   [out,size_is(*pulLength),length_is(*pulLength)]  LPWSTR Buffer,
   [in,out]                 PULONG     pulLength,
   [in]                     ULONG      ulFlags
   );

CONFIGRET
PNP_GetInterfaceDeviceListSize(
   [in]                     handle_t   hBinding,
   [out]                    PULONG     pulLen,
   [in]                     LPGUID     InterfaceGuid,
   [in,string,unique]       LPCWSTR    pszDeviceID,
   [in]                     ULONG      ulFlags
   );

CONFIGRET
PNP_RegisterDeviceClassAssociation(
   [in]                     handle_t   hBinding,
   [in,string,unique]       LPCWSTR    pszDeviceID,
   [in]                     LPGUID     InterfaceGuid,
   [in,string,unique]       LPCWSTR    pszReference,
   [out,string,size_is(*pulTransferLen)] PWSTR pszSymLink,
   [in,out]                 PULONG     pulLength,
   [in,out]                 PULONG     pulTransferLen,
   [in]                     ULONG      ulFlags
   );

CONFIGRET
PNP_UnregisterDeviceClassAssociation(
   [in]                     handle_t   hBinding,
   [in,string,unique]       LPCWSTR    pszInterfaceDevice,
   [in]                     ULONG      ulFlags
   );

CONFIGRET
PNP_GetClassRegProp(
   [in]                      handle_t   hBinding,
   [in,string,ref]           LPCWSTR    pszClassGuid,
   [in]                      ULONG      ulProperty,
   [in,out]                  PULONG     pulRegDataType,
   [out,size_is(*pulTransferLen),length_is(*pulTransferLen)] LPBYTE Buffer,
   [in,out]                  PULONG     pulTransferLen,
   [in,out]                  PULONG     pulLength,
   [in]                      ULONG      ulFlags
   );

CONFIGRET
PNP_SetClassRegProp(
   [in]                      handle_t   hBinding,
   [in,string,ref]           LPCWSTR    pszClassGuid,
   [in]                      ULONG      ulProperty,
   [in]                      ULONG      ulDataType,
   [in,size_is(ulLength)]    LPBYTE     Buffer,
   [in]                      ULONG      ulLength,
   [in]                      ULONG      ulFlags
   );

CONFIGRET
PNP_CreateDevInst(
   [in]                     handle_t            hBinding,
   [in,out,string,size_is(ulLength)] LPWSTR pszDeviceID,
   [in,string,ref]          LPWSTR              pszParentDeviceID,
   [in]                     ULONG               ulLength,
   [in]                     ULONG               ulFlags
   );

CONFIGRET
PNP_DeviceInstanceAction(
   [in]                     handle_t            hBinding,
   [in]                     ULONG               ulMajorAction,
   [in]                     ULONG               ulMinorAction,
   [in,string,unique]       PCWSTR              pszDeviceInstance1,
   [in,string,unique]       PCWSTR              pszDeviceInstance2
   );

CONFIGRET
PNP_GetDeviceStatus(
   [in]                     handle_t            hBinding,
   [in,string,unique]       LPCWSTR             pDeviceID,
   [out]                    PULONG              pulStatus,
   [out]                    PULONG              pulProblem,
   [in]                     ULONG               ulFlags
   );

CONFIGRET
PNP_SetDeviceProblem(
   [in]                     handle_t            hBinding,
   [in,string,unique]       LPCWSTR             pDeviceID,
   [in]                     ULONG               ulProblem,
   [in]                     ULONG               ulFlags
   );

CONFIGRET
PNP_DisableDevInst(
   [in]                     handle_t            hBinding,
   [in,string,unique]       LPCWSTR             pDeviceID,
   [in,out,unique]          PPNP_VETO_TYPE      pVetoType,
   [in,out,string,max_is(ulNameLength),unique]  LPWSTR pszVetoName,
   [in]                     ULONG               ulNameLength,
   [in]                     ULONG               ulFlags
   );

CONFIGRET
PNP_UninstallDevInst(
   [in]                     handle_t            hBinding,
   [in,string,unique]       LPCWSTR             pDeviceID,
   [in]                     ULONG               ulFlags
   );

CONFIGRET
PNP_AddID(
   [in]                     handle_t            hBinding,
   [in,string,unique]       LPCWSTR             pszDeviceID,
   [in,string,ref]          LPCWSTR             pszID,
   [in]                     ULONG               ulFlags
   );

CONFIGRET
PNP_RegisterDriver(
   [in]                     handle_t            hBinding,
   [in,string,ref]          LPCWSTR             pszDeviceID,
   [in]                     ULONG               ulFlags
   );


CONFIGRET
PNP_QueryRemove(
   [in]                     handle_t            hBinding,
   [in,string,ref]          LPCWSTR             pszDeviceID,
   [in,out,unique]          PPNP_VETO_TYPE      pVetoType,
   [in,out,string,max_is(ulNameLength),unique]  LPWSTR pszVetoName,
   [in]                     ULONG               ulNameLength,
   [in]                     ULONG               ulFlags
   );

CONFIGRET
PNP_RequestDeviceEject(
   [in]                     handle_t            hBinding,
   [in,string,ref]          LPCWSTR             pszDeviceID,
   [in,out,unique]          PPNP_VETO_TYPE      pVetoType,
   [in,out,string,max_is(ulNameLength),unique]  LPWSTR pszVetoName,
   [in]                     ULONG               ulNameLength,
   [in]                     ULONG               ulFlags
   );

CONFIGRET
PNP_IsDockStationPresent (
    [in]                    handle_t   hBinding,
    [in,out,unique]         PBOOL      Present
    );

CONFIGRET
PNP_RequestEjectPC (
    [in]                    handle_t   hBinding
    );

CONFIGRET
PNP_HwProfFlags(
   [in]                     handle_t   hBinding,
   [in]                     ULONG      ulAction,
   [in,string,ref]          LPCWSTR    pDeviceID,
   [in]                     ULONG      ulConfig,
   [in,out]                 PULONG     pulValue,
   [in,out,unique]          PPNP_VETO_TYPE  pVetoType,
   [in,out,string,max_is(ulNameLength),unique]  LPWSTR pszVetoName,
   [in]                     ULONG      ulNameLength,
   [in]                     ULONG      ulFlags
   );

CONFIGRET
PNP_GetHwProfInfo(
   [in]                     handle_t   hBinding,
   [in]                     ULONG      ulIndex,
   [in,out,ref]             HWPROFILEINFO *pHWProfileInfo,
   [in]                     ULONG      ulProfileInfoSize,
   [in]                     ULONG      ulFlags
   );

CONFIGRET
PNP_AddEmptyLogConf(
   [in]                     handle_t   hBinding,
   [in,string,ref]          LPWSTR     pDeviceID,
   [in]                     ULONG      ulPriority,
   [out]                    PULONG     pulLogConfTag,
   [in]                     ULONG      ulFlags
   );

CONFIGRET
PNP_FreeLogConf(
   [in]                     handle_t   hBinding,
   [in,string,ref]          LPWSTR     pDeviceID,
   [in]                     ULONG      ulLogConfType,
   [in]                     ULONG      ulLogConfTag,
   [in]                     ULONG      ulFlags
   );

CONFIGRET
PNP_GetFirstLogConf(
   [in]                     handle_t   hBinding,
   [in,string,ref]          LPWSTR     pDeviceID,
   [in]                     ULONG      ulLogConfType,
   [out]                    PULONG     pulLogConfTag,
   [in]                     ULONG      ulFlags
   );

CONFIGRET
PNP_GetNextLogConf(
   [in]                     handle_t   hBinding,
   [in,string,ref]          LPWSTR     pDeviceID,
   [in]                     ULONG      ulLogConfType,
   [in]                     ULONG      ulCurrentTag,
   [out]                    PULONG     pulNextTag,
   [in]                     ULONG      ulFlags
   );

CONFIGRET
PNP_GetLogConfPriority(
   [in]                     handle_t    hBinding,
   [in,string,ref]          LPWSTR      pDeviceID,
   [in]                     ULONG       ulType,
   [in]                     ULONG       ulTag,
   [out]                    PULONG      pPriority,
   [in]                     ULONG       ulFlags
   );

CONFIGRET
PNP_AddResDes(
   [in]                     handle_t   hBinding,
   [in,string,ref]          LPWSTR     pDeviceID,
   [in]                     ULONG      ulLogConfTag,
   [in]                     ULONG      ulLogConfType,
   [in]                     RESOURCEID ResourceID,
   [out]                    PULONG     pulResourceTag,
   [in,size_is(ResourceLen)] LPBYTE    ResourceData,
   [in]                     ULONG      ResourceLen,
   [in]                     ULONG      ulFlags
   );

CONFIGRET
PNP_FreeResDes(
   [in]                     handle_t   hBinding,
   [in,string,ref]          LPWSTR     pDeviceID,
   [in]                     ULONG      ulLogConfTag,
   [in]                     ULONG      ulLogConfType,
   [in]                     RESOURCEID ResourceID,
   [in]                     ULONG      ulResourceTag,
   [out]                    PULONG     pulPreviousResType,
   [out]                    PULONG     pulPreviousResTag,
   [in]                     ULONG      ulFlags
   );

CONFIGRET
PNP_GetNextResDes(
   [in]                     handle_t   hBinding,
   [in,string,ref]          LPWSTR     pDeviceID,
   [in]                     ULONG      ulLogConfTag,
   [in]                     ULONG      ulLogConfType,
   [in]                     RESOURCEID ResourceID,
   [in]                     ULONG      ulResourceTag,
   [out]                    PULONG     pulNextResDesTag,
   [out]                    PULONG     pulNextResDesType,
   [in]                     ULONG      ulFlags
   );

CONFIGRET
PNP_GetResDesData(
   [in]                     handle_t   hBinding,
   [in,string,ref]          LPWSTR     pDeviceID,
   [in]                     ULONG      ulLogConfTag,
   [in]                     ULONG      ulLogConfType,
   [in]                     RESOURCEID ResourceID,
   [in]                     ULONG      ulResourceTag,
   [out,size_is(BufferLen)] LPBYTE     Buffer,
   [in]                     ULONG      BufferLen,
   [in]                     ULONG      ulFlags
   );

CONFIGRET
PNP_GetResDesDataSize(
   [in]                     handle_t   hBinding,
   [in,string,ref]          LPWSTR     pDeviceID,
   [in]                     ULONG      ulLogConfTag,
   [in]                     ULONG      ulLogConfType,
   [in]                     RESOURCEID ResourceID,
   [in]                     ULONG      ulResourceTag,
   [out]                    PULONG     pulSize,
   [in]                     ULONG      ulFlags
   );

CONFIGRET
PNP_ModifyResDes(
   [in]                     handle_t   hBinding,
   [in,string,ref]          LPWSTR     pDeviceID,
   [in]                     ULONG      ulLogConfTag,
   [in]                     ULONG      ulLogConfType,
   [in]                     RESOURCEID CurrentResourceID,
   [in]                     RESOURCEID NewResourceID,
   [in]                     ULONG      ulResourceTag,
   [in,size_is(ResourceLen)] LPBYTE    ResourceData,
   [in]                     ULONG      ResourceLen,
   [in]                     ULONG      ulFlags
   );

CONFIGRET
PNP_DetectResourceConflict(
   [in]                     handle_t   hBinding,
   [in,string,ref]          LPWSTR     pDeviceID,
   [in]                     RESOURCEID ResourceID,
   [in,size_is(ResourceLen)] LPBYTE    ResourceData,
   [in]                     ULONG      ResourceLen,
   [out]                    PBOOL      pbConflictDetected,
   [in]                     ULONG      ulFlags
   );

CONFIGRET
PNP_QueryResConfList(
   [in]                     handle_t   hBinding,
   [in,string,ref]          LPWSTR     pDeviceID,
   [in]                     RESOURCEID ResourceID,
   [in,size_is(ResourceLen)] LPBYTE    ResourceData,
   [in]                     ULONG      ResourceLen,
   [out,size_is(BufferLen)] LPBYTE     Buffer,
   [in]                     ULONG      BufferLen,
   [in]                     ULONG      ulFlags
   );

CONFIGRET
PNP_SetHwProf(
    [in]                     handle_t   hBinding,
    [in]                     ULONG      ulHardwareProfile,
    [in]                     ULONG      ulFlags
    );

CONFIGRET
PNP_QueryArbitratorFreeData(
    [in]                     handle_t   hBinding,
    [out,size_is(ulDataLen)] LPBYTE     pData,
    [in]                     ULONG      ulDataLen,
    [in,string,ref]          LPCWSTR    pszDeviceID,
    [in]                     RESOURCEID ResourceID,
    [in]                     ULONG      ulFlags
    );

CONFIGRET
PNP_QueryArbitratorFreeSize(
    [in]                     handle_t   hBinding,
    [out]                    PULONG     pulSize,
    [in,string,ref]          LPCWSTR    pszDeviceID,
    [in]                     RESOURCEID ResourceID,
    [in]                     ULONG      ulFlags
    );

CONFIGRET
PNP_RunDetection(
    [in]                     handle_t   hBinding,
    [in]                     ULONG      ulFlags
    );

CONFIGRET
PNP_RegisterNotification(
    [in]                     handle_t hBinding,
    [in]                     ULONG_PTR hRecipient,
    [in,string,ref]          LPWSTR   ServiceName,
    [in,size_is(ulSize)]     LPBYTE   NotificationFilter,
    [in]                     ULONG    ulSize,
    [in]                     DWORD    Flags,
    [out]                    PNP_NOTIFICATION_CONTEXT *Context,
    [in]                     ULONG    hProcess,
    [in]                     ULONG64  *ClientContext
    );

CONFIGRET
PNP_UnregisterNotification(
    [in]                     handle_t hBinding,
    [in,out]                 PNP_NOTIFICATION_CONTEXT *Context
    );

//----------------------------------------------------------//
// ** FUNCTIONS BELOW THIS POINT ARE ONLY AVAILABLE ON:     //
//    WINDOWS XP (RTM) OR LATER.                            //
//----------------------------------------------------------//

CONFIGRET
PNP_GetCustomDevProp(
   [in]                      handle_t   hBinding,
   [in,string,ref]           LPCWSTR    pDeviceID,
   [in,string,ref]           LPCWSTR    CustomPropName,
   [out]                     PULONG     pulRegDataType,
   [out,size_is(*pulLength),length_is(*pulTransferLen)] LPBYTE Buffer,
   [out]                     PULONG     pulTransferLen,
   [in,out]                  PULONG     pulLength,
   [in]                      ULONG      ulFlags
   );

CONFIGRET
PNP_GetVersionInternal(
   [in]                      handle_t   hBinding,
   [in,out]                  WORD      *pwVersion
   );

CONFIGRET
PNP_GetBlockedDriverInfo(
   [in]                      handle_t   hBinding,
   [out,size_is(*pulLength),length_is(*pulTransferLen)] LPBYTE Buffer,
   [out]                     PULONG     pulTransferLen,
   [in,out]                  PULONG     pulLength,
   [in]                      ULONG      ulFlags
   );

CONFIGRET
PNP_GetServerSideDeviceInstallFlags(
   [in]                      handle_t   hBinding,
   [out]                     PULONG     pulSSDIFlags,
   [in]                      ULONG      ulFlags
   );

//----------------------------------------------------------//
// ** FUNCTIONS BELOW THIS POINT ARE ONLY AVAILABLE ON:     //
//    WINDOWS XP (SP1) / WINDOWS .NET OR LATER.             //
//----------------------------------------------------------//

//----------------------------------------------------------//
// ** ADD NEW INTERFACES HERE                               //
//----------------------------------------------------------//

}