ADC Home > Reference Library > Technical Q&As > QuickTime > Movie Creation >

Sequence Grabber - How do I save user settings as CFPreferences?


Q: I'm using SGSettingDialog so users of my application can set their Sequence Grabber preferences. Once set, I call SGGetChannelSettings on the Video Channel to get the settings I'd like to save off for later use. SGGetChannelSettings returns the settings as UserData. How can I use the CFPreferences APIs to save and subsequently restore these UserData settings?

A: The functions CFPreferencesSetAppValue and CFPreferencesCopyAppValue are the most straightforward way to create and retrieve preferences on Mac OS X. The Sequence Grabber Settings APIs work with channel components and panel components to collect configuration settings from the user and return these settings as UserData.

UserData is defined as a pointer to a UserDataRecord (see Figure 1), an array of items containing settings specific to a instance of a SeqGrabComponent or an SGChannel.

Figure 1.

struct UserDataRecord {
  long data[1];
};
typedef struct UserDataRecord UserDataRecord;
typedef UserDataRecord *      UserData;

By calling User Data functions such as NewUserDataFromHandle and PutUserDataIntoHandle, you can easily create CFPropertyList objects from UserData, or create UserData from CFPropertyList objects, to save off and subsequently restore Sequence Grabber settings.

The GetSettingsPreference and SetSettingsPreference functions as shown in Listing 1 demonstrate one way to save and restore UserData as CFPreferences. Listing 2 demonstrates how these example functions can work together with the SGGetChannelSettings and SGSetChannelSettings calls.

Listing 1.

// GetSettingsPreference
//    Returns a preference for a specified key as QuickTime UserData
// It is your responsibility to dispose of the returned UserData
OSErr GetSettingsPreference(CFStringRef inKey, UserData *outUserData)
{
  CFPropertyListRef theCFSettings;
  Handle            theHandle = NULL;
  UserData          theUserData = NULL;
  OSErr             err = paramErr;

  // read the new setttings from our preferences
  theCFSettings = CFPreferencesCopyAppValue(inKey,
                                         kCFPreferencesCurrentApplication);
  if (theCFSettings) {
    err = PtrToHand(CFDataGetBytePtr((CFDataRef)theCFSettings), &theHandle,
                    CFDataGetLength((CFDataRef)theCFSettings));
        
    CFRelease(theCFSettings);
    if (theHandle) {
      err = NewUserDataFromHandle(theHandle, &theUserData);
      if (theUserData) {
        *outUserData = theUserData;
      }
      DisposeHandle(theHandle);
    }
  }

  return err;
}

// SaveSettingsPreference
//    Saves a preference for a specified key from QuickTime UserData
OSErr SaveSettingsPreference(CFStringRef inKey, UserData inUserData)
{
  CFDataRef theCFSettings;
  Handle    hSettings;
  OSErr     err;
    
  if (NULL == inUserData) return paramErr;
    
  hSettings = NewHandle(0);
  err = MemError();
    
  if (noErr == err) {
    err = PutUserDataIntoHandle(inUserData, hSettings); 
        
    if (noErr == err) {
      HLock(hSettings);
    
      theCFSettings = CFDataCreate(kCFAllocatorDefault,
                                   (UInt8 *)*hSettings,
                                   GetHandleSize(hSettings));
      if (theCFSettings) {
        CFPreferencesSetAppValue(inKey, theCFSettings,
                                 kCFPreferencesCurrentApplication);
        CFPreferencesAppSynchronize(kCFPreferencesCurrentApplication);
        CFRelease(theCFSettings);
      }
    }

    DisposeHandle(hSettings);
  }

  return err;
}

Listing 2.

UserData mySGVideoSettings = NULL;

...

// get the settings using the key "sgVideoSettings"
GetSettingsPreference(CFSTR("sgVideoSettings"), &mySGVideoSettings);
if (mySGVideoSettings) {
  // use the saved settings preference to configure the SGChannel
  SGSetChannelSettings(theSGInstance, theVideoChannel,
                       mySGVideoSettings, 0);
  DisposeUserData(mySGVideoSettings);
}

// bring up the settings dialog to allow for further configuration
SGSettingsDialog( ... );

// get the SGChannel settings cofigured by the user
SGGetChannelSettings(theSGInstance, theVideoChannel, &mySGVideoSettings, 0);
// save the settings using the key "sgVideoSettings" 
SaveSettingsPreference(CFSTR("sgVideoSettings"), mySGVideoSettings);
DisposeUserData(mySGVideoSettings);

...

References:


[Sep 04, 2003]


Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.