Real-time collaboration for Jupyter Notebooks, Linux Terminals, LaTeX, VS Code, R IDE, and more,
all in one place.

1
//////////////////////////////////////////////////////////////////////////////
2
//
3
//  Core Detours Functionality (detours.h of detours.lib)
4
//
5
//  Microsoft Research Detours Package, Version 2.1.
6
//
7
//  Copyright (c) Microsoft Corporation.  All rights reserved.
8
//
9

10
#pragma once
11
#ifndef _DETOURS_H_
12
#define _DETOURS_H_
13

14
#define DETOURS_VERSION     20100   // 2.1.0
15

16
//////////////////////////////////////////////////////////////////////////////
17
//
18

19
#if (_MSC_VER < 1299)
20
typedef LONG LONG_PTR;
21
typedef ULONG ULONG_PTR;
22
#endif
23

24
#ifndef __in_z
25
#define __in_z
26
#endif
27

28
//////////////////////////////////////////////////////////////////////////////
29
//
30
#ifndef GUID_DEFINED
31
#define GUID_DEFINED
32
typedef struct  _GUID
33
{
34
    DWORD Data1;
35
    WORD Data2;
36
    WORD Data3;
37
    BYTE Data4[ 8 ];
38
} GUID;
39

40
#ifdef INITGUID
41
#define DEFINE_GUID(name, l, w1, w2, b1, b2, b3, b4, b5, b6, b7, b8) \
42
        const GUID name \
43
                = { l, w1, w2, { b1, b2,  b3,  b4,  b5,  b6,  b7,  b8 } }
44
#else
45
#define DEFINE_GUID(name, l, w1, w2, b1, b2, b3, b4, b5, b6, b7, b8) \
46
    const GUID name
47
#endif // INITGUID
48
#endif // !GUID_DEFINED
49

50
#if defined(__cplusplus)
51
#ifndef _REFGUID_DEFINED
52
#define _REFGUID_DEFINED
53
#define REFGUID             const GUID &
54
#endif // !_REFGUID_DEFINED
55
#else // !__cplusplus
56
#ifndef _REFGUID_DEFINED
57
#define _REFGUID_DEFINED
58
#define REFGUID             const GUID * const
59
#endif // !_REFGUID_DEFINED
60
#endif // !__cplusplus
61

62
//
63
//////////////////////////////////////////////////////////////////////////////
64

