Accessing the Connection Speed Preference

Dispatch 17

Question: How do I get and set the Internet Connection Speed?

QuickTime 3.0 allows the user to specify their connection speed to the Internet. With QuickTime 3.0, many web sites provide several different versions of the same QuickTime movie, each optimized for viewing at a particular data rate. By knowing the user's maximum available data rate, QuickTime can automatically select the highest quality version of a movie that the user can stream in real time. To learn more about providing multiple alternate versions of the same content, optimized for streaming at a range of data rates, see Dispatch 15.

The user can set the Connection Speed from the QuickTime Plug-in Settings panel or from the QuickTime Control Panel (see Figure).

Figure. Setting Connection Speed from Control Panel

How It's Done

Your application may want to know the Connection Speed that the user has set. Because this information is stored in the QuickTime Preferences, you can access it using QuickTime's Movie Toolbox. Each QuickTime Preference is stored and retrieved by specifying its four character code. For example, the Connection Speed preference's four character code is shown below:

#define ConnectionSpeedPrefsType OSTypeConst('cspd') 

To retrieve a particular QuickTime preference, the function GetQuickTimePreference is used. The following sample code shows how to retrieve the Connection Speed setting from the QuickTime Preferences.

struct ConnectionSpeedPrefsRecord {
	long	connectionSpeed;
};
typedef struct ConnectionSpeedPrefsRecord ConnectionSpeedPrefsRecord;
 
...
OSErr err;
QTAtomContainer prefs;
QTAtom prefsAtom;
long dataSize;
Ptr atomData;
ConnectionSpeedPrefsRecord prefrec;
 
err = GetQuickTimePreference(ConnectionSpeedPrefsType, &prefs);
if (err == noErr) {
	prefsAtom = QTFindChildByID(prefs, kParentAtomIsContainer, 
				ConnectionSpeedPrefsType, 1, nil);
	if (!prefsAtom) {
		// set the default setting to 28.8kpbs
		prefrec.connectionSpeed = kDataRate288ModemRate;
	} else {
		err = QTGetAtomDataPtr(prefs, prefsAtom, &dataSize, 
		        &atomData);
		if (dataSize != sizeof(ConnectionSpeedPrefsRecord)) {
		    // the prefs record wasn't the right size, 
		    // so it must be corrupt -- set to the default
		    prefrec.connectionSpeed = kDataRate288ModemRate;
		} else {
		    // everything was fine -- read the connection speed
		    prefrec = *(ConnectionSpeedPrefsRecord *)atomData;
		}
	}
	QTDisposeAtomContainer(prefs);
}

Note that in this code, if no preference has been set by the user, we assume a connection speed of 28.8. This is typically a good default if nothing has been specified. After the sample code has run, the prefrec variable will contain the connection speed. The Connection Speed is stored as the number of bytes per second that can be transfered. So, for example, if the Connection Speed is 28.8, the value of prefrec will be 2800. The interface file "MoviesFormat.h" contains constants for all the Connection Speeds displayed in the QuickTime Connection Speed settings dialog. These constants are also shown below.

enum {
	kDataRate144ModemRate  = 1400,
	kDataRate288ModemRate  = 2800,
	kDataRateISDNRate      = 5600,
	kDataRateDualISDNRate  = 11200,
	kDataRateT1Rate        = 150000L,
	kDataRateInfiniteRate  = 0x7FFFFFFF
};

Note that if the user specifies "Intranet" the value kDataRateInfiniteRate is selected. This is the fastest data rate that can be specified.

In some rare cases, your application may need to set the user's connection speed - perhaps as part of a unified installer. This is done by using SetQuickTimePreference. In the following sample code, the Connection Speed is set to the T1 data rate.

err = QTNewAtomContainer(&prefs);
if (err == noErr) {
	prefrec.connectionSpeed = kDataRateT1Rate;
	err = QTInsertChild(prefs, kParentAtomIsContainer, 
	        ConnectionSpeedPrefsType, 
	        1, 0, sizeof(ConnectionSpeedPrefsRecord), 
	        &prefrec, &prefsAtom);
	if (err == noErr) {
		SetQuickTimePreference(ConnectionSpeedPrefsType, prefs);
	}
	QTDisposeAtomContainer(prefs);
}

Note that while it is possible to set any Connection Speed value, Apple recommends only using those values for which constants have been enumerated in "MoviesFormat.h".

See Also

Dispatch 15

Change History

6/1/98 - mdd - First published