home *** CD-ROM | disk | FTP | other *** search
/ Magazyn Internet 2000 May / MICD_2000_05.iso / CBuilder5 / INSTALL / DATA1.CAB / Program_Built_Files / Include / rtutils.h < prev    next >
C/C++ Source or Header  |  2000-02-01  |  39KB  |  1,101 lines
  1. /*++
  2.  
  3. Copyright (c) 1995-1999  Microsoft Corporation
  4.  
  5. Module Name:
  6.  
  7.     rtutils.h
  8.  
  9. Abstract:
  10.      Public declarations for the Router process  utility functions.
  11.  
  12. --*/
  13.  
  14. #ifndef __ROUTING_RTUTILS_H__
  15. #pragma option push -b -a8 -pc -A- /*P_O_Push*/
  16. #define __ROUTING_RTUTILS_H__
  17.  
  18. #if _MSC_VER > 1000
  19. #pragma once
  20. #endif
  21.  
  22. #ifdef __cplusplus
  23. extern "C" {
  24. #endif
  25.  
  26.  
  27. //////////////////////////////////////////////////////////////////////////////
  28. //                                                                          //
  29. // TRACING FUNCTION PROTOTYPES                                              //
  30. //                                                                          //
  31. // See DOCUMENT for more information                                        //
  32. //                                                                          //
  33. //////////////////////////////////////////////////////////////////////////////
  34.  
  35. //////////////////////////////////////////////////////////////////////////////
  36. //                                                                          //
  37. // Definitions for flags and constants                                      //
  38. //                                                                          //
  39. //////////////////////////////////////////////////////////////////////////////
  40.  
  41. #define TRACE_USE_FILE      0x00000001
  42. #define TRACE_USE_CONSOLE   0x00000002
  43. #define TRACE_NO_SYNCH      0x00000004
  44.  
  45. #define TRACE_NO_STDINFO    0x00000001
  46. #define TRACE_USE_MASK      0x00000002
  47. #define TRACE_USE_MSEC      0x00000004
  48.  
  49. #define INVALID_TRACEID     0xFFFFFFFF
  50.  
  51.  
  52. //////////////////////////////////////////////////////////////////////////////
  53. //                                                                          //
  54. // ANSI entry-points                                                        //
  55. //                                                                          //
  56. //////////////////////////////////////////////////////////////////////////////
  57.  
  58. DWORD
  59. APIENTRY
  60. TraceRegisterExA(
  61.     IN  LPCSTR      lpszCallerName,
  62.     IN  DWORD       dwFlags
  63.     );
  64.  
  65. DWORD
  66. APIENTRY
  67. TraceDeregisterA(
  68.     IN  DWORD       dwTraceID
  69.     );
  70.  
  71. DWORD
  72. APIENTRY
  73. TraceDeregisterExA(
  74.     IN  DWORD       dwTraceID,
  75.     IN  DWORD       dwFlags
  76.     );
  77.  
  78. DWORD
  79. APIENTRY
  80. TraceGetConsoleA(
  81.     IN  DWORD       dwTraceID,
  82.     OUT LPHANDLE    lphConsole
  83.     );
  84.  
  85. DWORD
  86. APIENTRY
  87. TracePrintfA(
  88.     IN  DWORD       dwTraceID,
  89.     IN  LPCSTR      lpszFormat,
  90.     IN  ...         OPTIONAL
  91.     );
  92.  
  93. DWORD
  94. APIENTRY
  95. TracePrintfExA(
  96.     IN  DWORD       dwTraceID,
  97.     IN  DWORD       dwFlags,
  98.     IN  LPCSTR      lpszFormat,
  99.     IN  ...         OPTIONAL
  100.     );
  101.  
  102. DWORD
  103. APIENTRY
  104. TraceVprintfExA(
  105.     IN  DWORD       dwTraceID,
  106.     IN  DWORD       dwFlags,
  107.     IN  LPCSTR      lpszFormat,
  108.     IN  va_list     arglist
  109.     );
  110.  
  111. DWORD
  112. APIENTRY
  113. TracePutsExA(
  114.     IN  DWORD       dwTraceID,
  115.     IN  DWORD       dwFlags,
  116.     IN  LPCSTR      lpszString
  117.     );
  118.  
  119. DWORD
  120. APIENTRY
  121. TraceDumpExA(
  122.     IN  DWORD       dwTraceID,
  123.     IN  DWORD       dwFlags,
  124.     IN  LPBYTE      lpbBytes,
  125.     IN  DWORD       dwByteCount,
  126.     IN  DWORD       dwGroupSize,
  127.     IN  BOOL        bAddressPrefix,
  128.     IN  LPCSTR      lpszPrefix
  129.     );
  130.  
  131.  
  132. //////////////////////////////////////////////////////////////////////////////
  133. //                                                                          //
  134. // ANSI entry-points macros                                                 //
  135. //                                                                          //
  136. //////////////////////////////////////////////////////////////////////////////
  137.  
  138. #define TraceRegisterA(a)               TraceRegisterExA(a,0)
  139. #define TraceVprintfA(a,b,c)            TraceVprintfExA(a,0,b,c)
  140. #define TracePutsA(a,b)                 TracePutsExA(a,0,b)
  141. #define TraceDumpA(a,b,c,d,e,f)         TraceDumpExA(a,0,b,c,d,e,f)
  142.  
  143.  
  144.  
  145. //////////////////////////////////////////////////////////////////////////////
  146. //                                                                          //
  147. // Unicode entry-points                                                     //
  148. //                                                                          //
  149. //////////////////////////////////////////////////////////////////////////////
  150.  
  151. DWORD
  152. APIENTRY
  153. TraceRegisterExW(
  154.     IN  LPCWSTR     lpszCallerName,
  155.     IN  DWORD       dwFlags
  156.     );
  157.  
  158. DWORD
  159. APIENTRY
  160. TraceDeregisterW(
  161.     IN  DWORD       dwTraceID
  162.     );
  163.  
  164. DWORD
  165. APIENTRY
  166. TraceDeregisterExW(
  167.     IN  DWORD       dwTraceID,
  168.     IN  DWORD       dwFlags
  169.     );
  170.  
  171. DWORD
  172. APIENTRY
  173. TraceGetConsoleW(
  174.     IN  DWORD       dwTraceID,
  175.     OUT LPHANDLE    lphConsole
  176.     );
  177.  
  178. DWORD
  179. APIENTRY
  180. TracePrintfW(
  181.     IN  DWORD       dwTraceID,
  182.     IN  LPCWSTR     lpszFormat,
  183.     IN  ...         OPTIONAL
  184.     );
  185.  
  186. DWORD
  187. APIENTRY
  188. TracePrintfExW(
  189.     IN  DWORD       dwTraceID,
  190.     IN  DWORD       dwFlags,
  191.     IN  LPCWSTR     lpszFormat,
  192.     IN  ...         OPTIONAL
  193.     );
  194.  
  195. DWORD
  196. APIENTRY
  197. TraceVprintfExW(
  198.     IN  DWORD       dwTraceID,
  199.     IN  DWORD       dwFlags,
  200.     IN  LPCWSTR     lpszFormat,
  201.     IN  va_list     arglist
  202.     );
  203.  
  204. DWORD
  205. APIENTRY
  206. TracePutsExW(
  207.     IN  DWORD       dwTraceID,
  208.     IN  DWORD       dwFlags,
  209.     IN  LPCWSTR     lpszString
  210.     );
  211.  
  212. DWORD
  213. APIENTRY
  214. TraceDumpExW(
  215.     IN  DWORD       dwTraceID,
  216.     IN  DWORD       dwFlags,
  217.     IN  LPBYTE      lpbBytes,
  218.     IN  DWORD       dwByteCount,
  219.     IN  DWORD       dwGroupSize,
  220.     IN  BOOL        bAddressPrefix,
  221.     IN  LPCWSTR     lpszPrefix
  222.     );
  223.  
  224.  
  225. //////////////////////////////////////////////////////////////////////////////
  226. //                                                                          //
  227. // Unicode entry-points macros                                              //
  228. //                                                                          //
  229. //////////////////////////////////////////////////////////////////////////////
  230.  
  231. #define TraceRegisterW(a)               TraceRegisterExW(a,0)
  232. #define TraceVprintfW(a,b,c)            TraceVprintfExW(a,0,b,c)
  233. #define TracePutsW(a,b)                 TracePutsExW(a,0,b)
  234. #define TraceDumpW(a,b,c,d,e,f)         TraceDumpExW(a,0,b,c,d,e,f)
  235.  
  236.  
  237.  
  238. //////////////////////////////////////////////////////////////////////////////
  239. //                                                                          //
  240. // Code-page dependent entry-point macros                                   //
  241. //                                                                          //
  242. //////////////////////////////////////////////////////////////////////////////
  243.  
  244. #ifdef UNICODE
  245. #define TraceRegister           TraceRegisterW
  246. #define TraceDeregister         TraceDeregisterW
  247. #define TraceDeregisterEx       TraceDeregisterExW
  248. #define TraceGetConsole         TraceGetConsoleW
  249. #define TracePrintf             TracePrintfW
  250. #define TraceVprintf            TraceVprintfW
  251. #define TracePuts               TracePutsW
  252. #define TraceDump               TraceDumpW
  253. #define TraceRegisterEx         TraceRegisterExW
  254. #define TracePrintfEx           TracePrintfExW
  255. #define TraceVprintfEx          TraceVprintfExW
  256. #define TracePutsEx             TracePutsExW
  257. #define TraceDumpEx             TraceDumpExW
  258. #else
  259. #define TraceRegister           TraceRegisterA
  260. #define TraceDeregister         TraceDeregisterA
  261. #define TraceDeregisterEx       TraceDeregisterExA
  262. #define TraceGetConsole         TraceGetConsoleA
  263. #define TracePrintf             TracePrintfA
  264. #define TraceVprintf            TraceVprintfA
  265. #define TracePuts               TracePutsA
  266. #define TraceDump               TraceDumpA
  267. #define TraceRegisterEx         TraceRegisterExA
  268. #define TracePrintfEx           TracePrintfExA
  269. #define TraceVprintfEx          TraceVprintfExA
  270. #define TracePutsEx             TracePutsExA
  271. #define TraceDumpEx             TraceDumpExA
  272. #endif
  273.  
  274.  
  275.  
  276. //////////////////////////////////////////////////////////////////////////////
  277. //                                                                          //
  278. // EVENT LOGGING FUNCTION PROTOTYPES                                        //
  279. //                                                                          //
  280. //////////////////////////////////////////////////////////////////////////////
  281.  
  282. //////////////////////////////////////////////////////////////////////////////
  283. //                                                                          //
  284. // ANSI prototypes                                                          //
  285. //                                                                          //
  286. //////////////////////////////////////////////////////////////////////////////
  287.  
  288.  
  289. VOID
  290. APIENTRY
  291. LogErrorA(
  292.     IN DWORD    dwMessageId,
  293.     IN DWORD    cNumberOfSubStrings,
  294.     IN LPSTR   *plpwsSubStrings,
  295.     IN DWORD    dwErrorCode
  296. );
  297.  
  298. VOID
  299. APIENTRY
  300. LogEventA(
  301.     IN DWORD   wEventType,
  302.     IN DWORD   dwMessageId,
  303.     IN DWORD   cNumberOfSubStrings,
  304.     IN LPSTR  *plpwsSubStrings
  305. );
  306.  
  307.  
  308. //////////////////////////////////////////////////////////////////////////////
  309. //                                                                          //
  310. // Unicode prototypes                                                       //
  311. //                                                                          //
  312. //////////////////////////////////////////////////////////////////////////////
  313.  
  314. VOID
  315. LogErrorW(
  316.     IN DWORD    dwMessageId,
  317.     IN DWORD    cNumberOfSubStrings,
  318.     IN LPWSTR  *plpwsSubStrings,
  319.     IN DWORD    dwErrorCode
  320. );
  321.  
  322. VOID
  323. LogEventW(
  324.     IN DWORD   wEventType,
  325.     IN DWORD   dwMessageId,
  326.     IN DWORD   cNumberOfSubStrings,
  327.     IN LPWSTR *plpwsSubStrings
  328. );
  329.  
  330.  
  331. #ifdef UNICODE
  332. #define LogError                LogErrorW
  333. #define LogEvent                LogEventW
  334. #else
  335. #define LogError                LogErrorA
  336. #define LogEvent                LogEventA
  337. #endif
  338.  
  339.  
  340. //////////////////////////////////////////////////////////////////////////////
  341. //                                                                          //
  342. // The following functions allow the caller to specify the event source.    //
  343. //                                                                          //
  344. // Call RouterLogRegister with the strings which would be passed to         //
  345. // RegisterEventSource; this returns a handle which can be passed           //
  346. // to the functions RouterLogEvent and RouterLogEventData.                  //
  347. //                                                                          //
  348. // Call RouterLogDeregister to close the handle.                            //
  349. //                                                                          //
  350. // Macros are provided for the different kinds of event log entrys:         //
  351. //  RouterLogError          logs an error (EVENTLOG_ERROR_TYPE)             //
  352. //  RouterLogWarning        logs a warning (EVENTLOG_WARNING_TYPE)          //
  353. //  RouterLogInformation    logs information (EVENTLOG_INFORMATION_TYPE)    //
  354. //                                                                          //
  355. //////////////////////////////////////////////////////////////////////////////
  356.  
  357. //////////////////////////////////////////////////////////////////////////////
  358. //                                                                          //
  359. // ANSI prototypes                                                          //
  360. //                                                                          //
  361. //////////////////////////////////////////////////////////////////////////////
  362.  
  363. HANDLE
  364. RouterLogRegisterA(
  365.     LPCSTR lpszSource
  366.     );
  367.  
  368. VOID
  369. RouterLogDeregisterA(
  370.     HANDLE hLogHandle
  371.     );
  372.  
  373. VOID
  374. RouterLogEventA(
  375.     IN HANDLE hLogHandle,
  376.     IN DWORD dwEventType,
  377.     IN DWORD dwMessageId,
  378.     IN DWORD dwSubStringCount,
  379.     IN LPSTR *plpszSubStringArray,
  380.     IN DWORD dwErrorCode
  381.     );
  382.  
  383. VOID
  384. RouterLogEventDataA(
  385.     IN HANDLE hLogHandle,
  386.     IN DWORD dwEventType,
  387.     IN DWORD dwMessageId,
  388.     IN DWORD dwSubStringCount,
  389.     IN LPSTR *plpszSubStringArray,
  390.     IN DWORD dwDataBytes,
  391.     IN LPBYTE lpDataBytes
  392.     );
  393.  
  394. VOID
  395. RouterLogEventStringA(
  396.     IN HANDLE hLogHandle,
  397.     IN DWORD dwEventType,
  398.     IN DWORD dwMessageId,
  399.     IN DWORD dwSubStringCount,
  400.     IN LPSTR *plpszSubStringArray,
  401.     IN DWORD dwErrorCode,
  402.     IN DWORD dwErrorIndex
  403.     );
  404.  
  405. VOID
  406. RouterLogEventExA(
  407.     IN HANDLE   hLogHandle,
  408.     IN DWORD    dwEventType,
  409.     IN DWORD    dwErrorCode,
  410.     IN DWORD    dwMessageId,
  411.     IN LPCSTR   ptszFormat,
  412.     ...
  413.     );
  414.  
  415. VOID
  416. RouterLogEventValistExA(
  417.     IN HANDLE   hLogHandle,
  418.     IN DWORD    dwEventType,
  419.     IN DWORD    dwErrorCode,
  420.     IN DWORD    dwMessageId,
  421.     IN LPCSTR   ptszFormat,
  422.     IN va_list  arglist
  423.     );
  424.  
  425. DWORD
  426. RouterGetErrorStringA(
  427.     IN  DWORD   dwErrorCode,
  428.     OUT LPSTR * lplpszErrorString
  429.     );
  430.  
  431. #define RouterLogErrorA(h,msg,count,array,err) \
  432.         RouterLogEventA(h,EVENTLOG_ERROR_TYPE,msg,count,array,err)
  433. #define RouterLogWarningA(h,msg,count,array,err) \
  434.         RouterLogEventA(h,EVENTLOG_WARNING_TYPE,msg,count,array,err)
  435. #define RouterLogInformationA(h,msg,count,array,err) \
  436.         RouterLogEventA(h,EVENTLOG_INFORMATION_TYPE,msg,count,array,err)
  437.  
  438. #define RouterLogErrorDataA(h,msg,count,array,c,buf) \
  439.         RouterLogEventDataA(h,EVENTLOG_ERROR_TYPE,msg,count,array,c,buf)
  440. #define RouterLogWarningDataA(h,msg,count,array,c,buf) \
  441.         RouterLogEventDataA(h,EVENTLOG_WARNING_TYPE,msg,count,array,c,buf)
  442. #define RouterLogInformationDataA(h,msg,count,array,c,buf) \
  443.         RouterLogEventDataA(h,EVENTLOG_INFORMATION_TYPE,msg,count,array,c,buf)
  444.  
  445. #define RouterLogErrorStringA(h,msg,count,array,err,index) \
  446.         RouterLogEventStringA(h,EVENTLOG_ERROR_TYPE,msg,count,array, err,index)
  447. #define RouterLogWarningStringA(h,msg,count,array,err,index) \
  448.         RouterLogEventStringA(h,EVENTLOG_WARNING_TYPE,msg,count,array,err,index)
  449. #define RouterLogInformationStringA(h,msg,count,array, err,index) \
  450.         RouterLogEventStringA(h,EVENTLOG_INFORMATION_TYPE,msg,count,array,err,\
  451.                               index)
  452.  
  453.  
  454. //////////////////////////////////////////////////////////////////////////////
  455. //                                                                          //
  456. // Unicode prototypes                                                       //
  457. //                                                                          //
  458. //////////////////////////////////////////////////////////////////////////////
  459.  
  460. HANDLE
  461. RouterLogRegisterW(
  462.     LPCWSTR lpszSource
  463.     );
  464.  
  465. VOID
  466. RouterLogDeregisterW(
  467.     HANDLE hLogHandle
  468.     );
  469.  
  470. VOID
  471. RouterLogEventW(
  472.     IN HANDLE hLogHandle,
  473.     IN DWORD dwEventType,
  474.     IN DWORD dwMessageId,
  475.     IN DWORD dwSubStringCount,
  476.     IN LPWSTR *plpszSubStringArray,
  477.     IN DWORD dwErrorCode
  478.     );
  479.  
  480. VOID
  481. RouterLogEventDataW(
  482.     IN HANDLE hLogHandle,
  483.     IN DWORD dwEventType,
  484.     IN DWORD dwMessageId,
  485.     IN DWORD dwSubStringCount,
  486.     IN LPWSTR *plpszSubStringArray,
  487.     IN DWORD dwDataBytes,
  488.     IN LPBYTE lpDataBytes
  489.     );
  490.  
  491. VOID
  492. RouterLogEventStringW(
  493.     IN HANDLE hLogHandle,
  494.     IN DWORD dwEventType,
  495.     IN DWORD dwMessageId,
  496.     IN DWORD dwSubStringCount,
  497.     IN LPWSTR *plpszSubStringArray,
  498.     IN DWORD dwErrorCode,
  499.     IN DWORD dwErrorIndex
  500.     );
  501.  
  502. VOID
  503. RouterLogEventExW(
  504.     IN HANDLE   hLogHandle,
  505.     IN DWORD    dwEventType,
  506.     IN DWORD    dwErrorCode,
  507.     IN DWORD    dwMessageId,
  508.     IN LPCWSTR  ptszFormat,
  509.     ...
  510.     );
  511.  
  512. VOID
  513. RouterLogEventValistExW(
  514.     IN HANDLE   hLogHandle,
  515.     IN DWORD    dwEventType,
  516.     IN DWORD    dwErrorCode,
  517.     IN DWORD    dwMessageId,
  518.     IN LPCWSTR  ptszFormat,
  519.     IN va_list  arglist
  520.     );
  521.  
  522. DWORD
  523. RouterGetErrorStringW(
  524.     IN  DWORD    dwErrorCode,
  525.     OUT LPWSTR * lplpwszErrorString
  526.     );
  527.  
  528.  
  529. #define RouterLogErrorW(h,msg,count,array,err) \
  530.         RouterLogEventW(h,EVENTLOG_ERROR_TYPE,msg,count,array,err)
  531. #define RouterLogWarningW(h,msg,count,array,err) \
  532.         RouterLogEventW(h,EVENTLOG_WARNING_TYPE,msg,count,array,err)
  533. #define RouterLogInformationW(h,msg,count,array,err) \
  534.         RouterLogEventW(h,EVENTLOG_INFORMATION_TYPE,msg,count,array,err)
  535.  
  536. #define RouterLogErrorDataW(h,msg,count,array,c,buf) \
  537.         RouterLogEventDataW(h,EVENTLOG_ERROR_TYPE,msg,count,array,c,buf)
  538. #define RouterLogWarningDataW(h,msg,count,array,c,buf) \
  539.         RouterLogEventDataW(h,EVENTLOG_WARNING_TYPE,msg,count,array,c,buf)
  540. #define RouterLogInformationDataW(h,msg,count,array,c,buf) \
  541.         RouterLogEventDataW(h,EVENTLOG_INFORMATION_TYPE,msg,count,array,c,buf)
  542.  
  543. #define RouterLogErrorStringW(h,msg,count,array,err,index) \
  544.         RouterLogEventStringW(h,EVENTLOG_ERROR_TYPE,msg,count,array,err,index)
  545. #define RouterLogWarningStringW(h,msg,count,array,err,index) \
  546.         RouterLogEventStringW(h,EVENTLOG_WARNING_TYPE,msg,count,array,err,index)
  547. #define RouterLogInformationStringW(h,msg,count,array,err,index) \
  548.         RouterLogEventStringW(h,EVENTLOG_INFORMATION_TYPE,msg,count,array,err,\
  549.                               index)
  550.  
  551.  
  552. #ifdef UNICODE
  553. #define RouterLogRegister           RouterLogRegisterW
  554. #define RouterLogDeregister         RouterLogDeregisterW
  555. #define RouterLogEvent              RouterLogEventW
  556. #define RouterLogError              RouterLogErrorW
  557. #define RouterLogWarning            RouterLogWarningW
  558. #define RouterLogInformation        RouterLogInformationW
  559. #define RouterLogEventData          RouterLogEventDataW
  560. #define RouterLogErrorData          RouterLogErrorDataW
  561. #define RouterLogWarningData        RouterLogWarningDataW
  562. #define RouterLogInformationData    RouterLogInformationDataW
  563. #define RouterLogEventString        RouterLogEventStringW
  564. #define RouterLogEventEx            RouterLogEventExW
  565. #define RouterLogEventValistEx      RouterLogEventValistExW
  566. #define RouterLogErrorString        RouterLogErrorStringW
  567. #define RouterLogWarningString      RouterLogWarningStringW
  568. #define RouterLogInformationString  RouterLogInformationStringW
  569. #define RouterGetErrorString        RouterGetErrorStringW
  570. #
  571. #else
  572. #define RouterLogRegister           RouterLogRegisterA
  573. #define RouterLogDeregister         RouterLogDeregisterA
  574. #define RouterLogEvent              RouterLogEventA
  575. #define RouterLogError              RouterLogErrorA
  576. #define RouterLogWarning            RouterLogWarningA
  577. #define RouterLogInformation        RouterLogInformationA
  578. #define RouterLogEventData          RouterLogEventDataA
  579. #define RouterLogErrorData          RouterLogErrorDataA
  580. #define RouterLogWarningData        RouterLogWarningDataA
  581. #define RouterLogInformationData    RouterLogInformationDataA
  582. #define RouterLogEventString        RouterLogEventStringA
  583. #define RouterLogEventEx            RouterLogEventExA
  584. #define RouterLogEventValistEx      RouterLogEventValistExA
  585. #define RouterLogErrorString        RouterLogErrorStringA
  586. #define RouterLogWarningString      RouterLogWarningStringA
  587. #define RouterLogInformationString  RouterLogInformationStringA
  588. #define RouterGetErrorString        RouterGetErrorStringA
  589. #endif
  590.  
  591.  
  592. //////////////////////////////////////////////////////////////////////////////
  593. //                                                                          //
  594. // WORKER THREAD POOL FUNCTIONS                                             //
  595. //                                                                          //
  596. //////////////////////////////////////////////////////////////////////////////
  597.  
  598. //////////////////////////////////////////////////////////////////////////////
  599. //                                                                          //
  600. // definition of worker function passed in QueueWorkItem API                //
  601. //                                                                          //
  602. //////////////////////////////////////////////////////////////////////////////
  603.  
  604. typedef VOID (APIENTRY * WORKERFUNCTION)(PVOID);
  605.  
  606.  
  607. //////////////////////////////////////////////////////////////////////////////
  608. //                                                                          //
  609. //  Function: Queues the supplied work item in the work queue.              //
  610. //                                                                          //
  611. //  functionptr: function to be called must be of WORKERFUNCTION type       //
  612. //  context:     opaque ptr                                                 //
  613. //  serviceinalertablethread: if TRUE gets scheduled in                     //
  614. //               a alertably waiting thread that never dies                 //
  615. //  Returns:  0 (success)                                                   //
  616. //            Win32 error codes for cases like out of memory                //
  617. //                                                                          //
  618. //////////////////////////////////////////////////////////////////////////////
  619.  
  620. DWORD
  621. APIENTRY
  622. QueueWorkItem(
  623.     IN WORKERFUNCTION functionptr,
  624.     IN PVOID context,
  625.     IN BOOL serviceinalertablethread
  626.     );
  627.  
  628.  
  629. //////////////////////////////////////////////////////////////////////////////
  630. //                                                                          //
  631. // Function:        Associates file handle with the completion port (all    //
  632. //                  asynchronous i/o on this handle will be queued to       //
  633. //                    the completion port)                                    //
  634. //                                                                          //
  635. // FileHandle:        File handle to be associated with completion port       //
  636. //                                                                          //
  637. // CompletionProc:  Procedure to be called when io associated with the file //
  638. //                    handle completes. This function will be executed in     //
  639. //                    the context of non-alertable worker thread              //
  640. //                                                                          //
  641. //////////////////////////////////////////////////////////////////////////////
  642.  
  643. DWORD
  644. APIENTRY
  645. SetIoCompletionProc (
  646.     IN HANDLE                            FileHandle,
  647.     IN LPOVERLAPPED_COMPLETION_ROUTINE    CompletionProc
  648.     );
  649.  
  650.  
  651.  
  652. //////////////////////////////////////////////////////////////////////////////
  653. //                                                                          //
  654. // The following defines are included here as a hint on how the worker      //
  655. // thread pool is managed:                                                  //
  656. //                                                                          //
  657. // There are NUM_ALERTABLE_THREADS permanent threads that never quit and    //
  658. // wait alertably on a alertable worker queue.  These threads should solely //
  659. // be used for work items that intiate asyncronous operation (file io,      //
  660. // waitable timer) that ABSOLUTELY require APCs to complete (preferable     //
  661. // method for IO is the usage of completio port API)                        //
  662. //                                                                          //
  663. // There is a pool of the threads that wait on completion port              //
  664. // that used both for processing of IO and non-IO related work items        //
  665. //                                                                          //
  666. // The minimum number of threads is Number of processors                    //
  667. // The maximum number of threads is MAX_WORKER_THREADS                      //
  668. //                                                                          //
  669. // A new thread is created if worker queue has not been served for more     //
  670. // that WORK_QUEUE_TIMEOUT                                                  //
  671. // The existing thread will be shut down if it is not used for more than    //
  672. // THREAD_IDLE_TIMEOUT                                                      //
  673. //                                                                          //
  674. // Note that worker threads age guaranteed to be alive for at least         //
  675. // THREAD_IDLE_TIMEOUT after the last work item is executed.  This timeout  //
  676. // is chosen such that bulk of IO request could be completed before it      //
  677. // expires.  If it is not enough for your case, use alertable thread with   //
  678. // APC, or create your own thread.                                          //
  679. //                                                                          //
  680. // Note: changing these flags will not change anything.                     //
  681. //                                                                          //
  682. //////////////////////////////////////////////////////////////////////////////
  683.  
  684.  
  685. //////////////////////////////////////////////////////////////////////////////
  686. //                                                                          //
  687. // Number of alertable threads                                              //
  688. //                                                                          //
  689. //////////////////////////////////////////////////////////////////////////////
  690.  
  691. #define NUM_ALERTABLE_THREADS        2
  692.  
  693. //////////////////////////////////////////////////////////////////////////////
  694. //                                                                          //
  695. // Max number of threads at any time                                        //
  696. //                                                                          //
  697. //////////////////////////////////////////////////////////////////////////////
  698.  
  699. #define MAX_WORKER_THREADS          10
  700.  
  701. //////////////////////////////////////////////////////////////////////////////
  702. //                                                                          //
  703. // Time that the worker queue is not served before starting new thread      //
  704. //                                                                          //
  705. //////////////////////////////////////////////////////////////////////////////
  706.  
  707. #define WORK_QUEUE_TIMEOUT            1 //sec
  708.  
  709. //////////////////////////////////////////////////////////////////////////////
  710. //                                                                          //
  711. // Time that thread has to be idle before exiting                           //
  712. //                                                                          //
  713. //////////////////////////////////////////////////////////////////////////////
  714.  
  715. #define THREAD_IDLE_TIMEOUT            10 //sec
  716.  
  717.  
  718. //////////////////////////////////////////////////////////////////////////////
  719. //                                                                          //
  720. // ROUTER ASSERT DECLARATION                                                //
  721. //                                                                          //
  722. //////////////////////////////////////////////////////////////////////////////
  723.  
  724. VOID
  725. RouterAssert(
  726.     IN PSTR pszFailedAssertion,
  727.     IN PSTR pszFileName,
  728.     IN DWORD dwLineNumber,
  729.     IN PSTR pszMessage OPTIONAL
  730.     );
  731.  
  732.  
  733. #if DBG
  734. #define RTASSERT(exp) \
  735.         if (!(exp)) \
  736.             RouterAssert(#exp, __FILE__, __LINE__, NULL)
  737. #define RTASSERTMSG(msg, exp) \
  738.         if (!(exp)) \
  739.             RouterAssert(#exp, __FILE__, __LINE__, msg)
  740. #else
  741. #define RTASSERT(exp)
  742. #define RTASSERTMSG(msg, exp)
  743. #endif
  744.  
  745. //////////////////////////////////////////////////////////////////////////////
  746. //                                                                          //
  747. // REGISTRY CONFIGURATION FUNCTIONS                                         //
  748. //                                                                          //
  749. // The following definitions are used to read configuration information     //
  750. // about installed protocols.                                               //
  751. //                                                                          //
  752. // Call 'MprSetupProtocolEnum' to enumerate the routing-protocols           //
  753. // for transport 'dwTransportId'. This fills an array with entries          //
  754. // of type 'MPR_PROTOCOL_0'.                                                //
  755. //                                                                          //
  756. // The array loaded can be destroyed by calling 'MprSetupProtocolFree'.     //
  757. //                                                                          //
  758. //////////////////////////////////////////////////////////////////////////////
  759.  
  760. #define MAX_PROTOCOL_NAME_LEN                           40
  761. #define MAX_PROTOCOL_DLL_LEN                            48
  762.  
  763. typedef struct _MPR_PROTOCOL_0 {
  764.  
  765.     DWORD       dwProtocolId;                           // e.g. IP_RIP
  766.     WCHAR       wszProtocol[MAX_PROTOCOL_NAME_LEN+1];   // e.g. "IPRIP"
  767.     WCHAR       wszDLLName[MAX_PROTOCOL_DLL_LEN+1];     // e.g. "iprip2.dll"
  768.  
  769. } MPR_PROTOCOL_0;
  770.  
  771.  
  772. DWORD APIENTRY
  773. MprSetupProtocolEnum(
  774.     IN      DWORD                   dwTransportId,
  775.     OUT     LPBYTE*                 lplpBuffer,         // MPR_PROTOCOL_0
  776.     OUT     LPDWORD                 lpdwEntriesRead
  777.     );
  778.  
  779.  
  780. DWORD APIENTRY
  781. MprSetupProtocolFree(
  782.     IN      LPVOID                  lpBuffer
  783.     );
  784.  
  785.  
  786. //////////////////////////////////////////////////////////////////////////////
  787. // Extensions to Rtutils to improve worker thread utilization.                //
  788. //                                                                             //
  789. //////////////////////////////////////////////////////////////////////////////
  790.  
  791. #define ROUTING_RESERVED
  792. #define OPT1_1
  793. #define OPT1_2
  794. #define OPT2_1
  795. #define OPT2_2
  796. #define OPT3_1
  797. #define OPT3_2
  798.  
  799.  
  800. //
  801. // When everyone is migrated to using Winsock2
  802. //
  803.  
  804. #if 0
  805.  
  806.  
  807. //==========================================================================================================//
  808. //==========================================================================================================//
  809.  
  810. // ASYNC_SOCKET_DATA structure is used to pass / receive back data from an        //
  811. // asynchronous wait recv from call                                                //
  812.  
  813. typedef struct _ASYNC_SOCKET_DATA {
  814.             OVERLAPPED        Overlapped;            // reserved. not to be used
  815.     IN        WSABUF            WsaBuf;                // WsaBuf.buf to be initialized to point to buffer
  816.                                                 // WsaBuf.len set to the length of the buffer
  817.     OUT        SOCKADDR_IN        SrcAddress;            // AsyncWsaRecvFrom fills this with the source address of the packet
  818.     OUT        DWORD            NumBytesReceived;    // AsyncWsaRecvFrom fills this with the number of bytes returned in the packet
  819.     IN OUT    DWORD            Flags;                // Used to set flags for WSARecvFrom, and returns the flags set by WSARecvFrom
  820.     OUT        DWORD            Status;                // status returned by IO Completion Port
  821.  
  822.     IN        WORKERFUNCTION    pFunction;            // Function to be executed on receiving packet
  823.     IN        PVOID            pContext;            // context for the above function
  824. } ASYNC_SOCKET_DATA, *PASYNC_SOCKET_DATA;
  825.  
  826.  
  827.  
  828. // AsyncSocketInit() binds the socket to the IOCompletionPort. This should be called//
  829. // after the socket is created and before AsyncWsaRecvFrom() call is made            //
  830. DWORD
  831. APIENTRY
  832. AsyncSocketInit (
  833.     SOCKET    sock
  834.     );
  835.  
  836.  
  837. // This should be called only after the appropriate fields in SockData are initialized    //
  838. // This sets up an asynchronous WSARecvFrom(), and on its return dispatches the         //
  839. // function to a worker thread. It should be remembered that the function will run in     //
  840. // a worker thread which might later on be deleted. So SetWaitableTimer() and             //
  841. // asynchronous receive calls should be avoided unless you are sure that it would not be//
  842. // a problem. It is adviced that if you want the function to run in an alertable thread,//
  843. // then have the callback function queue a work item to alertable thread. Queue work     //
  844. // items to alertable worker threads for SetWaitableTimer() and async receives.         //
  845. // One must not make many AsyncWSArecvFrom() calls, as the buffer are non-paged            //
  846. DWORD
  847. APIENTRY
  848. AsyncWSARecvFrom (
  849.     SOCKET        sock,
  850.     PASYNC_SOCKET_DATA    pSockData
  851.     );
  852.  
  853. #endif // all winsock2 functions
  854.  
  855. //==========================================================================================================//
  856. //==========================================================================================================//
  857.  
  858.  
  859. // forward declarations
  860. struct _WAIT_THREAD_ENTRY;
  861. struct _WT_EVENT_ENTRY;
  862.  
  863.  
  864. typedef struct _WT_TIMER_ENTRY {
  865.     LONGLONG            te_Timeout;
  866.  
  867.     WORKERFUNCTION        te_Function;
  868.     PVOID                te_Context;
  869.     DWORD                te_ContextSz;
  870.     BOOL                te_RunInServer;
  871.     
  872.     DWORD                te_Status;
  873.  
  874.     #define         TIMER_INACTIVE  3
  875.     #define         TIMER_ACTIVE    4
  876.  
  877.     DWORD                te_ServerId;
  878.     struct _WAIT_THREAD_ENTRY *teP_wte;    
  879.     LIST_ENTRY            te_ServerLinks;
  880.     
  881.     LIST_ENTRY            te_Links;
  882.  
  883.     BOOL                te_Flag;        //todo: not used
  884.     DWORD                te_TimerId;
  885. } WT_TIMER_ENTRY, *PWT_TIMER_ENTRY;
  886.  
  887.     
  888. typedef struct _WT_WORK_ITEM {
  889.     WORKERFUNCTION      wi_Function;                // function to call
  890.     PVOID               wi_Context;                    // context passed into function call
  891.     DWORD                wi_ContextSz;                // size of context, used for allocating
  892.     BOOL                wi_RunInServer;                // run in wait server thread or get queued to some worker thread
  893.  
  894.     struct _WT_EVENT_ENTRY    *wiP_ee;
  895.     LIST_ENTRY        wi_ServerLinks;
  896.     LIST_ENTRY      wi_Links;                      //todo not req    // link to next and prev element
  897. } WT_WORK_ITEM, *PWT_WORK_ITEM;
  898.  
  899. #define WT_EVENT_BINDING     WT_WORK_ITEM
  900. #define PWT_EVENT_BINDING     PWT_WORK_ITEM
  901.  
  902.  
  903. //
  904. // WT_EVENT_ENTRY
  905. //
  906. typedef struct _WT_EVENT_ENTRY {
  907.     HANDLE            ee_Event;
  908.     BOOL            ee_bManualReset;                            // is the event manually reset
  909.     BOOL            ee_bInitialState;                        // is the initial state of the event active
  910.     BOOL            ee_bDeleteEvent;                        // was the event created as part of createWaitEvent
  911.     
  912.     DWORD            ee_Status;                                // current status of the event entry
  913.     BOOL            ee_bHighPriority;
  914.     
  915.     LIST_ENTRY        eeL_wi;
  916.     
  917.     BOOL            ee_bSignalSingle;                        // signal single function or multiple functions                        // how many functions to activate when event signalled (default:1)
  918.     BOOL            ee_bOwnerSelf;                            // the owner if the client which create this event
  919.  
  920.     INT                ee_ArrayIndex;                            // index in the events array if active
  921.     
  922.     DWORD            ee_ServerId;                            // Id of server: used while deleting
  923.     struct _WAIT_THREAD_ENTRY *eeP_wte;                        // pointer to wait thread entry
  924.     LIST_ENTRY        ee_ServerLinks;                            // used by wait server thread
  925.     LIST_ENTRY        ee_Links;                                // used by client
  926.  
  927.     DWORD            ee_RefCount;
  928.     BOOL            ee_bFlag;        //todo: notused                                // reserved for use during deletion
  929.     DWORD            ee_EventId;        //todo: remove it, being used only for testing/debugging    
  930.  
  931. } WT_EVENT_ENTRY, *PWT_EVENT_ENTRY;
  932.  
  933.  
  934.  
  935.  
  936. // PROTOTYPES OF FUNCTIONS USED IN THIS FILE ONLY
  937. //
  938.  
  939.  
  940. // used by client to create a wait event
  941. // context size should be 0 if you are passing a dword instead of a pointer
  942. // if pEvent field is set, then lpName and security attributes are ignored
  943. // if pFunction is NULL, then pContext, dwContextSz, and bRunInServerContext are ignored
  944. PWT_EVENT_ENTRY
  945. APIENTRY
  946. CreateWaitEvent (
  947.     //IN    PWT_EVENT_ENTRY    pEventEntry,                    // handle to event entry if initialized by others
  948.     IN    HANDLE            pEvent                 OPT1_1,            // handle to event if already created
  949.  
  950.     IN    LPSECURITY_ATTRIBUTES lpEventAttributes OPT1_2,     // pointer to security attributes
  951.     IN    BOOL            bManualReset,
  952.     IN    BOOL            bInitialState,
  953.     IN    LPCTSTR         lpName                 OPT1_2,         // pointer to event-object name
  954.  
  955.     IN  BOOL            bHighPriority,                        // create high priority event
  956.  
  957.     IN    WORKERFUNCTION     pFunction             OPT2_1,            // if null, means will be set by other clients
  958.     IN    PVOID             pContext              OPT2_1,            // can be null
  959.     IN  DWORD            dwContextSz            OPT2_1,            // size of context: used for allocating context to functions
  960.     IN     BOOL            bRunInServerContext    OPT2_1            // run in server thread or get dispatched to worker thread
  961.     );
  962.  
  963.  
  964.  
  965. //dwContextSz should be 0 if a dword is being passed. >0 only if pointer to block of that size is being passed.
  966. PWT_EVENT_BINDING
  967. APIENTRY
  968. CreateWaitEventBinding (
  969.     IN    PWT_EVENT_ENTRY    pee,
  970.     IN     WORKERFUNCTION     pFunction,
  971.     IN     PVOID            pContext,
  972.     IN    DWORD            dwContextSz,
  973.     IN    BOOL            bRunInServerContext
  974.     );
  975.  
  976.     
  977. PWT_TIMER_ENTRY
  978. APIENTRY
  979. CreateWaitTimer (
  980.     IN    WORKERFUNCTION    pFunction,
  981.     IN    PVOID            pContext,
  982.     IN    DWORD            dwContextSz,
  983.     IN    BOOL            bRunInServerContext
  984.     );
  985.  
  986. DWORD
  987. APIENTRY
  988. DeRegisterWaitEventBindingSelf (
  989.     IN    PWT_EVENT_BINDING    pwiWorkItem
  990.     );
  991.  
  992.     
  993. DWORD
  994. APIENTRY
  995. DeRegisterWaitEventBinding (
  996.     IN    PWT_EVENT_BINDING    pwiWorkItem
  997.     );
  998.  
  999.  
  1000. //all the events and timers should be registered with one waitThread server
  1001. //todo: change the above requirement
  1002. DWORD
  1003. APIENTRY
  1004. DeRegisterWaitEventsTimers (
  1005.     PLIST_ENTRY    pLEvents,    // list of events linked by ee_Links field
  1006.     PLIST_ENTRY pLTimers    // list of timers linked by te_Links field:
  1007.     //these lists can be a single list entry, or a multiple entry list with a list header entry.
  1008.     );
  1009.  
  1010. // this should be used only when called within a server thread
  1011. DWORD
  1012. APIENTRY
  1013. DeRegisterWaitEventsTimersSelf (
  1014.     IN    PLIST_ENTRY pLEvents,
  1015.     IN    PLIST_ENTRY    pLTimers
  1016.     );
  1017.  
  1018.     
  1019. DWORD
  1020. APIENTRY
  1021. RegisterWaitEventBinding (
  1022.     IN    PWT_EVENT_BINDING    pwiWorkItem
  1023.     );
  1024.     
  1025. // Register the client with the wait thread
  1026. DWORD
  1027. APIENTRY
  1028. RegisterWaitEventsTimers (
  1029.     IN    PLIST_ENTRY pLEventsToAdd,
  1030.     IN    PLIST_ENTRY    pLTimersToAdd
  1031.     );
  1032.  
  1033. DWORD
  1034. APIENTRY
  1035. UpdateWaitTimer (
  1036.     IN    PWT_TIMER_ENTRY    pte,
  1037.     IN    LONGLONG         *time
  1038.     );
  1039.  
  1040. VOID
  1041. APIENTRY
  1042. WTFree (
  1043.     PVOID ptr
  1044.     );
  1045.  
  1046.  
  1047. //used to free wait-event. Should be deallocated using DeRegisterWaitEventsTimers
  1048. //This function is to be used only when the events have not been registered
  1049. VOID
  1050. APIENTRY
  1051. WTFreeEvent (
  1052.     IN    PWT_EVENT_ENTRY    peeEvent
  1053.     );
  1054.  
  1055.  
  1056. //used to free wait-timer. Should be deallocated using DeRegisterWaitEventsTimers
  1057. //This function is to be used only when the timers have not been registered
  1058. VOID
  1059. APIENTRY
  1060. WTFreeTimer (
  1061.     IN PWT_TIMER_ENTRY pteTimer
  1062.     );
  1063.  
  1064.     
  1065. VOID
  1066. APIENTRY
  1067. DebugPrintWaitWorkerThreads (
  1068.     DWORD    dwDebugLevel
  1069.     );
  1070.  
  1071. #define DEBUGPRINT_FILTER_NONCLIENT_EVENTS    0x2
  1072. #define DEBUGPRINT_FILTER_EVENTS            0x4
  1073. #define DEBUGPRINT_FILTER_TIMERS            0x8
  1074.  
  1075.  
  1076. //
  1077. //ERROR VALUES
  1078. //
  1079. #define ERROR_WAIT_THREAD_UNAVAILABLE     1
  1080.  
  1081. #define ERROR_WT_EVENT_ALREADY_DELETED     2
  1082.  
  1083.  
  1084.  
  1085.  
  1086. #define TIMER_HIGH(time) \
  1087.     (((LARGE_INTEGER*)&time)->HighPart)
  1088.  
  1089. #define TIMER_LOW(time) \
  1090.     (((LARGE_INTEGER*)&time)->LowPart)
  1091.  
  1092.  
  1093. #ifdef __cplusplus
  1094. }
  1095. #endif
  1096.  
  1097. #pragma option pop /*P_O_Pop*/
  1098. #endif // ___ROUTING_RTUTILS_H__
  1099.  
  1100.  
  1101.