Futurebasic/Language/cfurlref

CFURLRef Structures

Accessing files and resources via URLs.

Description

CFURL provides facilities for creating, parsing, and dereferencing URL strings. CFURL is useful to applications that need to use URLs to access resources, including local files, hence its inclusion here.

Apple engineers have made CFURL “toll-free bridged” with its Cocoa Foundation counterpart, NSURL. For FB and FBtoC programmers this is good news because of the many code snippets available online in Cocoa that are transplantable into our Carbon code.

A CFURL object is composed of two components:

   1.) A base URL, which can be empty, 0 or NULL in C, and

   2.) A string that is resolved relative to the base URL.

A CFURL object whose string is fully resolved without a base URL is considered absolute; all others are considered relative.

As an example, assuming that your FutureBASIC application is stored in your OS X Applications folder in a folder labeled "FutureBASIC 4.1.1," an absolute CFURL path to its executable would be:

/Applications/FutureBASIC\ 4.1.1/FutureBASIC.app/Contents/MacOS/FutureBASIC 

This object is fully resolved since it is a complete path to the root level of the volume on which it is located.

On the other hand, a relative path not fully resolved would be:

/FutureBASIC.app/Contents/MacOS/FutureBASIC

This relative path defines the location of the FutueBASIC executable within the FutureBASIC.app bundle, but does not indicate where the FutureBASIC application resides.

A CFURL object is defined by a CFURLRef. Like other Core Foundation object references, CFURLRefs are opaque types. Their internal composition is not documented by Apple and they are accessed and manipulated through Toolbox functions.

Among areas where CFURLs and their associated CRURLRefs shine is locating resources inside an OS X bundle.

This example, posted on the FutureBASIC mailing list—the list is an invaluable resource for FB and FBtoC users—demonstrates a technique for obtaining a CFURLRef to a ReadMe text file located inside bundle, and passing the CFURL to the OS X system Launch Services which proceeds to open the file for the user to read in the system's default text application.

include "Tlbx LSOpen.incl"
include "Tlbx CFBundle.incl"
include "Subs DEF USR CFPrefs.incl"

toolbox fn CFBundleCopyResourceURL( CFBundleRef bundle,¬
                              CFStringRef resourceName,¬
                              CFStringRef resourceType,¬
                                CFStringRef subDirName ) = CFBundleRef

local fn OpenReadMe( readMeName as Str255 )
 dim as CFBundleRef  bundle
 dim as CFURLRef     url

 bundle = fn CFBundleGetMainBundle
  long if( bundle )
    url = fn CFBundleCopyResourceURL( bundle, fn CFSTR( readMeName ), 0, 0 )
    long if( url )
      call LSOpenCFURLRef( url, #0 )
    end if
  end if
  
  CFRelease( url )

end fn

fn OpenReadMe( "ReadMe.txt" )

do
handleevents
until gFBQuit

Here's another function that uses a CFURLRef to create an image reference to any one of several kinds of image files recognized by QuickTime—JPEG, PNG, TIFF, etc.-- again located in the Resource folder of a bundled application:

local mode
local fn CreateCGImageFromBundleResource( fileName as CFStringRef )
 dim as CFURLRef           url
 dim as CGImageRef         imageRef
 dim as CGDataProviderRef  sourceRef

 image = 0
 url = fn CFBundleCopyResourceURL( fn CFBundleGetMainBundle(), fileName, 0, 0 )
   long if ( url )
     sourceRef = fn CGImageSourceCreateWithURL( url, 0 )
     long if ( sourceRef )
       imageRef = fn CGImageSourceCreateImageAtIndex( sourceRef, 0, 0 )
     end if
   end if

 CFRelease( url )
 CFRelease( sourceRef )

end fn = imageRef

(More discussion to follow)

0100 1101 0110 1001 0110 0100 0110 1110 0110 1001 0110 0111 0110 1000 0111 0100

0043 6f64 6572