All right, so let's get started. Let's have a look back. So we've had wireless in Mac OS ever since Mac OS 9, and as far back as that, you could actually make some AppleScript calls against our dictionary to do really basic tasks, scanning, joining networks. We even had some controls for the base station, so you'd be able to dial your base station back when modems roamed the earth.

Starting with Mac OS X, the interface that you use, that we use internally to talk to AirPort went private, and it has been that way pretty much until today. So starting with Snow Leopard, we're going to have a public API that will allow you to access the AirPort interface. This includes scanning, connecting the networks, and a bunch of other features we'll talk about over the course of the session.

All right, so why are we doing this? There are out there right now, in fact, some of you in the audience may have written tools that using the private API go out and perform scans, okay? Now, these are important tools. There's a lot of them. And people use them a lot in these self-help scenarios where they're trying to figure out what's going on with their wireless network and trying to find solutions for themselves. So we really wanted to provide a way for people to sort of more easily write these tools out of the box, and we want to enable some other utilities that we're going to talk about in the session.

So, airport utilities. So, here we've got a really simple scanning utility. It takes a look around at all the available wireless networks, reports back the sort of detailed information that you need when you're in a sort of self-help scenario. So, our first demo and our first portion of the thing is we're going to talk about how to build one of these, the specific steps you need to take.

And for the more sort of complicated, secure, modern enterprise network, there's a few other things you're going to need to know to get those set up. So besides the utilities that exist, the other use case we really want to take care of is people in education and enterprise environments who want to write configuration tools to help you really, you know, make it easy for your users to get set up and onto your network.

Okay, so for our first demo, we're just going to have a quick look around, okay? So we have to get set up. Obviously, there's some set up to do. Once we do that, we're going to have a peek at the status of the interface as it exists. We're going to do some simple scanning.

Look at those scan results. And then finally, of course, with any good piece of API, there's some cleanup work to be done once we're finished. So let's get going with setup. So to use the AirPort API-- and this is in your seed. If you have your seed builds, go look in System Library Frameworks for the AirPort framework.

There's going to be an AirPort reference the entire time you're working with this API. And this reference is an opaque pointer type that we use that you can use to access a particular interface. So the first thing you need to do is create one. So AirPort create ref will initialize a reference for you and get it ready to use.

Once you've got the reference, you need to bind it to an interface. Now, we ship systems right now with either zero or one AirPort interface in them. This interface supports multiples. And for the most part, users have these, all the laptops do, but some of the machines, in particular our tower demo systems here, do not. So it's important when you're doing these kinds of utilities to check and see if you have an interface available at all. Some of your users may not have them.

Once you've got the list, and remember, it's either going to be empty or it's going to have the primary AirPort interface in it, you can bind your reference to it. So you pass the reference, and this calling convention is used throughout. The reference is the first argument. And in this case, we're passing in the string, which is just the interface name. So EN1 most of the time.

Okay. Once we've got the interface set up, we've bound it to our primary interface, we can do some really simple status operations. And really the most fundamental piece of status is, hey, is this thing on? All right. So AirPort getPower takes that reference that you've created and initialized and gives you the Boolean, is the power on or off? So it's pretty important. If there's no power, you're not going to get a lot of information back from any of these calls.

Once you determine the power zone, if it's off, by the way, there's a corresponding AirPort set power call that you can use to bring the interface up. Once you've done that, you can copy the status, okay? And this gives you some really good information about what the... What the card is doing at the moment, whether you're connected to an interface or to a network, excuse me, what if you are, what the network name is, the particular BSS ID you're associated to, all of your transmit power and signal and noise information for your current connection. Copying the status is a relatively inexpensive operation, so we want to do it always before we start scanning so that we know what state we're in before we do any real work.

which takes us right to scanning. This is really the heart of the API because this allows you to go out, look around, and find the wireless networks in your vicinity. So airport create scan results takes that reference that we went to the trouble to set up, takes the dictionary of arguments.

