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