65
#ifdef __cplusplus
66
extern "C" {
67
#endif // __cplusplus
68

69
/////////////////////////////////////////////////// Instruction Target Macros.
70
//
71
#define DETOUR_INSTRUCTION_TARGET_NONE          ((PVOID)0)
72
#define DETOUR_INSTRUCTION_TARGET_DYNAMIC       ((PVOID)(LONG_PTR)-1)
73
#define DETOUR_SECTION_HEADER_SIGNATURE         0x00727444   // "Dtr\0"
74

75
extern const GUID DETOUR_EXE_RESTORE_GUID;
76

77
#define DETOUR_TRAMPOLINE_SIGNATURE             0x21727444  // Dtr!
78
typedef struct _DETOUR_TRAMPOLINE DETOUR_TRAMPOLINE, *PDETOUR_TRAMPOLINE;
79

80
/////////////////////////////////////////////////////////// Binary Structures.
81
//
82
#pragma pack(push, 8)
83
typedef struct _DETOUR_SECTION_HEADER
84
{
85
    DWORD       cbHeaderSize;
86
    DWORD       nSignature;
87
    DWORD       nDataOffset;
88
    DWORD       cbDataSize;
89

90
    DWORD       nOriginalImportVirtualAddress;
91
    DWORD       nOriginalImportSize;
92
    DWORD       nOriginalBoundImportVirtualAddress;
93
    DWORD       nOriginalBoundImportSize;
94

95
    DWORD       nOriginalIatVirtualAddress;
96
    DWORD       nOriginalIatSize;
97
    DWORD       nOriginalSizeOfImage;
98
    DWORD       cbPrePE;
99

100
    DWORD       nOriginalClrFlags;
101
    DWORD       reserved1;
102
    DWORD       reserved2;
103
    DWORD       reserved3;
104

105
    // Followed by cbPrePE bytes of data.
106
} DETOUR_SECTION_HEADER, *PDETOUR_SECTION_HEADER;
107

108
typedef struct _DETOUR_SECTION_RECORD
109
{
110
    DWORD       cbBytes;
111
    DWORD       nReserved;
112
    GUID        guid;
113
} DETOUR_SECTION_RECORD, *PDETOUR_SECTION_RECORD;
114

115
typedef struct _DETOUR_CLR_HEADER
116
{
117
    // Header versioning
118
    ULONG                   cb;
119
    USHORT                  MajorRuntimeVersion;
120
    USHORT                  MinorRuntimeVersion;
121

122
    // Symbol table and startup information
123
    IMAGE_DATA_DIRECTORY    MetaData;
124
    ULONG                   Flags;
125

126
    // Followed by the rest of the header.
127
} DETOUR_CLR_HEADER, *PDETOUR_CLR_HEADER;
128

129
typedef struct _DETOUR_EXE_RESTORE
130
{
131
    ULONG               cb;
132

133
    PIMAGE_DOS_HEADER   pidh;
134
    PIMAGE_NT_HEADERS   pinh;
135
    PULONG              pclrFlags;
136
    DWORD               impDirProt;
137

138
    IMAGE_DOS_HEADER    idh;
139
    IMAGE_NT_HEADERS    inh;
140
    ULONG               clrFlags;
141
} DETOUR_EXE_RESTORE, *PDETOUR_EXE_RESTORE;
142

143
#pragma pack(pop)
144

145
#define DETOUR_SECTION_HEADER_DECLARE(cbSectionSize) \
146
{ \
147
      sizeof(DETOUR_SECTION_HEADER),\
148
      DETOUR_SECTION_HEADER_SIGNATURE,\
149
      sizeof(DETOUR_SECTION_HEADER),\
150
      (cbSectionSize),\
151
      \
152
      0,\
153
      0,\
154
      0,\
155
      0,\
156
      \
157
      0,\
158
      0,\
159
      0,\
160
      0,\
161
}
162

163
///////////////////////////////////////////////////////////// Binary Typedefs.
164
//
165
typedef BOOL (CALLBACK *PF_DETOUR_BINARY_BYWAY_CALLBACK)(PVOID pContext,
166
                                                         PCHAR pszFile,
167
                                                         PCHAR *ppszOutFile);
168

169
typedef BOOL (CALLBACK *PF_DETOUR_BINARY_FILE_CALLBACK)(PVOID pContext,
170
                                                        PCHAR pszOrigFile,
171
                                                        PCHAR pszFile,
172
                                                        PCHAR *ppszOutFile);
173

174
typedef BOOL (CALLBACK *PF_DETOUR_BINARY_SYMBOL_CALLBACK)(PVOID pContext,
175
                                                          ULONG nOrigOrdinal,
176
                                                          ULONG nOrdinal,
177
                                                          ULONG *pnOutOrdinal,
178
                                                          PCHAR pszOrigSymbol,
179
                                                          PCHAR pszSymbol,
180
                                                          PCHAR *ppszOutSymbol);
181

182
typedef BOOL (CALLBACK *PF_DETOUR_BINARY_COMMIT_CALLBACK)(PVOID pContext);
183

184
typedef BOOL (CALLBACK *PF_DETOUR_ENUMERATE_EXPORT_CALLBACK)(PVOID pContext,
185
                                                             ULONG nOrdinal,
186
                                                             PCHAR pszName,
187
                                                             PVOID pCode);
188

189
typedef VOID * PDETOUR_BINARY;
190
typedef VOID * PDETOUR_LOADED_BINARY;
191

192
//////////////////////////////////////////////////////////// Detours 2.1 APIs.
193
//
194

195
LONG WINAPI DetourTransactionBegin();
196
LONG WINAPI DetourTransactionAbort();
197
LONG WINAPI DetourTransactionCommit();
198
LONG WINAPI DetourTransactionCommitEx(PVOID **pppFailedPointer);
199

200
LONG WINAPI DetourUpdateThread(HANDLE hThread);
201

202
LONG WINAPI DetourAttach(PVOID *ppPointer,
203
                         PVOID pDetour);
204

205
LONG WINAPI DetourAttachEx(PVOID *ppPointer,
206
                           PVOID pDetour,
207
                           PDETOUR_TRAMPOLINE *ppRealTrampoline,
208
                           PVOID *ppRealTarget,
209
                           PVOID *ppRealDetour);
210

211
LONG WINAPI DetourDetach(PVOID *ppPointer,
212
                         PVOID pDetour);
213

214
VOID WINAPI DetourSetIgnoreTooSmall(BOOL fIgnore);
215

216
////////////////////////////////////////////////////////////// Code Functions.
217
//
218
PVOID WINAPI DetourFindFunction(PCSTR pszModule, PCSTR pszFunction);
219
PVOID WINAPI DetourCodeFromPointer(PVOID pPointer, PVOID *ppGlobals);
220

221
PVOID WINAPI DetourCopyInstruction(PVOID pDst, PVOID pSrc, PVOID *ppTarget);
222
PVOID WINAPI DetourCopyInstructionEx(PVOID pDst,
223
                                     PVOID pSrc,
224
                                     PVOID *ppTarget,
225
                                     LONG *plExtra);
226

227
///////////////////////////////////////////////////// Loaded Binary Functions.
228
//
229
HMODULE WINAPI DetourEnumerateModules(HMODULE hModuleLast);
230
PVOID WINAPI DetourGetEntryPoint(HMODULE hModule);
231
ULONG WINAPI DetourGetModuleSize(HMODULE hModule);
232
BOOL WINAPI DetourEnumerateExports(HMODULE hModule,
233
                                   PVOID pContext,
234
                                   PF_DETOUR_ENUMERATE_EXPORT_CALLBACK pfExport);
235

236
PVOID WINAPI DetourFindPayload(HMODULE hModule, REFGUID rguid, DWORD *pcbData);
237
DWORD WINAPI DetourGetSizeOfPayloads(HMODULE hModule);
238

239
///////////////////////////////////////////////// Persistent Binary Functions.
240
//
241

242
PDETOUR_BINARY WINAPI DetourBinaryOpen(HANDLE hFile);
243
PVOID WINAPI DetourBinaryEnumeratePayloads(PDETOUR_BINARY pBinary,
244
                                           GUID *pGuid,
245
                                           DWORD *pcbData,
246
                                           DWORD *pnIterator);
247
PVOID WINAPI DetourBinaryFindPayload(PDETOUR_BINARY pBinary,
248
                                     REFGUID rguid,
249
                                     DWORD *pcbData);
250
PVOID WINAPI DetourBinarySetPayload(PDETOUR_BINARY pBinary,
251
                                    REFGUID rguid,
252
                                    PVOID pData,
253
                                    DWORD cbData);
254
BOOL WINAPI DetourBinaryDeletePayload(PDETOUR_BINARY pBinary, REFGUID rguid);
255
BOOL WINAPI DetourBinaryPurgePayloads(PDETOUR_BINARY pBinary);
256
BOOL WINAPI DetourBinaryResetImports(PDETOUR_BINARY pBinary);
257
BOOL WINAPI DetourBinaryEditImports(PDETOUR_BINARY pBinary,
258
                                    PVOID pContext,
259
                                    PF_DETOUR_BINARY_BYWAY_CALLBACK pfByway,
260
                                    PF_DETOUR_BINARY_FILE_CALLBACK pfFile,
261
                                    PF_DETOUR_BINARY_SYMBOL_CALLBACK pfSymbol,
262
                                    PF_DETOUR_BINARY_COMMIT_CALLBACK pfCommit);
263
BOOL WINAPI DetourBinaryWrite(PDETOUR_BINARY pBinary, HANDLE hFile);
264
BOOL WINAPI DetourBinaryClose(PDETOUR_BINARY pBinary);
265

266
/////////////////////////////////////////////////// Create Process & Load Dll.
267
//
268
typedef BOOL (WINAPI *PDETOUR_CREATE_PROCESS_ROUTINEA)
269
    (LPCSTR lpApplicationName,
270
     LPSTR lpCommandLine,
271
     LPSECURITY_ATTRIBUTES lpProcessAttributes,
272
     LPSECURITY_ATTRIBUTES lpThreadAttributes,
273
     BOOL bInheritHandles,
274
     DWORD dwCreationFlags,
275
     LPVOID lpEnvironment,
276
     LPCSTR lpCurrentDirectory,
277
     LPSTARTUPINFOA lpStartupInfo,
278
     LPPROCESS_INFORMATION lpProcessInformation);
279

280
typedef BOOL (WINAPI *PDETOUR_CREATE_PROCESS_ROUTINEW)
281
    (LPCWSTR lpApplicationName,
282
     LPWSTR lpCommandLine,
283
     LPSECURITY_ATTRIBUTES lpProcessAttributes,
284
     LPSECURITY_ATTRIBUTES lpThreadAttributes,
285
     BOOL bInheritHandles,
286
     DWORD dwCreationFlags,
287
     LPVOID lpEnvironment,
288
     LPCWSTR lpCurrentDirectory,
289
     LPSTARTUPINFOW lpStartupInfo,
290
     LPPROCESS_INFORMATION lpProcessInformation);
291

292
BOOL WINAPI DetourCreateProcessWithDllA(LPCSTR lpApplicationName,
293
                                        __in_z LPSTR lpCommandLine,
294
                                        LPSECURITY_ATTRIBUTES lpProcessAttributes,
295
                                        LPSECURITY_ATTRIBUTES lpThreadAttributes,
296
                                        BOOL bInheritHandles,
297
                                        DWORD dwCreationFlags,
298
                                        LPVOID lpEnvironment,
299
                                        LPCSTR lpCurrentDirectory,
300
                                        LPSTARTUPINFOA lpStartupInfo,
301
                                        LPPROCESS_INFORMATION lpProcessInformation,
302
                                        LPCSTR lpDetouredDllFullName,
303
                                        LPCSTR lpDllName,
304
                                        PDETOUR_CREATE_PROCESS_ROUTINEA
305
                                        pfCreateProcessA);
306

307
BOOL WINAPI DetourCreateProcessWithDllW(LPCWSTR lpApplicationName,
308
                                        __in_z LPWSTR lpCommandLine,
309
                                        LPSECURITY_ATTRIBUTES lpProcessAttributes,
310
                                        LPSECURITY_ATTRIBUTES lpThreadAttributes,
311
                                        BOOL bInheritHandles,
312
                                        DWORD dwCreationFlags,
313
                                        LPVOID lpEnvironment,
314
                                        LPCWSTR lpCurrentDirectory,
315
                                        LPSTARTUPINFOW lpStartupInfo,
316
                                        LPPROCESS_INFORMATION lpProcessInformation,
317
                                        LPCSTR lpDetouredDllFullName,
318
                                        LPCSTR lpDllName,
319
                                        PDETOUR_CREATE_PROCESS_ROUTINEW
320
                                        pfCreateProcessW);
321

322
#ifdef UNICODE
323
#define DetourCreateProcessWithDll  DetourCreateProcessWithDllW
324
#define PDETOUR_CREATE_PROCESS_ROUTINE     PDETOUR_CREATE_PROCESS_ROUTINEW
325
#else
326
#define DetourCreateProcessWithDll  DetourCreateProcessWithDllA
327
#define PDETOUR_CREATE_PROCESS_ROUTINE     PDETOUR_CREATE_PROCESS_ROUTINEA
328
#endif // !UNICODE
329

330
BOOL WINAPI DetourCopyPayloadToProcess(HANDLE hProcess,
331
                                       REFGUID rguid,
332
                                       PVOID pvData,
333
                                       DWORD cbData);
334
BOOL WINAPI DetourRestoreAfterWith();
335
BOOL WINAPI DetourRestoreAfterWithEx(PVOID pvData, DWORD cbData);
336

337
HMODULE WINAPI DetourGetDetouredMarker();
338

339
//
340
//////////////////////////////////////////////////////////////////////////////
341
#ifdef __cplusplus
342
}
343
#endif // __cplusplus
344