Now, most of the time you're just going to pass in null here. We'll talk about some of the special cases a little later, ways you can control the scan a little further. And then you get your array of results back out of that. Now, you should be aware this call can take a little while, and we'll see that in the demo. We're pushing seven or eight seconds, depending on what hardware you have. So we'll talk a little bit more about that, too. All right.

Okay, so that list of results, what's in there? It's a bunch of dictionaries, and each of the dictionaries we call a scan record, okay? And it's got keys and values. You'll see in the framework there's airporkeys.h, which contains, you know, the list of keys for particular features and descriptions of them so that you have something to sort of go from. But generally, it's the network's information and capabilities, how much signal and noise there was on the radio end when we were measuring, and a bunch of other detailed info we'll see in the demo here.

Okay, cleanup, very important. All of the calls that you're making here are giving you a copy of these lists or objects or dictionaries. So these are CF types. You need to CF release them when you're done. When you're done with the AirPort ref, and you can keep this thing around for the lifetime of your application and reuse it, it's more efficient that way, you call AirPort release ref, and that'll allow us, that'll give us a chance to clean up everything we need to clean up on the back end. Okay, so, you know, remember to try not to sweep things under the rug. It's always best to clean up after yourself. All right, and that brings us to our first demo.

Thank you. OK, so here we have a little demo application. I left it running from earlier. This already has the status information in here. And if this little pointer works, you can see-- We've got what state the interface is in. Right now we're not connected to anything. You can see what PHY mode we're in, whether the power's on, The actual BSS ID that you're associated to in this point, it's all zeros because we're not connected to anything. Transmit power flags. So this is the info information for when you're not connected to a network. You get a little more out of this when you are connected. Let's have a peek here, and we'll start up the scanner.

All right, so here we've got a really simple scanner, similar to the one you saw on the slides. It's got a lot of options, though. So we're going to kick off a scan. So remember I said this takes a few seconds, and you can see the delay there. All right. Thanks, whoever set up that one.

So each of these rows here is one of the scan records. So we're going to go right across the top here and have a look at each of them as they go. The SSID string is our interpretation. We've parsed out the SSID into a string for you. So that one's set up and ready to go.

BSSID is the basic service set identifier. That's going to be the wireless MAC address of the base station that's sending out the probe frame. The channel number, of course, you know, channels below, 14 and below, are the 2.5 gigahertz channels. Higher channels are 5 gigahertz. BSSID is the basic service set identifier.

RSSI, which is the Received Signal Strength Indicator, that tells you how the signal's doing. It's given in DBM, and I encourage you to look that up to see how to interpret it. It's a fairly complicated thing if you're not familiar with radio information front end. Noise, of course, very important.

Your beacon interval, which is sort of a technical detail you may or may not be interested in. This capabilities field here, if you look at the AirPorT var.h in the thing, this is a bit field and it tells you what the network's capable of doing. So what protocols it's supporting, what types of security. You can parse that sort of information out of there.

The channel flags, if you're not content to find out from the channel number, you can determine from the channel flags whether you've got a 2.4 or 5 gigahertz network. And for our equipment that's operating in 5 gigahertz, you can tell whether it's a single or double wide channel, so HT40 or just a 20 megahertz basic channel.

The age column here, if you get a cached set of scan results back, so if more than one process asks for a scan, you might get a slightly older version of it, and that's to keep from using too much air time on our end. So this will indicate to you how old this record is. Usually it's going to be zero.

The mode information for the element, this HT elements present tells you if there's--if using wide channels. This next column here, this is the actual data of the information elements. So you can see it's not particularly human readable, but if you have a custom information element that you're looking for, you can get it out of this property of the dictionary.

What rates are supported? You can see the actual bytes of the SSID string. If you didn't like our decoding, you can try it yourself. Here are the bytes. You can go ahead and have a peek at that. And then finally, this one on the right here, and this one's by far the largest, this is a parsed-out version of the 802.11d information element.

