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