345
//////////////////////////////////////////////// Detours Internal Definitions.
346
//
347
#ifdef __cplusplus
348
#ifdef DETOURS_INTERNAL
349

350
#ifndef __deref_out
351
#define __deref_out
352
#endif
353

354
#ifndef __deref
355
#define __deref
356
#endif
357

358
//////////////////////////////////////////////////////////////////////////////
359
//
360
#if (_MSC_VER < 1299)
361
#include <imagehlp.h>
362
typedef IMAGEHLP_MODULE IMAGEHLP_MODULE64;
363
typedef PIMAGEHLP_MODULE PIMAGEHLP_MODULE64;
364
typedef IMAGEHLP_SYMBOL SYMBOL_INFO;
365
typedef PIMAGEHLP_SYMBOL PSYMBOL_INFO;
366

367
static inline
368
LONG InterlockedCompareExchange(LONG *ptr, LONG nval, LONG oval)
369
{
370
    return (LONG)::InterlockedCompareExchange((PVOID*)ptr, (PVOID)nval, (PVOID)oval);
371
}
372
#else
373
#include <dbghelp.h>
374
#endif
375

376
#ifdef IMAGEAPI // defined by DBGHELP.H
377
typedef LPAPI_VERSION (NTAPI *PF_ImagehlpApiVersionEx)(LPAPI_VERSION AppVersion);
378