Okay, so that's a public information element, and it tells you where the base station thinks it is in the world, what country code it has assigned to it, and what its capabilities and channel set availability are. So there's really a lot of information in there. It's kind of compressed down through this table view here, but you can see that just from scanning, we've picked up, you know, quite a bit of good background information on our wireless environment, and we can use that to help our users out. Slides, please.

Okay. So we saw the demo. So that's a really simple scanner. This thing's a fairly small chunk of code. We want to look at now a real setup assistant. So this is a much more complicated set of tasks here. We have--we may want to do some directed scanning.

If we know what network we're looking for ahead of time, we can optimize our scanning to get some better, more specific results that we care about in particular. If we're still just doing broadcast scans, there'll be some information on how to filter the results that come back, okay? So you can get a pretty good-sized list depending on what environment you're in.

So you may want to cut that down a little bit. How to connect to a network. So this is a pretty critical feature, right? Once you've done all the scanning, what are you gonna do? You need to get associated. So we're gonna get into how to achieve that.

Once you've connected, you may want to monitor the connection to make sure it looks good. Keep an eye on things. So check your signal strength out. For some things on the interface, it's more efficient to listen for events. And we'll talk about that. And this is actually pretty important because one of the things that we're going to talk about in the third part of this is things that you can do to help your application perform well and put less load in the system. And this is a big one. So event-based in general, of course, is more efficient. And we've got some information for you there. And finally, we're going to take a brief look at setting and preferences, getting some information about the join mode and some other things.

Okay, so for directed scanning, you remember we talked about AirPort create scan results, which takes a dictionary of arguments, okay? So one of the things you may be interested to do with this is directed scanning. And this is where you request a scan, not of every network that's visible, but of a particular network. And you can scan either by the SSID, which is the network name, or you can scan if you're looking for one specific piece of equipment by the BSSID, so the actual hardware identifier.

And these scans can actually run faster because once we find the network that we're looking for, we know we're done. And you can even further specify these if you have some more information about the network. Like, for instance, if you know what channel you're looking for, you can provide an array of channels. And that's really going to speed up the scan time because the fewer channels we have to scan, the faster it goes, the quicker you get your results.

So if you are scanning for the BSSID, you're going to get either one result or nothing, right? The base station is either visible or it's not visible. If you're scanning for an SSID, you may get multiples. For instance, the network here has many, many base stations, but one SSID. So you get every station that was visible from the point at which you did your scan.

All right, filtering your scan results. So the keys that you're going to find the most helpful to dig through this list are, and these are taken right out of there, are this SSID string. Okay, so this is the name of the network. Obviously, if you know the name, it's pretty easy to search for that.

The security type. Okay, so there's a security type field, and that'll tell you sort of the human readable security, whether it's an open system, a web network. And that's probably the most critical one if you're in an enterprise environment. You want to get the right network, and you want to make sure it has the right security type. before you present it to your user. Make sure it's what you're expecting.

And then finally, and we saw this in the previous example, the information elements that the vendor provides. So this comes through as that binary blob. You may have to do some parsing to get your particular bit or piece of information out of there. But if you have custom hardware, if you have some vendor hardware that you know has a custom information element, you can also use that to do your scanning.

All right, so getting connected to a network. After scanning, this is probably one of the more important features of the API, because it allows you to actually get your user connected and move them onto the packets flowing portion of their day, which is what they're really after. So AirPorr associate here takes the reference, as does every other call. It takes the network record. So that's the scan record that you got back from a scan.

So you may find that it's best to do a directed scan, even if you know the network name, so that you'll get the information to make the associate faster. And that's knowing what channel that we're on and knowing what security type really speed up the process of getting connected. So it's worth taking the time to do that directed scan ahead.

And then finally, there's a results dictionary. That's sort of for future implementation. If there's any information about the association that we think you need to know, we're gonna stash it in there for the future. Big things that you might sneak into this arguments dictionary. The really obvious one is the password. So if it's a secure network, you need to provide that.

