pckunpck.h
上传用户:zhongxx05
上传日期:2007-06-06
资源大小:33641k
文件大小:13k
源码类别:

Symbian

开发平台:

C/C++

  1. /* ***** BEGIN LICENSE BLOCK ***** 
  2.  * Version: RCSL 1.0/RPSL 1.0 
  3.  *  
  4.  * Portions Copyright (c) 1995-2002 RealNetworks, Inc. All Rights Reserved. 
  5.  *      
  6.  * The contents of this file, and the files included with this file, are 
  7.  * subject to the current version of the RealNetworks Public Source License 
  8.  * Version 1.0 (the "RPSL") available at 
  9.  * http://www.helixcommunity.org/content/rpsl unless you have licensed 
  10.  * the file under the RealNetworks Community Source License Version 1.0 
  11.  * (the "RCSL") available at http://www.helixcommunity.org/content/rcsl, 
  12.  * in which case the RCSL will apply. You may also obtain the license terms 
  13.  * directly from RealNetworks.  You may not use this file except in 
  14.  * compliance with the RPSL or, if you have a valid RCSL with RealNetworks 
  15.  * applicable to this file, the RCSL.  Please see the applicable RPSL or 
  16.  * RCSL for the rights, obligations and limitations governing use of the 
  17.  * contents of the file.  
  18.  *  
  19.  * This file is part of the Helix DNA Technology. RealNetworks is the 
  20.  * developer of the Original Code and owns the copyrights in the portions 
  21.  * it created. 
  22.  *  
  23.  * This file, and the files included with this file, is distributed and made 
  24.  * available on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER 
  25.  * EXPRESS OR IMPLIED, AND REALNETWORKS HEREBY DISCLAIMS ALL SUCH WARRANTIES, 
  26.  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, FITNESS 
  27.  * FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. 
  28.  * 
  29.  * Technology Compatibility Kit Test Suite(s) Location: 
  30.  *    http://www.helixcommunity.org/content/tck 
  31.  * 
  32.  * Contributor(s): 
  33.  *  
  34.  * ***** END LICENSE BLOCK ***** */ 
  35. #ifndef PCKUNPCK_H
  36. #define PCKUNPCK_H
  37. /* Unfortunate but necessary includes */
  38. #include "hxtypes.h"
  39. #include "hxwintyp.h"
  40. #include "hxcom.h"
  41. #include "hxstring.h"
  42. #include <stdarg.h> /* for va_arg */
  43. /*
  44.  * forward decls
  45.  */
  46. typedef _INTERFACE IHXBuffer IHXBuffer;
  47. typedef _INTERFACE IHXValues IHXValues;
  48. /*
  49.  * packing/unpacking functions
  50.  * NOTE: this are Nick Hart's original methods imported
  51.  * directly from chinembed/unix/bufferutils.cpp
  52.  */
  53. HX_RESULT PackBuffer(REF(IHXBuffer*) pBuffer,
  54.      const char*      pFormat,
  55.      ...);
  56. HX_RESULT PackBufferV(REF(IHXBuffer*) pBuffer,
  57.       const char*      pFormat,
  58.       va_list vargs);
  59. int UnpackBuffer(REF(const char*) pBuffer,
  60.  const char*      pFormat,
  61.  ...);
  62. int UnpackBufferV(REF(const char*) pBuffer,
  63.   const char*      pFormat,
  64.   va_list          vargs);
  65. HX_RESULT PackValues(REF(CHXString) sBuffer,
  66.                      IHXValues*    pValues);
  67. HX_RESULT UnpackValues(REF(const char*) pBuffer,
  68.                        REF(IHXValues*) pValues,
  69.                        BOOL             bCreateValues = TRUE);
  70. HX_RESULT Bufferize(REF(IHXBuffer*) pBuffer,
  71.                     void*            pData,
  72.                     UINT32           uSize);
  73. #ifdef _DEBUG
  74. void TestBufferPacking();
  75. #endif
  76. /*
  77.  * NOTE: these are methods Eric Hyche added specifically
  78.  * for packing and unpacking IHXValues. They also add two
  79.  * additional options:
  80.  * a) binary packing (as opposed to Nick's text string packing); and 
  81.  * b) if you pass in an IUnknown context, then all your IHXBuffer's
  82.  *    and IHXValues will be created by the common class factory.
  83.  *    If you leave out the IUnknown, then IHXBuffer's will be 
  84.  *    directly created from CHXBuffer's and IHXValues will be created
  85.  *    directly from CHXHeader's.
  86.  */
  87. // GetBinaryPackedSize() returns the number of
  88. // bytes required to binary pack the IHXValues
  89. // that you pass in
  90. UINT32 GetBinaryPackedSize(IHXValues* pValues);
  91. // PackValuesBinary() packs the IHXValues you provide
  92. // in the IHXBuffer you provide in binary form. It assumes
  93. // that pBuffer is at least as big as the the
  94. // number of bytes returned by GetBinaryPackedSize(). If
  95. // pBuffer is not big enough, it will return HXR_FAIL.
  96. HX_RESULT PackValuesBinary(IHXBuffer* pBuffer,
  97.                            IHXValues* pValues);
  98. // CreateBuffer() creates an IHXBuffer. If you pass in
  99. // an IUnknown context, it will QI that context for
  100. // IHXCommonClassFactory and use IHXCommonClassFactory::CreateInstance()
  101. // to create the IHXBuffer. If you don't pass in an IUnknown context, then
  102. // it will do a "new CHXBuffer()" to create the IHXBuffer.
  103. HX_RESULT CreateBuffer(REF(IHXBuffer*) rpBuffer,
  104.                        IUnknown*        pContext = NULL);
  105. // CreateValues() creates an IHXValues. If you pass in
  106. // an IUnknown context, it will QI that context for
  107. // IHXCommonClassFactory and use IHXCommonClassFactory::CreateInstance()
  108. // to create the IHXValues. If you don't pass in an IUnknown context, then
  109. // it will do a "new CHXHeader()" to create the IHXValues.
  110. HX_RESULT CreateValues(REF(IHXValues*) rpValues,
  111.                        IUnknown*        pContext = NULL);
  112. // CreateStringBuffer() creates an IHXBuffer with the
  113. // string pszStr in it. The length of rpBuffer will
  114. // be strlen(pszStr) + 1. CreateStringBuffer() calls
  115. // CreateBuffer() to create the IHXBuffer.
  116. HX_RESULT CreateStringBuffer(REF(IHXBuffer*) rpBuffer,
  117.                              const char*      pszStr,
  118.                              IUnknown*        pContext = NULL);
  119. // SetCStringProperty() sets a CString property in
  120. // pValues where pszName is the property name
  121. // and the property value is pszValue. SetCStringProperty()
  122. // calls CreateStringBuffer() to create the IHXBuffer
  123. // which holds the property value string.
  124. HX_RESULT SetCStringProperty(IHXValues* pValues,
  125.                              const char* pszName,
  126.                              const char* pszValue,
  127.                              IUnknown*   pContext = NULL,
  128.                              BOOL        bSetAsBufferProp = FALSE);
  129. // SetCStringPropertyWithNullTerm() sets a CString property in
  130. // pValues where pszName is the property name
  131. // and the property value is in pBuf and ulLen. It's assumed
  132. // that pBuf and ulLen hold a string, but the string is
  133. // not NULL-terminated. Therefore, SetCStringPropertyWithNT()
  134. // will NULL-terminate the buffer in pBuf (making the
  135. // IHXBuffer it creates ulLen + 1).
  136. HX_RESULT SetCStringPropertyWithNullTerm(IHXValues*  pValues,
  137.                                          const char* pszName,
  138.                                          BYTE*       pBuf,
  139.                                          UINT32      ulLen,
  140.                                          IUnknown*   pContext = NULL,
  141.                                          BOOL        bSetAsBufferProp = FALSE);
  142. // CreateNullTermBuffer takes pBuf and ulLen, creates a
  143. // buffer of length ulLen+1, copies ulLen bytes
  144. // of pBuf into this new buffer, and then NULL-terminates
  145. // it. It then returns this buffer as an out parameter.
  146. HX_RESULT CreateNullTermBuffer(BYTE*  pBuf,
  147.                                UINT32 ulLen,
  148.                                char** ppNTBuf);
  149. // SetBufferPropety() sets a Buffer property in pValues.
  150. // First calls CreateBuffer() (see above) to create the
  151. // IHXBuffer, then calls IHXBuffer::Set() with the
  152. // provided pBuf and ulLen, and then sets this
  153. // property into the IHXValues.
  154. HX_RESULT SetBufferProperty(IHXValues* pValues,
  155.                             const char* pszName,
  156.                             BYTE*       pBuf,
  157.                             UINT32      ulLen,
  158.                             IUnknown*   pContext = NULL);
  159. // UnpackPropertyULONG32() unpacks a ULONG32 property
  160. // from binary form, and then sets that ULONG32 property
  161. // into the provided IHXValues. Initially rpBuf should
  162. // be set to the beginning of the packed ULONG32 and 
  163. // pLimit should be set to the end of the entire packing
  164. // buffer (this provides protection against corrupt data
  165. // buffer overruns). Upon return, rpBuf will be set to
  166. // the first byte past the end of the packed ULONG32.
  167. // UnpackPropertyULONG32() is called by UnpackValuesBinary().
  168. HX_RESULT UnpackPropertyULONG32(IHXValues* pValues,
  169.                                 REF(BYTE*)  rpBuf,
  170.                                 BYTE*       pLimit,
  171.                                 IUnknown*   pContext = NULL);
  172. // UnpackPropertyCString() unpacks a CString property
  173. // from binary form, and then sets that CString property
  174. // into the provided IHXValues. Initially rpBuf should
  175. // be set to the beginning of the packed CString and 
  176. // pLimit should be set to the end of the entire packing
  177. // buffer (this provides protection against corrupt data
  178. // buffer overruns). Upon return, rpBuf will be set to
  179. // the first byte past the end of the packed CString.
  180. // UnpackPropertyCString() is called by UnpackValuesBinary().
  181. HX_RESULT UnpackPropertyCString(IHXValues* pValues,
  182.                                 REF(BYTE*)  rpBuf,
  183.                                 BYTE*       pLimit,
  184.                                 IUnknown*   pContext = NULL);
  185. // UnpackPropertyBuffer() unpacks a Buffer property
  186. // from binary form, and then sets that Buffer property
  187. // into the provided IHXValues. Initially rpBuf should
  188. // be set to the beginning of the packed CString and 
  189. // pLimit should be set to the end of the entire packing
  190. // buffer (this provides protection against corrupt data
  191. // buffer overruns). Upon return, rpBuf will be set to
  192. // the first byte past the end of the packed Buffer.
  193. // UnpackPropertyBuffer() is called by UnpackValuesBinary().
  194. HX_RESULT UnpackPropertyBuffer(IHXValues* pValues,
  195.                                REF(BYTE*)  rpBuf,
  196.                                BYTE*       pLimit,
  197.                                IUnknown*   pContext = NULL);
  198. // UnpackValuesBinary() unpacks a binary-packed pBuffer into
  199. // the provided pValues. If pBuffer is not binary-packed, then
  200. // it will return HXR_FAIL. If you pass in an IUnknown context,
  201. // then it will use the common class factory to create the
  202. // necessary IHXBuffer's. Otherwise, it will use "new CHXBuffer()".
  203. HX_RESULT UnpackValuesBinary(IHXValues* pValues,
  204.                              IHXBuffer* pBuffer,
  205.                              IUnknown*   pContext = NULL);
  206. // UnpackValuesBinary() unpacks a binary-packed pBuffer into
  207. // the provided pValues. If pBuffer is not binary-packed, then
  208. // it will return HXR_FAIL. If you pass in an IUnknown context,
  209. // then it will use the common class factory to create the
  210. // necessary IHXBuffer's. Otherwise, it will use "new CHXBuffer()".
  211. HX_RESULT UnpackValuesBinary(IHXValues* pValues,
  212.                              BYTE*       pBuf,
  213.                              UINT32      ulLen,
  214.                              IUnknown*   pContext = NULL);
  215. // PackValues() packs pValues into an IHXBuffer and returns
  216. // the packed buffer into rpBuffer. If bPackBinary is TRUE,
  217. // it will pack the IHXValues as binary; otherwise, it
  218. // will pack the IHXValues as text. If you pass in an IUnknown context,
  219. // then it will use the common class factory to create the
  220. // necessary IHXBuffer's. Otherwise, it will use "new CHXBuffer()".
  221. HX_RESULT PackValues(REF(IHXBuffer*) rpBuffer,
  222.                      IHXValues*      pValues,
  223.                      BOOL             bPackBinary = FALSE,
  224.                      IUnknown*        pContext = NULL);
  225. // UnpackValues() unpacks an IHXBuffer into rpValues. It 
  226. // automatically detects whether pBuffer is binary-packed
  227. // or text-packed (as long as PackValues() was used to pack
  228. // the IHXValues).
  229. HX_RESULT UnpackValues(REF(IHXValues*) rpValues,
  230.                        IHXBuffer*      pBuffer,
  231.                        IUnknown*        pContext = NULL);
  232. // UnpackValues() unpacks an IHXBuffer into rpValues. It 
  233. // automatically detects whether pBuffer is binary-packed
  234. // or text-packed (as long as PackValues() was used to pack
  235. // the IHXValues).
  236. HX_RESULT UnpackValues(REF(IHXValues*) rpValues,
  237.                        BYTE*            pBuf,
  238.                        UINT32           ulLen,
  239.                        IUnknown*        pContext = NULL);
  240. // AreValuesInclusiveIdentical() checks whether all the
  241. // properties in pValues1 are:
  242. // a) in pValues2; AND
  243. // b) identical to the corresponding properties in pValues2.
  244. BOOL AreValuesInclusiveIdentical(IHXValues* pValues1,
  245.                                  IHXValues* pValues2);
  246. // AreValuesIdentical() returns
  247. // AreValuesInclusiveIdentical(pValues1, pValues2) &&
  248. // AreValuesInclusiveIdentical(pValues1, pValues2).
  249. // By checking inclusive identity in both directions, this
  250. // absolutely establishes identity between the contents
  251. // of pValues1 and pValues2.
  252. BOOL AreValuesIdentical(IHXValues* pValues1,
  253.                         IHXValues* pValues2);
  254. #ifdef _DEBUG
  255. // This tests text and binary packing of IHXValues.
  256. // It is also a good place to look for examples of how
  257. // to call PackValues() and UnpackValues().
  258. HX_RESULT TestValuesPacking(IUnknown* pContext = NULL);
  259. #endif
  260. #endif