home *** CD-ROM | disk | FTP | other *** search
/ Apple Developer Connectio…eloper Series 2005 March / Dev.CD Mar 05.iso / What's New / Technical Notes and Q&As / ADC Reference Library / technotes / tn / downloads / tn2022.hqx / tn2022 / FileURLDesc.h < prev   
Encoding:
C/C++ Source or Header  |  2001-05-31  |  7.9 KB  |  156 lines
  1. /*
  2.     File: FileURLDesc.h
  3.     
  4.     Description:
  5.         Handy routines for dealing with typeFileURL. These routines assist
  6.         in sending and receiving typeFileURL descriptors in Apple events,
  7.         most helpfully in dealing with references to nonexistent files.
  8.  
  9.     Copyright:
  10.         © Copyright 2001 Apple Computer, Inc. All rights reserved.
  11.     
  12.     Disclaimer:
  13.         IMPORTANT:  This Apple software is supplied to you by Apple Computer, Inc.
  14.         ("Apple") in consideration of your agreement to the following terms, and your
  15.         use, installation, modification or redistribution of this Apple software
  16.         constitutes acceptance of these terms.  If you do not agree with these terms,
  17.         please do not use, install, modify or redistribute this Apple software.
  18.  
  19.         In consideration of your agreement to abide by the following terms, and subject
  20.         to these terms, Apple grants you a personal, non-exclusive license, under Apple’s
  21.         copyrights in this original Apple software (the "Apple Software"), to use,
  22.         reproduce, modify and redistribute the Apple Software, with or without
  23.         modifications, in source and/or binary forms; provided that if you redistribute
  24.         the Apple Software in its entirety and without modifications, you must retain
  25.         this notice and the following text and disclaimers in all such redistributions of
  26.         the Apple Software.  Neither the name, trademarks, service marks or logos of
  27.         Apple Computer, Inc. may be used to endorse or promote products derived from the
  28.         Apple Software without specific prior written permission from Apple.  Except as
  29.         expressly stated in this notice, no other rights or licenses, express or implied,
  30.         are granted by Apple herein, including but not limited to any patent rights that
  31.         may be infringed by your derivative works or by other works in which the Apple
  32.         Software may be incorporated.
  33.  
  34.         The Apple Software is provided by Apple on an "AS IS" basis.  APPLE MAKES NO
  35.         WARRANTIES, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION THE IMPLIED
  36.         WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  37.         PURPOSE, REGARDING THE APPLE SOFTWARE OR ITS USE AND OPERATION ALONE OR IN
  38.         COMBINATION WITH YOUR PRODUCTS.
  39.  
  40.         IN NO EVENT SHALL APPLE BE LIABLE FOR ANY SPECIAL, INDIRECT, INCIDENTAL OR
  41.         CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
  42.         GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  43.         ARISING IN ANY WAY OUT OF THE USE, REPRODUCTION, MODIFICATION AND/OR DISTRIBUTION
  44.         OF THE APPLE SOFTWARE, HOWEVER CAUSED AND WHETHER UNDER THEORY OF CONTRACT, TORT
  45.         (INCLUDING NEGLIGENCE), STRICT LIABILITY OR OTHERWISE, EVEN IF APPLE HAS BEEN
  46.         ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  47.  
  48.     Change History (most recent first):
  49.         May 31, 2001 -- created
  50. */
  51.  
  52.  
  53. #ifndef _FILEURLDESC_
  54. #define _FILEURLDESC_
  55.  
  56. #if FRAMEWORKS
  57.     #include <Carbon/Carbon.h>
  58. #else
  59.     #include <Files.h>
  60.     #include <Navigation.h>
  61.     #include <AppleEvents.h>
  62.     #include <AEDataModel.h>
  63.     #include <CFString.h>
  64.     #include <CFURL.h>
  65. #endif
  66.  
  67. /**************************************************************************
  68.   typeFileURL is a simple AE data type.  The data of a file URL is the data
  69.   of a 'file'-scheme CFURL. This type is also sent by and can be used with
  70.   the Drag Manager.
  71. **************************************************************************/
  72.  
  73. #define typeFileURL 'furl'
  74.  
  75.  
  76. /**************************************************************************
  77.   This call extracts the operative parts of a NavReplyRecord and creates a CFURLRef.  
  78.   After calling FURLCreateFromNavReply, you are responsible for releasing the CFURLRef.
  79. **************************************************************************/
  80.  
  81. OSStatus FURLCreateFromNavReply(CFAllocatorRef allocator, const NavReplyRecord * navReply, CFURLRef* ref);
  82.  
  83.  
  84. /**************************************************************************
  85.   These calls can be used to put typeFileURL descriptors into and out of Apple event descriptors and records.
  86.   FURLCreateDescFromCFURL takes a CFURLRef and fills out an AEDesc record, which you are then responsible for
  87.   disposing of when you are finished with it.  FURLPutParamCFURL works like AEPutParamDesc but takes a 
  88.   CFURLRef (which you remain responsible for).  The FURLPutKeyCFURL is an equivalent function for an AERecord.
  89.   
  90.   These calls obey AppleEvent calling conventions and return an OSErr.
  91. **************************************************************************/
  92.  
  93. OSStatus FURLCreateDescFromCFURL(CFURLRef url, AEDesc * desc);
  94. OSStatus FURLPutParamCFURL(AppleEvent * event, DescType key, CFURLRef url);
  95. #define  FURLPutKeyCFURL(e, k, u) FURLPutParamCFURL((AERecord *)e, k, u)
  96.  
  97.  
  98. /**************************************************************************
  99.   These calls can be used to create CFURLs from the contents of Apple event structures.  FURLCreateFromAEDesc
  100.   takes a string AEDesc and creates a new CFURL, returning you the CFURLRef; it does not affect the input desc.  
  101.   FURLCreateFromAppleEventParam extracts a string descriptor from an Apple event and creates a CFURLRef
  102.   from it if possible.  FURLCreateFromAERecordKey is the equivalent function for dealing with AERecords instead of
  103.   Apple events.
  104.   
  105.   For all of these calls, if the input string is typeChar, typeStyledText, or typeUnicodeText, it will be
  106.   percent-escaped.  If it is a typeFileURL it is assumed to be escaped already.
  107.   
  108.   You are resposible for disposing of the CFURLRef.
  109. **************************************************************************/
  110.  
  111. OSStatus FURLCreateFromAEDesc(CFAllocatorRef allocator, const AEDesc * desc, CFURLRef * url);
  112. OSStatus FURLCreateFromAppleEventParam(CFAllocatorRef allocator, const AppleEvent * event, DescType key, CFURLRef * url);
  113. #define  FURLCreateFromAERecordKey(a, e, k, u) FURLCreateFromAppleEventParam(a, (const AERecord *)e, k, u)
  114.  
  115.  
  116. /**************************************************************************
  117.   This call is an alternative to CFURLCreateFromFSRef, but takes an FSSpec that may specify a nonexistent
  118.   file.
  119. **************************************************************************/
  120.  
  121. OSStatus FURLCreateFromFSSpec(CFAllocatorRef allocator, const FSSpec * spec, CFURLRef * ref);
  122.  
  123.  
  124. /**************************************************************************
  125.   This call can be used to create a new file from a file specified by a CFURL.  It behaves like FSCreateFileUnicode
  126.   (which it uses) but takes a CFURL instead of an FSRef and UniChar *.  It also takes the whichInfo and catalogInfo
  127.   fields and passes them unaltered to FSCreateFileUnicode.  Note that the entire path up to the leaf
  128.   node file must exist; this call will not create intermediate directories specified in the URL.  It returns the
  129.   same error codes as FSCreateUnicode.
  130. **************************************************************************/
  131.  
  132. OSStatus FURLCreateFileWithCFURL(CFURLRef url, FSCatalogInfoBitmap whichInfo,
  133.   const FSCatalogInfo * catalogInfo, FSRef * ref);
  134.  
  135. /**************************************************************************
  136.   The following routines can be installed as coercion handlers in your application.  They coerce between typeFileURL and
  137.   the following types:
  138.   
  139.   typeChar
  140.   typeStyledText
  141.   typeUnicodeText
  142.   cFile
  143.   typeFSSpec
  144.   typeFSRef
  145.   typeObjectSpecifier
  146.   
  147.   In the case of typeObjectSpecifier, the keyAEKeyData field of the specifier can be any string type
  148.   to coerce to a typeFileURL, and will be typeUnicodeText when coercing from typeFileURL.
  149. **************************************************************************/
  150.  
  151. OSErr FURLCoerceDescToFURL(const AEDesc *fromDesc, DescType toType, long handlerRefcon, AEDesc *toDesc);
  152. OSErr FURLCoerceFURLPtrToDesc(DescType typeCode, const void *dataPtr, Size dataSize, DescType toType, long handlerRefcon, AEDesc *result);
  153.  
  154.  
  155. #endif
  156.