If it's an enterprise security network, you may need to provide the username and the password. You may also need to provide the 802.1x profile information that it's going to use, so the authentication types especially. And that's what we're going to get into a little bit more in this demo here.

And finally, if you're looking to disconnect, just unplug for a little bit, there's AirPorT Disassociate. And that'll actually, you know, it's like unplugging your Ethernet. It's going to drop your wireless connection for you. So if you ever have need of it, it's there for you. And look at our next slide.

Once you've established a connection, you get a good error code back, you might want to keep an eye on it. Okay, so there's several things that you're going to change over time or as you move around, right? The signal strength can come and go. You can roam to different access points, change your BSS ID. So we looked at AirPort copy status a little earlier, and it has facilities in there for getting these kinds of bits of information.

So the connected network name we saw, or we didn't see because we weren't connected. The op mode that the card is in. So most of the time, the card is a client, okay? You can, if you want, start up an IBSS, and then the card goes into IBSS mode, which is a different operations mode. Okay.

If the user turns on internet sharing, you're going to find yourself suddenly in software base station mode, where the card's acting as a software base station. So checking the status, making sure you know what's going on with the interface is a really good idea. If you're a software base station, it's probably a bad idea to try and join another network before you turn that off. And then the one that probably is most interesting to people is, what's the signal and noise? How good is my connection? What should I be expecting in terms of performance here? So that's the most popular feature by a long shot.

Okay, so getting the status of an interface is fairly inexpensive, but it's not free. And there are some things, there are a lot of things about your status that only change very rarely. So roaming, for instance, happens infrequently. Interface power events happen. It would be really nice if we could get notified of these things asynchronously, okay, because we don't want to sit and poll the interface repeatedly. So for that, we have AirPorT event monitor start and AirPorT event monitor stop.

Takes that AirPorT reference. You're going to provide a callback function pointer, your own context pointer if you need one, and then provide an array of event types that you're interested in. And these are in the header. As you can see, there's a list. Principally, the things you're going to be looking out for are, like I said, the power changes. So if someone turns the power on and off, you're going to get a notification. Link changes.

If we wander out of distance of one access point and you lose our link, you're going to get a notification. Similarly, if you come back into range into range and we find one, you'll get the link out message. Op mode changes like we talked about previously if you go from IBSS to BSS to SWBSS in any given day.

And it's important to keep in mind that when these events are delivered, it's a good time to check your status, OK? Because you get an event in, you'll know what it is. You can check your status then to update things like what station am I attached to. Signal strength is one you do have to keep an eye on yourself manually if you want to monitor it over time. No need to check every second. Every five or 10 seconds will do fine.

Okay. So preferences. We're going to talk about this one pretty quickly. There's two calls here, one to copy a preference value and one to set a preference value. And this allows you to look at things like, well, even the power settings. Is the power setting on so that the interface is going to come up when you restart the machine? Whether you're going to be in a particular join mode. And then also you can get information here about the list of preferred networks. Okay.

And we're going to add -- we don't have it -- we didn't get it quite into the seed, but we're going to add the ability for you to set a preferred network without actually associating to it. So for the enterprise demo that we're going to show you, it's all live, but there's definitely a case that we want to support where you're configuring a bunch of machines and you're offline. You don't actually -- in the presence of the network that you want to configure. Okay. So that's our second demo.

All right, we still have our channel information here, so let's bring up this assistant. So this is a really simple step through assistant. We're going to go through the process of scanning, looking at our network list, making association, and then having a peek at it. So we've got our first screen here.

So now we're going into our scanning phase. And this takes a few minutes-- or a few seconds, excuse me-- just as it does in the other demo. Now I happen to have a 1x network here with me. And you can tell that by the name. OK. So we've detected that we have a 1x network. We want the username and password.

