Welcome to the Parallax Discussion Forums, sign-up to participate.
Headset <state_nvar>, <type_svar>, <mic_nvar>
Reports if there is a headset plugged into your device, and returns data about the headset. The parameters are all names of variables that receive the data:
<state_nvar>: 1.0 if a headset is plugged in, 0.0 if no headset is plugged in, and -1.0 if unknown.
<type_svar>: A string describing the device type of the last headset known to your device.
<mic_nvar>: 1.0 if the headset has a microphone, 0.0 if the headset does not have a microphone, and -1.0 if unknown.
On Android phones, on iOS devices, and on HD Audio PCs, no mechanical switches in the socket are used. Instead, the headphone socket has 4 contacts instead of 3, and accepts both 4-contact headsets and 3-contact headphones. The sleeve of the 3-contact headphone audio jack connects two of the socket contacts together.
One of the contacts is responsible for microphone and usually feeds 1.5-3.3v of voltage through a current limiting resistor (2-10 kOhm), which is necessary to bias a JFET transistor in the microphone capsule of a headset. DC resistance measurement between the microphone pin and the ground pin of the socket can be used to detect the kind of device plugged in - it will be 0 Ohm for a headphone, infinitely high for no device connected, and about 2 kOhm thereabouts for a headset with microphone.
The bias current limiting resistor forms a part of voltage divider network, with the other part being the above mentioned DC resistance. Voltage measurement on the microphone pin is taken to both determine the sound pressure on the microphone (through a 100hz high pass filter thereabouts) and the kind of jack or device inserted (through a low pass filter or noise rejection logic), allowing this design to be implemented without extra parts, if the filters are implemented digitally. Corresponding to the above DC resistances, you will measure about 0V on the microphone pin if headphone is connected, the full mic bias voltage in case nothing is connected, and something in between in case a headset is connected.
Switches in the audio jack like in the answer above were common in older electronics, but are incompatible with headsets and are just too bulky for a high-tech handset.