include/wx/osx/core/cfdataref.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/osx/core/cfdataref.h
   3 // Purpose:     wxCFDataRef class
   4 // Author:      Stefan Csomor
   5 // Modified by:
   6 // Created:     2007/05/10
   7 // RCS-ID:      $Id$
   8 // Copyright:   (c) 2007 Stefan Csomor
   9 // Licence:     wxWindows licence
  10 // Notes:       See http://developer.apple.com/documentation/CoreFoundation/Conceptual/CFBinaryData/index.html
  11 /////////////////////////////////////////////////////////////////////////////
  12 /*! @header     wx/osx/core/cfdataref.h
  13     @abstract   wxCFDataRef template class
  14 */
  15
  16 #ifndef _WX_MAC_COREFOUNDATION_CFDATAREF_H__
  17 #define _WX_MAC_COREFOUNDATION_CFDATAREF_H__
  18
  19 #include "wx/osx/core/cfref.h"
  20
  21 #include <CoreFoundation/CFData.h>
  22
  23 /*! @class wxCFDataRef
  24     @discussion Properly retains/releases reference to CoreFoundation data objects
  25 */
  26 class wxCFDataRef : public wxCFRef< CFDataRef >
  27 {
  28 public:
  29     /*! @method     wxCFDataRef
  30         @abstract   Creates a NULL data ref
  31     */
  32     wxCFDataRef()
  33     {}
  34
  35     typedef wxCFRef<CFDataRef> super_type;
  36
  37     /*! @method     wxCFDataRef
  38         @abstract   Assumes ownership of p and creates a reference to it.
  39         @templatefield otherType    Any type.
  40         @param p        The raw pointer to assume ownership of.  May be NULL.
  41         @discussion Like shared_ptr, it is assumed that the caller has a strong reference to p and intends
  42                     to transfer ownership of that reference to this ref holder.  If the object comes from
  43                     a Create or Copy method then this is the correct behaviour.  If the object comes from
  44                     a Get method then you must CFRetain it yourself before passing it to this constructor.
  45                     A handy way to do this is to use the non-member wxCFRefFromGet factory funcion.
  46                     This method is templated and takes an otherType *p.  This prevents implicit conversion
  47                     using an operator refType() in a different ref-holding class type.
  48     */
  49     explicit wxCFDataRef(CFDataRef r)
  50     :   super_type(r)
  51     {}
  52
  53     /*! @method     wxCFDataRef
  54         @abstract   Copies a ref holder of the same type
  55         @param otherRef The other ref holder to copy.
  56         @discussion Ownership will be shared by the original ref and the newly created ref. That is,
  57                     the object will be explicitly retained by this new ref.
  58     */
  59     wxCFDataRef(const wxCFDataRef& otherRef)
  60     :  super_type( otherRef )
  61     {}
  62
  63     /*! @method     wxCFDataRef
  64         @abstract   Copies raw data into a data ref
  65         @param data The raw data.
  66         @param length The data length.
  67     */
  68     wxCFDataRef(const UInt8* data, CFIndex length)
  69     : super_type(CFDataCreate(kCFAllocatorDefault, data, length))
  70     {
  71     }
  72
  73     /*! @method     GetLength
  74         @abstract   returns the length in bytes of the data stored
  75     */
  76     CFIndex GetLength() const
  77     {
  78         if ( m_ptr )
  79             return CFDataGetLength( *this );
  80         else
  81             return 0;
  82     }
  83
  84     /*! @method     GetBytes
  85         @abstract   Copies the data into an external buffer
  86         @param range The desired range.
  87         @param buffer The target buffer.
  88     */
  89     void GetBytes( CFRange range, UInt8 *buffer ) const
  90     {
  91         if ( m_ptr )
  92             CFDataGetBytes(m_ptr, range, buffer);
  93     }
  94 };
  95
  96 #endif //ifndef _WX_MAC_COREFOUNDATION_CFDATAREF_H__
  97