You may want to use this password one time. So we provide a checkbox here for this. If you have a network that has two-factor authentication, you have a secure ID card, you probably don't want the password saved. In this case, it's just a password, so we're going to uncheck that.

On the previous screen, you missed there's a checkbox also. I should have stopped for a second longer. It says, hey, do we want to remember this network or not? And this is another parameter that you can give to the associate call to say whether or not this thing gets added to the preferred list. So we have that checked. And let's go ahead and try and associate.

And we made it. So here you can see we have the network's name and it's keeping an eye on the signal here. As the signal changes, it'll animate a little so you can see how well it's receiving the signal. Okay? So, and this is using a lot, this is using the techniques that we just talked about in the previous slides here to get you through to this endpoint. All right. Slides, please.

So we talked about a really simple scanner, OK, and we talked about this slightly more complicated enterprise assistant that uses the associate calls. For this part of the presentation, I want to talk to you a little bit about managing the shared, precious shared resource that is the AirPort interface.

We, like any network interface, there's a lot of competition, or there's a lot of different people that are using it. And especially because this is the primary interface that a lot of people use today to connect. I mean, you get a MacBook out of the box, the first thing you do is flip it open, and you get connected to a wireless network.

So as we're using this API, there's some things we really have to take in to be mindful of. All right. And the first one is sort of take a look before you scan. We talked about checking your status before you break into a scan. And that's really important because you're going to be behaving differently when you're connected than when you're not connected in terms of how often you perform a scan if you're performing it repeatedly.

The second one, we touched on this a little bit earlier, is that scanning does take time. It used to be that it was very fast. It's getting long-- it's long now. It's getting longer. We'll talk a little bit about why that is and what you can do to mitigate that. And the third, this is, you know, true of all programming, is preparing for failure. And this is, you know, sort of an especially important consideration where we may or may not have cards. There's a lot that can go wrong here. All right. So look before you scan.

Copy status, copy status, copy status. Always have a look at what your card is doing before you start scanning. Listen to the notifications, okay? There are times when it's just not appropriate to scan. If you're in base station mode particularly, it doesn't make a lot of sense to go off and do your scanning.

There's a lot of useful info, but the big thing, the thing that you're going to base most of your decision-making on is are you currently connected to a network, okay? So if you are connected, scan less, okay, and much less. So every 45 to 60 seconds is pretty reasonable. So you're going to get, you know, updates every minute or so. This is unless you're driving around in a car, that's probably a pretty reasonable amount of time to wait before you update your network environment.

So if you're disconnected, scan less, okay. So scanning does take time, as we're about to talk about, but it also, you know, uses energy. So if you're on a battery, you're using power to scan. And if you're out and about, now, if you're not connected, you're not going to be interrupting network traffic.

And the reason we say to scan so infrequently is that when you scan, we can't move packets to the network that we're connected to, okay. So if you're disconnected, you can get away with scanning a little bit more often, but really every 30 seconds. That should be sufficient.

So doing the scanning takes some time. When we first started, when the first AirPorts cards came out, you could scan the whole 2.4 gigahertz spectrum in less than a second. And that's great. We got a lot of tools that were written around that assumption that it was going to take that long and no longer.

When we started introducing 802.11a and n technology and the 5 gigahertz band that they use, scans started taking a lot longer. There's a couple of reasons for this. So one of them is simply that we have more channels to look at. It takes longer to get through all of them.

The other one is that a lot of the newer channels are what we call passive channels. So these are frequencies that got recycled. A lot of them came from aviation radar systems. And we need to be careful when we're using them that we don't start broadcasting on frequencies that some incumbent is using. So.

In the 5 GHz band, we spend a lot of time looking, checking to make sure it's okay. We don't want to mess with anyone's radar systems. But as a result, it's taking longer and longer to scan. And as we add frequencies, most of the ones that we add are being reused from some other source. So you can expect it to continue to take a while. On some of our most recent machines, we're looking at close to 7 or 8 seconds to perform a full broadcast scan of 2.4 or 5 gig, all the passive channels.

