xpmgr/BuildTools/Include/RpcAsync.h

678 lines
15 KiB
C

/*++
Copyright (c) Microsoft Corporation. All rights reserved.
Module Name:
rpcasync.h
Abstract:
This module contains the RPC runtime APIs needed to use
[async] RPC features.
--*/
#ifndef __RPCASYNC_H__
#define __RPCASYNC_H__
#if _MSC_VER > 1000
#pragma once
#endif
#if defined(__RPC_WIN64__)
#include <pshpack8.h>
#endif
#ifdef __cplusplus
extern "C" {
#endif
#if defined(_KRPCENV_)
#include <ntddk.h>
#endif // _KRPCENV_
#if defined(RPC_NO_WINDOWS_H) || defined(_KRPCENV_)
// We've gotta have windef.h--can't live without it.
#include <windef.h>
#endif // RPC_NO_WINDOWS_H || _KRPCENV_
#define RPC_ASYNC_VERSION_1_0 sizeof(RPC_ASYNC_STATE)
typedef
enum _RPC_NOTIFICATION_TYPES
{
RpcNotificationTypeNone,
RpcNotificationTypeEvent,
#if !defined(_KRPCENV_)
RpcNotificationTypeApc,
RpcNotificationTypeIoc,
RpcNotificationTypeHwnd,
#endif
RpcNotificationTypeCallback
} RPC_NOTIFICATION_TYPES;
#if (NTDDI_VERSION >= NTDDI_VISTA)
typedef
enum _RPC_ASYNC_EVENT {
RpcCallComplete,
RpcSendComplete,
RpcReceiveComplete,
RpcClientDisconnect,
RpcClientCancel
} RPC_ASYNC_EVENT;
#else // (NTDDI_VERSION >= NTDDI_VISTA)
typedef
enum _RPC_ASYNC_EVENT {
RpcCallComplete,
RpcSendComplete,
RpcReceiveComplete,
RpcClientDisconnect
} RPC_ASYNC_EVENT;
#endif // (NTDDI_VERSION >= NTDDI_VISTA)
struct _RPC_ASYNC_STATE;
typedef void RPC_ENTRY
RPCNOTIFICATION_ROUTINE (
struct _RPC_ASYNC_STATE *pAsync,
void *Context,
RPC_ASYNC_EVENT Event);
typedef RPCNOTIFICATION_ROUTINE *PFN_RPCNOTIFICATION_ROUTINE;
typedef union _RPC_ASYNC_NOTIFICATION_INFO {
#if !defined(_KRPCENV_)
//
// Notification by APC
//
struct {
PFN_RPCNOTIFICATION_ROUTINE NotificationRoutine;
HANDLE hThread;
} APC;
#if !defined(RPC_NO_WINDOWS_H) || defined (_WINBASE_)
//
// Notification by IO completion port
//
struct {
HANDLE hIOPort;
DWORD dwNumberOfBytesTransferred;
DWORD_PTR dwCompletionKey;
LPOVERLAPPED lpOverlapped;
} IOC;
#endif // !RPC_NO_WINDOWS_H || _WINBASE_
#if !defined(RPC_NO_WINDOWS_H)
//
// Notification by window message
//
struct {
HWND hWnd;
UINT Msg;
} HWND;
#endif // RPC_NO_WINDOWS_H
#endif // _KRPCENV_
#if !defined(_KRPCENV_)
//
// Notification by event
//
HANDLE hEvent;
#else // _KRPCENV_
//
// Notification by event
//
PKEVENT Event;
#endif // _KRPCENV_
//
// Notification by callback function
//
// This option is available only to OLE
//
PFN_RPCNOTIFICATION_ROUTINE NotificationRoutine;
} RPC_ASYNC_NOTIFICATION_INFO, *PRPC_ASYNC_NOTIFICATION_INFO;
typedef struct _RPC_ASYNC_STATE {
unsigned int Size; // size of this structure
unsigned long Signature;
long Lock;
unsigned long Flags;
void *StubInfo;
void *UserInfo;
void *RuntimeInfo;
RPC_ASYNC_EVENT Event;
RPC_NOTIFICATION_TYPES NotificationType;
RPC_ASYNC_NOTIFICATION_INFO u;
LONG_PTR Reserved[4];
} RPC_ASYNC_STATE, *PRPC_ASYNC_STATE;
// Possible values for Flags
#define RPC_C_NOTIFY_ON_SEND_COMPLETE 0x1
#define RPC_C_INFINITE_TIMEOUT INFINITE
#define RpcAsyncGetCallHandle(pAsync) (((PRPC_ASYNC_STATE) pAsync)->RuntimeInfo)
RPCRTAPI
RPC_STATUS
RPC_ENTRY
RpcAsyncInitializeHandle (
__out_bcount(Size) PRPC_ASYNC_STATE pAsync,
__in unsigned int Size
);
#if !defined(_KRPCENV_)
RPCRTAPI
RPC_STATUS
RPC_ENTRY
RpcAsyncRegisterInfo (
__in PRPC_ASYNC_STATE pAsync
) ;
#endif
RPCRTAPI
RPC_STATUS
RPC_ENTRY
RpcAsyncGetCallStatus (
__in PRPC_ASYNC_STATE pAsync
) ;
RPCRTAPI
RPC_STATUS
RPC_ENTRY
RpcAsyncCompleteCall (
__inout PRPC_ASYNC_STATE pAsync,
__out_opt void *Reply
) ;
RPCRTAPI
RPC_STATUS
RPC_ENTRY
RpcAsyncAbortCall (
__inout PRPC_ASYNC_STATE pAsync,
__in unsigned long ExceptionCode
) ;
RPCRTAPI
RPC_STATUS
RPC_ENTRY
RpcAsyncCancelCall (
__inout PRPC_ASYNC_STATE pAsync,
__in BOOL fAbort
) ;
#if (NTDDI_VERSION >= NTDDI_WINXP)
// EEINFO needs k-mode or needs winbase.h
#if !defined(RPC_NO_WINDOWS_H) || defined(_KRPCENV_) || defined(_WINBASE_)
typedef enum tagExtendedErrorParamTypes
{
eeptAnsiString = 1,
eeptUnicodeString,
eeptLongVal,
eeptShortVal,
eeptPointerVal,
eeptNone,
eeptBinary
} ExtendedErrorParamTypes;
#define MaxNumberOfEEInfoParams 4
#define RPC_EEINFO_VERSION 1
typedef struct tagBinaryParam
{
void *Buffer;
short Size;
} BinaryParam;
typedef struct tagRPC_EE_INFO_PARAM
{
ExtendedErrorParamTypes ParameterType;
union
{
LPSTR AnsiString;
LPWSTR UnicodeString;
long LVal;
short SVal;
ULONGLONG PVal;
BinaryParam BVal;
} u;
} RPC_EE_INFO_PARAM;
#define EEInfoPreviousRecordsMissing 1
#define EEInfoNextRecordsMissing 2
#define EEInfoUseFileTime 4
#define EEInfoGCCOM 11
#if (NTDDI_VERSION >= NTDDI_WS03)
#define EEInfoGCFRS 12
#endif // (NTDDI_VERSION >= NTDDI_WS03)
typedef struct tagRPC_EXTENDED_ERROR_INFO
{
ULONG Version;
LPWSTR ComputerName;
ULONG ProcessID;
union
{
#if !defined(_KRPCENV_)
SYSTEMTIME SystemTime;
FILETIME FileTime;
#else // _KRPCENV_
LARGE_INTEGER KernelTime;
#endif // _KRPCENV_
} u;
ULONG GeneratingComponent;
ULONG Status;
USHORT DetectionLocation;
USHORT Flags;
int NumberOfParameters;
RPC_EE_INFO_PARAM Parameters[MaxNumberOfEEInfoParams];
} RPC_EXTENDED_ERROR_INFO;
typedef struct tagRPC_ERROR_ENUM_HANDLE
{
ULONG Signature;
void *CurrentPos;
void *Head;
} RPC_ERROR_ENUM_HANDLE;
RPCRTAPI
RPC_STATUS
RPC_ENTRY
RpcErrorStartEnumeration (
__out RPC_ERROR_ENUM_HANDLE *EnumHandle
);
RPCRTAPI
RPC_STATUS
RPC_ENTRY
RpcErrorGetNextRecord (
__in RPC_ERROR_ENUM_HANDLE *EnumHandle,
__in BOOL CopyStrings,
__out RPC_EXTENDED_ERROR_INFO *ErrorInfo
);
RPCRTAPI
RPC_STATUS
RPC_ENTRY
RpcErrorEndEnumeration (
__inout RPC_ERROR_ENUM_HANDLE *EnumHandle
);
RPCRTAPI
RPC_STATUS
RPC_ENTRY
RpcErrorResetEnumeration (
__inout RPC_ERROR_ENUM_HANDLE *EnumHandle
);
RPCRTAPI
RPC_STATUS
RPC_ENTRY
RpcErrorGetNumberOfRecords (
__in RPC_ERROR_ENUM_HANDLE *EnumHandle,
__out int *Records
);
RPCRTAPI
RPC_STATUS
RPC_ENTRY
RpcErrorSaveErrorInfo (
__in RPC_ERROR_ENUM_HANDLE *EnumHandle,
__deref_out_bcount(*BlobSize) PVOID *ErrorBlob,
__out size_t *BlobSize
);
RPCRTAPI
RPC_STATUS
RPC_ENTRY
RpcErrorLoadErrorInfo (
__in_bcount(BlobSize) PVOID ErrorBlob,
__in size_t BlobSize,
__out RPC_ERROR_ENUM_HANDLE *EnumHandle
);
RPCRTAPI
RPC_STATUS
RPC_ENTRY
RpcErrorAddRecord (
__in RPC_EXTENDED_ERROR_INFO *ErrorInfo
);
RPCRTAPI
void
RPC_ENTRY
RpcErrorClearInformation (
void
);
#endif // !RPC_NO_WINDOWS_H || _KRPCENV_ || _WINBASE_
#if !defined(_KRPCENV_)
RPCRTAPI
RPC_STATUS
RPC_ENTRY
RpcAsyncCleanupThread (
__in DWORD dwTimeout
);
RPCRTAPI
RPC_STATUS
RPC_ENTRY
RpcGetAuthorizationContextForClient (
__in_opt RPC_BINDING_HANDLE ClientBinding,
__in BOOL ImpersonateOnReturn,
__in_opt PVOID Reserved1,
__in_opt PLARGE_INTEGER pExpirationTime,
__in LUID Reserved2,
__in DWORD Reserved3,
__in_opt PVOID Reserved4,
__out PVOID *pAuthzClientContext
);
RPCRTAPI
RPC_STATUS
RPC_ENTRY
RpcFreeAuthorizationContext (
__deref PVOID *pAuthzClientContext
);
RPCRTAPI
RPC_STATUS
RPC_ENTRY
RpcSsContextLockExclusive (
__in_opt RPC_BINDING_HANDLE ServerBindingHandle,
__in PVOID UserContext
);
RPCRTAPI
RPC_STATUS
RPC_ENTRY
RpcSsContextLockShared (
__in RPC_BINDING_HANDLE ServerBindingHandle,
__in PVOID UserContext
);
#if (NTDDI_VERSION >= NTDDI_VISTA)
typedef enum tagRpcLocalAddressFormat
{
rlafInvalid = 0,
rlafIPv4,
rlafIPv6
} RpcLocalAddressFormat;
typedef struct _RPC_CALL_LOCAL_ADDRESS_V1
{
unsigned int Version;
void *Buffer;
unsigned long BufferSize;
RpcLocalAddressFormat AddressFormat;
} RPC_CALL_LOCAL_ADDRESS_V1, *PRPC_CALL_LOCAL_ADDRESS_V1;
#define RPC_CALL_ATTRIBUTES_VERSION (2)
#define RPC_QUERY_SERVER_PRINCIPAL_NAME (0x02)
#define RPC_QUERY_CLIENT_PRINCIPAL_NAME (0x04)
#define RPC_QUERY_CALL_LOCAL_ADDRESS (0x08)
#define RPC_QUERY_CLIENT_PID (0x10)
#define RPC_QUERY_IS_CLIENT_LOCAL (0x20)
#define RPC_QUERY_NO_AUTH_REQUIRED (0x40)
#endif // (NTDDI_VERSION >= NTDDI_VISTA)
#if ( (NTDDI_VERSION >= NTDDI_WINXP) && (NTDDI_VERSION < NTDDI_VISTA) )
#define RPC_CALL_ATTRIBUTES_VERSION (1)
#define RPC_QUERY_SERVER_PRINCIPAL_NAME (2)
#define RPC_QUERY_CLIENT_PRINCIPAL_NAME (4)
#endif // ( (NTDDI_VERSION >= NTDDI_WINXP) && (NTDDI_VERSION < NTDDI_VISTA) )
typedef struct tagRPC_CALL_ATTRIBUTES_V1_W
{
unsigned int Version;
unsigned long Flags;
unsigned long ServerPrincipalNameBufferLength;
unsigned short *ServerPrincipalName;
unsigned long ClientPrincipalNameBufferLength;
unsigned short *ClientPrincipalName;
unsigned long AuthenticationLevel;
unsigned long AuthenticationService;
BOOL NullSession;
} RPC_CALL_ATTRIBUTES_V1_W;
typedef struct tagRPC_CALL_ATTRIBUTES_V1_A
{
unsigned int Version;
unsigned long Flags;
unsigned long ServerPrincipalNameBufferLength;
unsigned char *ServerPrincipalName;
unsigned long ClientPrincipalNameBufferLength;
unsigned char *ClientPrincipalName;
unsigned long AuthenticationLevel;
unsigned long AuthenticationService;
BOOL NullSession;
} RPC_CALL_ATTRIBUTES_V1_A;
#if (NTDDI_VERSION >= NTDDI_VISTA)
// CallStatus bit fields
#define RPC_CALL_STATUS_CANCELLED 0x01
#define RPC_CALL_STATUS_DISCONNECTED 0x02
typedef enum tagRpcCallType
{
rctInvalid = 0,
rctNormal,
rctTraining,
rctGuaranteed
} RpcCallType;
typedef enum tagRpcCallClientLocality
{
rcclInvalid = 0,
rcclLocal,
rcclRemote,
rcclClientUnknownLocality
} RpcCallClientLocality;
typedef struct tagRPC_CALL_ATTRIBUTES_V2_W
{
unsigned int Version;
unsigned long Flags;
unsigned long ServerPrincipalNameBufferLength;
unsigned short *ServerPrincipalName;
unsigned long ClientPrincipalNameBufferLength;
unsigned short *ClientPrincipalName;
unsigned long AuthenticationLevel;
unsigned long AuthenticationService;
BOOL NullSession;
BOOL KernelModeCaller;
unsigned long ProtocolSequence;
RpcCallClientLocality IsClientLocal;
HANDLE ClientPID;
unsigned long CallStatus;
RpcCallType CallType;
RPC_CALL_LOCAL_ADDRESS_V1 *CallLocalAddress; // one of the CallLocalAddress flavors
unsigned short OpNum;
UUID InterfaceUuid;
} RPC_CALL_ATTRIBUTES_V2_W;
typedef struct tagRPC_CALL_ATTRIBUTES_V2_A
{
unsigned int Version;
unsigned long Flags;
unsigned long ServerPrincipalNameBufferLength;
unsigned char *ServerPrincipalName;
unsigned long ClientPrincipalNameBufferLength;
unsigned char *ClientPrincipalName;
unsigned long AuthenticationLevel;
unsigned long AuthenticationService;
BOOL NullSession;
BOOL KernelModeCaller;
unsigned long ProtocolSequence;
unsigned long IsClientLocal;
HANDLE ClientPID;
unsigned long CallStatus;
RpcCallType CallType;
RPC_CALL_LOCAL_ADDRESS_V1 *CallLocalAddress; // one of the CallLocalAddress flavors
unsigned short OpNum;
UUID InterfaceUuid;
} RPC_CALL_ATTRIBUTES_V2_A;
#endif // (NTDDI_VERSION >= NTDDI_VISTA)
RPCRTAPI
RPC_STATUS
RPC_ENTRY
RpcServerInqCallAttributesW (
__in_opt RPC_BINDING_HANDLE ClientBinding,
__inout void *RpcCallAttributes
);
RPCRTAPI
RPC_STATUS
RPC_ENTRY
RpcServerInqCallAttributesA (
__in_opt RPC_BINDING_HANDLE ClientBinding,
__inout void *RpcCallAttributes
);
#ifdef UNICODE
# define RPC_CALL_ATTRIBUTES_V1 RPC_CALL_ATTRIBUTES_V1_W
#if (NTDDI_VERSION >= NTDDI_VISTA)
# define RPC_CALL_ATTRIBUTES_V2 RPC_CALL_ATTRIBUTES_V2_W
#endif // (NTDDI_VERSION >= NTDDI_VISTA)
# define RpcServerInqCallAttributes RpcServerInqCallAttributesW
#else
# define RPC_CALL_ATTRIBUTES_V1 RPC_CALL_ATTRIBUTES_V1_A
#if (NTDDI_VERSION >= NTDDI_VISTA)
# define RPC_CALL_ATTRIBUTES_V2 RPC_CALL_ATTRIBUTES_V2_A
#endif // (NTDDI_VERSION >= NTDDI_VISTA)
# define RpcServerInqCallAttributes RpcServerInqCallAttributesA
#endif // !UNICODE
#if (NTDDI_VERSION >= NTDDI_VISTA)
typedef RPC_CALL_ATTRIBUTES_V2 RPC_CALL_ATTRIBUTES;
#else
typedef RPC_CALL_ATTRIBUTES_V1 RPC_CALL_ATTRIBUTES;
#endif // (NTDDI_VERSION >= NTDDI_VISTA)
#if (NTDDI_VERSION >= NTDDI_VISTA)
// can be used as flags in a bitmask too
typedef enum _RPC_NOTIFICATIONS
{
RpcNotificationCallNone = 0,
RpcNotificationClientDisconnect = 1,
RpcNotificationCallCancel = 2 // internal for Windows
} RPC_NOTIFICATIONS;
#define RpcNotificationCallStatusChange RpcNotificationClientDisconnect
RPCRTAPI
RPC_STATUS
RPC_ENTRY
RpcServerSubscribeForNotification (
__in_opt RPC_BINDING_HANDLE Binding,
__in RPC_NOTIFICATIONS Notification,
__in RPC_NOTIFICATION_TYPES NotificationType,
__in RPC_ASYNC_NOTIFICATION_INFO *NotificationInfo
);
RPCRTAPI
RPC_STATUS
RPC_ENTRY
RpcServerUnsubscribeForNotification (
__in_opt RPC_BINDING_HANDLE Binding,
__in RPC_NOTIFICATIONS Notification,
__out unsigned long *NotificationsQueued
);
#endif // (NTDDI_VERSION >= NTDDI_VISTA)
#endif // _KRPCENV_
#if (NTDDI_VERSION >= NTDDI_VISTA)
RPCRTAPI
RPC_STATUS
RPC_ENTRY
RpcBindingBind (
__in_opt PRPC_ASYNC_STATE pAsync,
__in RPC_BINDING_HANDLE Binding,
__in RPC_IF_HANDLE IfSpec
);
RPCRTAPI
RPC_STATUS
RPC_ENTRY
RpcBindingUnbind (
__in RPC_BINDING_HANDLE Binding
);
#if !defined(RPC_NO_WINDOWS_H) || defined(_KRPCENV_) || defined(_WINBASE_)
#define RPC_DE_USE_CURRENT_EEINFO (1)
RPCRTAPI
RPC_STATUS
RPC_ENTRY
RpcDiagnoseError (
__in RPC_BINDING_HANDLE BindingHandle,
__in RPC_IF_HANDLE IfSpec,
__in RPC_STATUS RpcStatus,
__in_opt RPC_ERROR_ENUM_HANDLE *EnumHandle,
__in ULONG Options,
__in_opt HWND ParentWindow
);
#endif // !RPC_NO_WINDOWS_H || _KRPCENV_ || _WINBASE_
#endif // (NTDDI_VERSION >= NTDDI_VISTA)
#endif // (NTDDI_VERSION >= NTDDI_WINXP)
//
// Internal APIs
//
RPC_STATUS RPC_ENTRY
I_RpcAsyncSetHandle (
__in PRPC_MESSAGE Message,
__in PRPC_ASYNC_STATE pAsync
);
RPC_STATUS RPC_ENTRY
I_RpcAsyncAbortCall (
__in PRPC_ASYNC_STATE pAsync,
__in unsigned long ExceptionCode
) ;
#if (NTDDI_VERSION >= NTDDI_WXP)
int
RPC_ENTRY
I_RpcExceptionFilter (
__in unsigned long ExceptionCode
);
#endif // (NTDDI_VERSION >= NTDDI_WXP)
#ifdef __cplusplus
}
#endif
#if defined(__RPC_WIN64__)
#include <poppack.h>
#endif
#endif /* __RPCASYNC_H__ */