379
typedef BOOL (NTAPI *PF_SymInitialize)(IN HANDLE hProcess,
380
                                       IN LPCSTR UserSearchPath,
381
                                       IN BOOL fInvadeProcess);
382
typedef DWORD (NTAPI *PF_SymSetOptions)(IN DWORD SymOptions);
383
typedef DWORD (NTAPI *PF_SymGetOptions)(VOID);
384
typedef DWORD64 (NTAPI *PF_SymLoadModule64)(IN HANDLE hProcess,
385
                                            IN HANDLE hFile,
386
                                            IN PSTR ImageName,
387
                                            IN PSTR ModuleName,
388
                                            IN DWORD64 BaseOfDll,
389
                                            IN DWORD SizeOfDll);
390
typedef BOOL (NTAPI *PF_SymGetModuleInfo64)(IN HANDLE hProcess,
391
                                            IN DWORD64 qwAddr,
392
                                            OUT PIMAGEHLP_MODULE64 ModuleInfo);
393
typedef BOOL (NTAPI *PF_SymFromName)(IN HANDLE hProcess,
394
                                     IN LPSTR Name,
395
                                     OUT PSYMBOL_INFO Symbol);
396

397
typedef struct _DETOUR_SYM_INFO
398
{
399
    HANDLE                  hProcess;
400
    HMODULE                 hDbgHelp;
401
    PF_ImagehlpApiVersionEx pfImagehlpApiVersionEx;
402
    PF_SymInitialize        pfSymInitialize;
403
    PF_SymSetOptions        pfSymSetOptions;
404
    PF_SymGetOptions        pfSymGetOptions;
405
    PF_SymLoadModule64      pfSymLoadModule64;
406
    PF_SymGetModuleInfo64   pfSymGetModuleInfo64;
407
    PF_SymFromName          pfSymFromName;
408
} DETOUR_SYM_INFO, *PDETOUR_SYM_INFO;
409