How long it takes really depends. So all the time I'm giving you right now, we're talking about United States systems. If you go outside the United States, where the list of channels is different, there are different rules about which ones can be scanned, these times can get even longer.

So one thing that you can do, as I highly suggest this, is just put a little clock, measure how long it takes you to perform a particular scan, and use that to set your timers. Because it's not going to be the same everywhere. And you really want to make sure that you're not interfering with nearby devices by scanning too much. You want to make sure you're not interfering with your own device by scanning too much.

All right. Prepare for failure. This is, you know, pretty important in all programming, but especially here. So we already talked about some machines do not have AirPort interfaces. Okay. For those machines that do have one, the hardware is installed, it's plugged in, it's powered up, it might not be configured. Okay.

So, you know, there's people using their network control panel can, you know, remove an interface from the list, deconfigure it. Even if it has been configured, it might be disabled. Right. In both those cases, you need to check the power on the card. the power will be turned off.

Now, let's say you've got a card. It's been configured. It's enabled. That's kind of the default state. This is the way the laptops ship, or the AirPort machines ship. You might find when you scan, you get an error code back that comes as eBusy. And eBusy is a code that we use to indicate that we're kind of doing something right now. We're using the interface. So what you need to do, and typically this is when you open the lid, the laptop wakes up, it's going to start looking around for networks to join.

During that searching process, it's going to mark the interface as busy. Your scans will come back with this result code. So if you see this, the thing to do is just back off. Give us five or ten seconds to see if we can't get the user onto the network.

And then start your scan process again and look to see if it's free now. Some of the operations that we talked about are going to require administrative privilege, okay? So in the network control panel, you know there's the little checkbox that says require administrative privilege to modify the AirPort interface.

When you run across one of those restricted features and you make one of the calls in the API, you may have to wait for the user to authorize or not authorize. Okay, so you might block for a few seconds or as long as it takes the user to remember their password. So be prepared for that.

And particularly association, creating IBSS networks, for instance, is another one where those are restricted for various reasons. Keep an eye out for these conditions. Some of these calls, particularly scanning, do take a long time. Don't do them in your UI thread because you will block your user interface.

All right, so that's kind of all the admonitions we have for today. This is an evolving system. Please send us some feedback. We have an email address, [email protected]. You can send us, you know, if you have information about what you're doing, we always like to hear that. If there's features that you need that don't appear, please let us know. And this is, you know, how we're gonna hear back from you to help improve this.

OK, resources. So I've mentioned a couple times the actual framework itself. Go look through the headers. There's lots of good information in there on the specifics of what some of these keys do and some of the information you can get we didn't get into. Things like create IBSS we didn't really have a chance to get into deeply. Code examples-- we're going to post the source for the examples for the demonstration here to developer.apple.com. Give us a little time to get those up and worked out.

And finally, if you have questions about the protocols themselves, so 802.11, the family has really grown over the years. There's a lot more going on than there used to be when it was just 11b. Go to IEEE Explorer, and you can actually get, for everything up to, I think, the current end draft may not be available publicly yet, but you can get the detailed information about all these protocols. So some of the bit fields that we talked about that you see in scan records, you'll have very detailed explanations about what's in there. So IEEE Explorer is the place to go if you need protocol-level information that's not going to be covered by this API.

Okay, even more information. Mark Tozer is our developer and wireless technologies evangelist. You can -- his email and contact information is here. And Rich Kubota is our DTS representative. So these guys have been great. They really -- you know, they're here to help you guys out as developers. So get in touch with them. Let them know what you're looking for. And also use that feedback email. We'll give you a second to write down those names.

All right. So thanks, everyone, for coming out. It's great to have a chance to do this. I want to say thank you to the whole AirPorT team from Apple for making this all possible, and then also the network operations team here. They did a great job for the show getting you all off the wire. So thanks, everybody.