home *** CD-ROM | disk | FTP | other *** search
/ Tricks of the Windows Gam…ming Gurus (2nd Edition) / Disc2.iso / vc98 / include / proxygen.h < prev    next >
C/C++ Source or Header  |  1998-04-25  |  11KB  |  248 lines
  1. // --proxygen.h-----------------------------------------------------------------
  2. //
  3. //  Copyright (c) Microsoft Corp. 1986-1996. All Rights Reserved.
  4. //
  5. //    Specification for the required implementation of a proxy generation DLL
  6. //    for an installed address-type.
  7. //
  8. //    Functions in this DLL will be called in the following order:
  9. //
  10. //         RcInitProxies
  11. //              |
  12. //              |<----------------------------------+
  13. //              |                                   |
  14. //                +-----------------------+           |
  15. //                |                       |           |
  16. //        RcGenerateProxy        RcValidateProxy         |
  17. //                |                       |           |
  18. //                |                       |           |
  19. //                |                       |           |
  20. //            FreeProxy                   |           |
  21. //                |                       |           |
  22. //                +-----------------------+-----------+
  23. //                                        |
  24. //                                        |
  25. //                                        |
  26. //                                      Close
  27. //
  28. //------------------------------------------------------------------------------
  29.  
  30. #if !defined(_PROXYGEN_H)
  31. #define _PROXYGEN_H
  32.  
  33. #include <windows.h>
  34. #include <retcode.h>    // RC
  35. #include <proxyinf.h>    // RECIPIENTINFO structures
  36.  
  37.  
  38. //$--RcInitProxies--------------------------------------------------------------
  39. //    Requests that the proxy generation DLL do any initializaton required before
  40. //    calling the GenerateProxy function with individual recipient objects.
  41. //  This function is not permitted to generate any UI as proxy generation
  42. //    should all be done silently without user intervention. If the implementor 
  43. //    desires, this function may do nothing other than make the site specific 
  44. //    information accessible to the GenerateProxy and ValidateProxy functions. 
  45.  
  46. //    Init is primarily included for efficiency purposes so that the implementor
  47. //    may do any common processing in this function as it is likely that a large 
  48. //    number of proxies will be generated at one time during an address-type 
  49. //    install or update.
  50. //
  51. //    Input Parameters
  52. //        pszSiteProxy    The site proxy for this address-type. Generally used
  53. //                        as part of the recipient proxy. May be NULL (this is 
  54. //                        address-type dependent) if not used or not set yet.
  55. //        pszServer        The name of the server that the proxy DLL is being
  56. //                        used on.
  57. //    
  58. //    Note: these 2 pointers are guaranteed to be stay valid until after Close is
  59. //    called so the DLL need only keep a copy of these pointers rather than copy 
  60. //    the data.  Or, the DLL can copy the data with the same result as the
  61. //    information these structures point to will not change until after Close is 
  62. //    called.
  63. //    
  64. //    Output Parameters
  65. //        hProxySession    Handle to a proxy session.  Any storage associated
  66. //                        with this handle which is allocated by Init must be
  67. //                        freed by Close
  68. //
  69. //    Returns:
  70. //        RC_SUCCESS        Success
  71. //        RC_IMPLEMENTATION    Proxies are not implemented for this address type. 
  72. //                        No proxies will be stored. The Generate and Close entry
  73. //                        points to this DLL are undefined. User will not be
  74. //                        notified as this is a supported configuration.
  75. //        RC_MEMORY        Memory allocation failure
  76. //        RC_ERROR        General failure.  User will be notified of inability
  77. //                        to generate proxies for this address type.
  78. //------------------------------------------------------------------------------
  79. RC RcInitProxies(IN LPWSTR pszSiteProxy,
  80.                  IN LPWSTR pszServer,
  81.                  OUT HANDLE *phProxySession);
  82.  
  83.  
  84. //$--RcGenerateProxy------------------------------------------------------------
  85. //    Returns a single proxy address as a unicode string. This function is not 
  86. //    permitted to generate any UI as proxy generation should all be done silently
  87. //    without user intervention.
  88. //
  89. //    Input Parameters:
  90. //        hProxySession    Handle to the proxy session previously returned by
  91. //                        Init.
  92. //        pRecipientInfo    The recipient specific details for this recipient.
  93. //                        Used along with the Site Proxy
  94. //                        information and nRetries by Generate to algorithmically
  95. //                        generate a site-unique recipient proxy in the 
  96. //                        addressing format of the foreign address-type.
  97. //        nRetries        The number of times this function has previously been
  98. //                        called with this value for pRecipientInfo. When ProxyGen
  99. //                        is called with the same pRecipientInfo but different
  100. //                        nRetries values it should endeavour to return a different
  101. //                        proxy address.  However, the maximum value which an
  102. //                        an implementation supports for nRetries is 
  103. //                        implementation specific (may be 0).
  104. //        
  105. //    Output Parameters:
  106. //        ppszProxyAddr    The foreign format (proxy) address which is generated.
  107. //                        This must be a unicode string. This is allocated by the 
  108. //                        Generate function but must be freed by the calling code
  109. //                        by calling FreeProxy.
  110. //                        The proxy should be of the form "TYPE:VALUE"
  111. //
  112. //    Returns:
  113. //        RC_SUCCESS        Success
  114. //        RC_MEMORY        Memory allocation failure
  115. //        RC_ERROR        Cannot generate proxy address, Possibile problems are:
  116. //                        - nRetries is too high, cannot generate any more unique
  117. //                          proxies.
  118. //                        - site specific info incomplete
  119. //                        - per recipient info incomplete
  120. //------------------------------------------------------------------------------
  121. RC RcGenerateProxy(IN HANDLE             hProxySession,
  122.                    IN PRECIPIENTINFO    pRecipientInfo,
  123.                    IN int                nRetries,
  124.                    OUT LPWSTR *            ppszProxyAddr);
  125.  
  126.  
  127. //$--RcUpdateProxy------------------------------------------------------------
  128. //    Compares the site proxy part of a proxy to an "old" site proxy. If
  129. //    they match then replace the "old" site proxy in the proxy with the "new
  130. //    site proxy.  All input parameters have the address type as a prefix.
  131. //
  132. //    Input Parameters:
  133. //        hProxySession        Handle to the proxy session previously returned by
  134. //                            Init.
  135. //        pRecipientInfo        The recipient specific details for this recipient.
  136. //        pwstrOldSiteProxy    "Old" site proxy.
  137. //        pwstrNewSiteProxy    "New" site proxy.
  138. //        pwstrProxy            The proxy to be modified.
  139. //        pUnused                unused
  140. //        
  141. //    Output Parameters:
  142. //        pwstrProxy            The modified proxy.
  143. //
  144. //    Returns:
  145. //        RC_SUCCESS        Success
  146. //        RC_MEMORY        Memory allocation failure
  147. //        RC_ERROR        Cannot generate new proxy address
  148. //------------------------------------------------------------------------------
  149. RC RcUpdateProxy(IN HANDLE hProxySession,
  150.                  IN PRECIPIENTINFO pRecipientInfo,
  151.                  IN LPWSTR pwstrOldSiteProxy,
  152.                  IN LPWSTR pwstrNewSiteProxy,
  153.                  IN OUT LPWSTR pwstrProxy,
  154.                  IN VOID * pUnused);
  155.  
  156.  
  157. //$--RcValidateProxy------------------------------------------------------------
  158. //    Given a unicode string it validates that this string represents a valid
  159. //    address of the appropriate foreign type. This is called to verify manually
  160. //    generated proxies are legal.
  161. //
  162. //    Input Parameters:
  163. //        hProxySession    Handle to the proxy session previously returned by
  164. //                        Init.
  165. //        pszProxyAddr    The foreign format (proxy) address to be validated
  166. //                      including the prefixed address type.
  167. //                        If the proxy dll can make an invalid proxy (because
  168. //                        of invalid characters, etc.) into a valid proxy then
  169. //                        return the corrected proxy in this location and
  170. //                        return TRUE in *pisValid.  The caller will have made
  171. //                        allowances for a possibly longer returned proxy string.
  172. //
  173. //    Output Parameters:
  174. //        pisValid        TRUE if valid, FALSE if not.  TRUE if return code
  175. //                        is RC_IMPLEMENTATION. Undefined if return code is
  176. //                        RC_ERROR or RC_MEMORY.
  177. //
  178. //    Returns:
  179. //        RC_SUCCESS        Success
  180. //        RC_IMPLEMENTATION    Proxy validation not implemented.  The caller 
  181. //                        should assume the entered proxy is valid and let the
  182. //                        gateway or foreign system advise otherwise if neccesary.
  183. //        RC_MEMORY        Memory allocation failure
  184. //        RC_ERROR        Implementation specific error.
  185. //------------------------------------------------------------------------------
  186. RC RcValidateProxy(IN HANDLE     hProxySession,
  187.                      IN LPWSTR     pszProxyAddr,
  188.                    OUT BOOL *     pisValid);
  189.  
  190.  
  191. //$--RcValidateSiteProxy------------------------------------------------------------
  192. //    Given a unicode string it validates that this string represents a valid
  193. //    site address of the appropriate foreign type. This is called to verify manually
  194. //    generated site proxies are legal.
  195. //
  196. //    Input Parameters:
  197. //        hProxySession    Handle to the proxy session previously returned by
  198. //                        Init.
  199. //        pszSiteProxy    The foreign format site (proxy) address to be validated
  200. //                      including the prefixed address type.
  201. //                        If the proxy dll can make an invalid proxy (because
  202. //                        of invalid characters, etc.) into a valid proxy then
  203. //                        return the corrected proxy in this location and
  204. //                        return TRUE in *pisValid.  The caller will have made
  205. //                        allowances for a possibly longer returned proxy string.
  206. //
  207. //    Output Parameters:
  208. //        pisValid        TRUE if valid, FALSE if not.  TRUE if return code
  209. //                        is RC_IMPLEMENTATION. Undefined if return code is
  210. //                        RC_ERROR or RC_MEMORY.
  211. //
  212. //    Returns:
  213. //        RC_SUCCESS        Success
  214. //        RC_IMPLEMENTATION    Proxy validation not implemented.  The caller 
  215. //                        should assume the entered site proxy is valid and let the
  216. //                        gateway or foreign system advise otherwise if neccesary.
  217. //        RC_MEMORY        Memory allocation failure
  218. //        RC_ERROR        Implementation specific error.
  219. //------------------------------------------------------------------------------
  220. RC RcValidateSiteProxy(IN HANDLE     hProxySession,
  221.                          IN LPWSTR     pszProxyAddr,
  222.                        OUT BOOL *     pisValid);
  223.  
  224.  
  225. //$--FreeProxy------------------------------------------------------------------
  226. //    Frees the memory previously allocated by 
  227. //    GenerateProxy for a proxy address string.
  228. //
  229. //     Input Parameter:
  230. //        pszProxy    The proxy string to be freed
  231. //------------------------------------------------------------------------------
  232. VOID FreeProxy(IN LPWSTR pszProxy);
  233.  
  234.  
  235. //$--CloseProxies---------------------------------------------------------------
  236. //    Closes a proxy generation session and frees any associated data.  The DLL
  237. //    can now be unloaded. This function is not permitted to generate any UI as 
  238. //    proxy generation should all be done silently without user intervention.
  239. //
  240. //    Input Parameters
  241. //        hProxySession    Handle to the proxy session previously returned by
  242. //                        Init.
  243. //    Returns:
  244. //        Nothing. 
  245. void CloseProxies(IN HANDLE hProxySession);
  246.  
  247. #endif
  248.