410
PDETOUR_SYM_INFO DetourLoadDbgHelp(VOID);
411

412
#endif // IMAGEAPI
413

414
#ifndef DETOUR_TRACE
415
#if DETOUR_DEBUG
416
#define DETOUR_TRACE(x) printf x
417
#define DETOUR_BREAK()  DebugBreak()
418
#include <stdio.h>
419
#include <limits.h>
420
#else
421
#define DETOUR_TRACE(x)
422
#define DETOUR_BREAK()
423
#endif
424
#endif
425

426
#ifdef DETOURS_IA64
427
__declspec(align(16)) struct DETOUR_IA64_BUNDLE
428
{
429
  public:
430
    union
431
    {
432
        BYTE    data[16];
433
        UINT64  wide[2];
434
    };
435

436
  public:
437
    struct DETOUR_IA64_METADATA;
438

439
    typedef BOOL (DETOUR_IA64_BUNDLE::* DETOUR_IA64_METACOPY)
440
        (const DETOUR_IA64_METADATA *pMeta, DETOUR_IA64_BUNDLE *pDst) const;
441

442
    enum {
443
        A_UNIT  = 1u,
444
        I_UNIT  = 2u,
445
        M_UNIT  = 3u,
446
        B_UNIT  = 4u,
447
        F_UNIT  = 5u,
448
        L_UNIT  = 6u,
449
        X_UNIT  = 7u,
450
        UNIT_MASK = 7u,
451
        STOP    = 8u
452
    };
453
    struct DETOUR_IA64_METADATA
454
    {
455
        ULONG       nTemplate       : 8;    // Instruction template.
456
        ULONG       nUnit0          : 4;    // Unit for slot 0
457
        ULONG       nUnit1          : 4;    // Unit for slot 1
458
        ULONG       nUnit2          : 4;    // Unit for slot 2
459
        DETOUR_IA64_METACOPY    pfCopy;     // Function pointer.
460
    };
461

462
  protected:
463
    BOOL CopyBytes(const DETOUR_IA64_METADATA *pMeta, DETOUR_IA64_BUNDLE *pDst) const;
464
    BOOL CopyBytesMMB(const DETOUR_IA64_METADATA *pMeta, DETOUR_IA64_BUNDLE *pDst) const;
465
    BOOL CopyBytesMBB(const DETOUR_IA64_METADATA *pMeta, DETOUR_IA64_BUNDLE *pDst) const;
466
    BOOL CopyBytesBBB(const DETOUR_IA64_METADATA *pMeta, DETOUR_IA64_BUNDLE *pDst) const;
467
    BOOL CopyBytesMLX(const DETOUR_IA64_METADATA *pMeta, DETOUR_IA64_BUNDLE *pDst) const;
468

469
    static const DETOUR_IA64_METADATA s_rceCopyTable[33];
470

471
  public:
472
    // 120 112 104 96 88 80 72 64 56 48 40 32 24 16  8  0
473
    //  f.  e.  d. c. b. a. 9. 8. 7. 6. 5. 4. 3. 2. 1. 0.
474

475
    //                                      00
476
    // f.e. d.c. b.a. 9.8. 7.6. 5.4. 3.2. 1.0.
477
    // 0000 0000 0000 0000 0000 0000 0000 001f : Template [4..0]
478
    // 0000 0000 0000 0000 0000 03ff ffff ffe0 : Zero [ 41..  5]
479
    // 0000 0000 0000 0000 0000 3c00 0000 0000 : Zero [ 45.. 42]
480
    // 0000 0000 0007 ffff ffff c000 0000 0000 : One  [ 82.. 46]
481
    // 0000 0000 0078 0000 0000 0000 0000 0000 : One  [ 86.. 83]
482
    // 0fff ffff ff80 0000 0000 0000 0000 0000 : Two  [123.. 87]
483
    // f000 0000 0000 0000 0000 0000 0000 0000 : Two  [127..124]
484
    BYTE    GetTemplate() const;
485
    BYTE    GetInst0() const;
486
    BYTE    GetInst1() const;
487
    BYTE    GetInst2() const;
488
    BYTE    GetUnit0() const;
489
    BYTE    GetUnit1() const;
490
    BYTE    GetUnit2() const;
491
    UINT64  GetData0() const;
492
    UINT64  GetData1() const;
493
    UINT64  GetData2() const;
494

495
  public:
496
    BOOL    IsBrl() const;
497
    VOID    SetBrl();
498
    VOID    SetBrl(UINT64 target);
499
    UINT64  GetBrlTarget() const;
500
    VOID    SetBrlTarget(UINT64 target);
501
    VOID    SetBrlImm(UINT64 imm);
502
    UINT64  GetBrlImm() const;
503

504
    BOOL    IsMovlGp() const;
505
    UINT64  GetMovlGp() const;
506
    VOID    SetMovlGp(UINT64 gp);
507

508
    VOID    SetInst0(BYTE nInst);
509
    VOID    SetInst1(BYTE nInst);
510
    VOID    SetInst2(BYTE nInst);
511
    VOID    SetData0(UINT64 nData);
512
    VOID    SetData1(UINT64 nData);
513
    VOID    SetData2(UINT64 nData);
514
    BOOL    SetNop0();
515
    BOOL    SetNop1();
516
    BOOL    SetNop2();
517
    BOOL    SetStop();
518

519
    BOOL    Copy(DETOUR_IA64_BUNDLE *pDst) const;
520
};
521
#endif // DETOURS_IA64
522

523
//////////////////////////////////////////////////////////////////////////////
524

525
#endif // DETOURS_INTERNAL
526
#endif // __cplusplus
527

528
#endif // _DETOURS_H_
529
//
530
////////////////////////////////////////////////////////////////  End of File.
531

532