My name's David O'Rourke. I have the privilege today of presenting the directory architecture that Apple's pursuing for its future development. A little later, Michael Dasenbrock will join me on stage to talk about something we didn't talk about last year. The presentation today is going to cover what are the Directory Services APIs, why should you care, why does Apple care. We're going to go into how Apple's using the Directory Services APIs.

We're going to give an overview of how to write a plug-in. This is one of the key aspects of Directory Services APIs that we mostly hand-waved about last year. So this year we're going to give you some details. And then we'll have a Q&A and answer any questions that you may have.

The concept of Directory APIs is we've heard feedback for years from Apple that customers want to take an Apple box out of the box, plop it down, and point it at an existing users and groups database, and not have to import or export their data from an existing database and maintain separate databases.

So this concept fits in with Apple's policy of simplifying, in that the users don't have to set up a separate database. And so the concept: just allow Apple services to use customer data. So Apple's Mac OS X system software will be based on a common directory architecture API. This common directory architecture will allow all Apple system software, the desktop and the server, to access directory services via plug-in architecture.

So the architecture is relatively straightforward. We have a directory access API layer that Apple provides. And we're providing some plug-ins ourselves. This is important because we're using our own plug-in architecture to deliver directory access. So we know this can be done. This is not something we're doing special case and then telling you guys to do plug-ins. We are providing an Apple NetInfo plug-in, which is Apple's directory service of choice.

We're also providing an LDAP plug-in. That's V2, for those of you that want to know, we might do V3 in the future. And one of the developer opportunities, as well as being on the top with the developer solution on top of the directory APIs, is for developers to provide plug-ins to other directories that Apple hasn't chosen to write for. That would include Novell. That would include LDAP V3. Any directory that you want, possibly an Oracle database. Some corporations run a proprietary database as their back end.

The API runtime is fairly straightforward. A Directory API client makes an API call. The APIs dispatch that as a Mach IPC request down to the Directory Access API. The Directory Access API looks at the request, determines what plug-in is best suited to handle the request, dispatches it to the plug-in. The plug-in performs magic. It accesses a local file, it goes out on the network. The plug-ins have full access to the entire Mac OS X operating system at that point. They satisfy the reply, return status, and return the results up to the client.

The Directory Services Configuration is another part of the Directory Services. Clearly, clients need a way to enable and disable various directory plug-ins. So, a la the extension manager for Mac OS 9, we're going to have a Mac OS X preference, which will allow users to turn Directory Services on and off.

The other thing this will do is, if you've written a plug-in, this will be the way customers will access your custom configuration. We'll have a configure button or some menu option or something like that that the users will click on. You'll turn control over to your code to put up an HI or do whatever's necessary to configure your plug-in.

The Directory Access APIs have been included in Functionals since DP3. They are on DP4. They are in /system/library/framework/directory service. The API manifests itself in five public C headers: directoryservices.h, directoryservicesconst.h, directoryservicescustom.h, and you can read the rest. If you link with those header files, you have access to the client APIs.

The plugin API will be made available as an SDK shortly, but also for anybody adopting the directory APIs to do a plugin will certainly give you an early seed. The SDK just wasn't quite ready at the time of DP4. But both the client and the plugin API will be part of the final release of Mac OS X. So there will be no SDK or no additional installation if you want to install a plugin on top of Mac OS X.

The APIs offer full support for read, write, and discovery of data in a directory service. Read, for example, would be find me a record named David of type user. Write would be update David's phone number. Discovery would be list all the records present in this directory. The API also offers the ability to publish custom authentication methods. We have defined some standard authentication methods, but you can extend the API and offer new and never before implemented authentication mechanisms. And this also allows clients to discover these authentication mechanisms.

That's the next bullet. The API allows capabilities for discovering of what the directory plug-ins are offering. The directory APIs are standard C API and available from BSD, Carbon, and Cocoa on Mac OS X. So really, we're running more to Core OS level. We're not Carbon, we're not Cocoa, we're more down near the file system layer, the networking API layer. So there's really no runtime issues. And you should be able to access these APIs from pretty much anywhere. any runtime environment on top of 10.

The API presents an abstraction model. The first and most important part of the abstraction model is nodes. I thought of nodes two years ago when we were beginning the early design of this product. Probably a better name would have been scope. But really this allows a plug-in to restrict its damage or how much data it's accessing. The nodes are published by the plug-ins and the directory service represents a collection of plug-ins.

Plug-ins can register zero or more nodes. It's even up to the plug-ins as to what the semantics of the nodes are. The nodes are one-to-one mapping to the foreign system or if one node represents an entire directory which is actually hierarchical on the back end. It's up to the plug-in to interpret the scope of the nodes. Nodes contain records.

Records reside in a directory node. They consist of at least one name and at least there is a keyword because records can have multiple names. I'm known as David O'Rourke. I'm known as Dave O. I'm known as David M. O'Rourke. We want the directory API to be able to accommodate the notion of multiple names mapping to the same record.

And at most one type. Types of records are examples of users, groups, printers, servers, whatever you want for a type of record. So you have the notion of name and you have the notion of category to deal with with record name and type. Records contain attributes and values.

Attribute types would be an example of unique ID, names, phone number, social security number. And then attribute types contain values. So an attribute like social security number would be a single-valued attribute, whereas an attribute like phone number would be multi-valued. You have work, home, fax, those sorts of examples. The API accommodates that sort of flexibility inside the system.

Values come from attributes, and they're contained within attribute types. Values are blobs of data. The Directory Service is data agnostic. So the data is formatted in whatever way the foreign system formats it, or whatever way the attribute type dictates it should be formatted. The Directory Service does no policy implementation in that particular area.

Apple's adoption. This is very important. We're not telling you to do this and adopt it for yourself and then going off and doing your own thing. Our server software as well as our desktop software will be based on the directory APIs. The administration software for Apple's server software is directory API-based.

And the Apple's server software products are already entirely based on the directory service APIs. So those of you fortunate enough to perhaps participate in some early seeds of server software have already used software on directory service APIs. Third-party enhancements or replacements of services can leverage Apple's work in this area. This means you don't need to provide your own administration tool to create a user.

You can simply add an attribute to a user but use Apple's tools to set up and populate the directory. You don't have to provide the full administration suite. You could. We're not saying you shouldn't. We're just saying you don't have to know, you no longer have to deliver the complete solution because you can leverage Apple's software. Thank you. that we're going to be doing using the directory APIs.

Apple software products will be configurable as to what nodes are used. What does that statement mean? That's the briefest I could get. First of all, Apple software will request standard record types which are documented as part of the API. So we will request KDS standard user or KDS standard printer record. This will enable directory node plug-ins to map our standard requests onto their foreign system.

The next thing we do is customers can configure directory access via the search node. One of our plug-ins is a search node, and this -- I could have an hour-long conversation just on this. But in essence, the search node allows the customer to choose which directory nodes the services are gonna use.

So the idea is that if you've added a directory for XYZ, you can go to the search node configuration panel, and you can say, "I wanna use active directory. I wanna then consult net info, and then I wanna consult LDAP in that order wherever anybody wants to find a record." Administrators can use the search node to control data access, access controls, as well as bring new directories online.

API plugin usage and development. We've developed three basic plugins. We've developed a plugin for Apple's own directory service, NetInfo. Now, this really gives you a dual API to use on Mac OS X. You can either use the native NetInfo APIs to access NetInfo, or you can use the directory APIs.

If you use the directory APIs, you're insulated from us changing directory service access. If you use the NetInfo APIs, they work with NetInfo. We've developed an LDAP plugin, so you can access any LDAP v2 system, and we've developed a search policy plugin. And that's what implements the system's policy about how it goes about finding user records, finding group records, and so on and so forth.

Apple software products are being tested with these three plugins. If you have a plugin you want us to test with, you need to contact us. But if you can make your plugin behave like any one of these three plugins, you're very close to being able to have your plugin be able to work with any Apple software out of the box.

The Apple desktop and server software uses this architecture to provide customers directory choice. That's the whole point, and that goes back to slide number one. We are actively looking for developers to develop a plug-in. We are not going to do plug-ins to every single directory system on the planet. If you have a custom directory you'd like to access, we encourage you to contact us to develop a plug-in. If you have a standard directory you want to develop access to, there's a product opportunity there for you to sell the product to Apple customers.

At this point in time, I'm going to stray from what we covered last year in last year's session, and we're going to give you some details on how actually to write a plug-in. And I'd like to invite Michael Dasenbrock up on stage at this time, and I'll be back later.

Thank you, David. My name is Michael Dasenbrock. I am the lead engineer on Apple's Directory Service project. And what I'm going to go over today is I'm going to talk about how to build a directory service plug-in. Basically, I'm going to give you a high-level overview of the plug-in itself, its structure, some of the entry points, and the callback mechanisms that are in each plug-in.

Okay, first of all, what are plug-ins? Plug-ins are code-loadable modules that use Apple's core foundations CF load function. They have seven different entry points, which are listed here. And they also have a series of callbacks, which we'll get into more detail later. Okay, where do you load a plug-in from? Right now there's two standard locations for loading directory plug-ins. We do this for two reasons. We allow you to load into the system path or into the local path.

The system path is somewhat sacred and you generally don't want to be modifying that while you're doing development. Also, it may be a read-only copy of the OS and you may not be able to modify that particular path. So, you load from the local path to allow you to develop that. You can blow it away when you're done and you won't be harming the system. Each plug-in that you develop requires that it has a DS plug extension on it to get loaded by the server.

Here's an example structure of what the Directory Service plug-in is going to look like, or the one that you're going to write. As I stated before, it's loaded in one of the two directory paths. And as you can see here, what's going to be inside that is going to be your plug-in with a .dsp extension. Inside that is your plug-in. It's basically your executable, the one that you're going to write. So that's what gets loaded by the directory server.

Also inside there is a resources folder. Inside this resources folder is a required property list. I'll get into more detail about what's going to be in that. As well as any additional information that you may want for your plug-in. Say, for example, you want some configuration information or runtime files that you need to have. It's guaranteed to go along with your plug-in. That's a great place to put them.

Okay, now here's that property list that I was talking about earlier. The items that you see in blue are the keys. Those are required and they need to be in each field. And as you can see, you can see that in the green, those are the items that you're going to provide. And the reason why I brought this slide up is the one issue that's going to be most particular to those plug-in developers is the plug-in UUID. That UUID needs to be unique to your plug-in on the system that it's loaded to.

If there's a conflict during load time, the plug-in will not get loaded and the first one with the same UUID is loaded and the other one is not. There will be ways to detect this and I'll get into that later. There will also be on the SDK that's to be provided later tools to generate a UUID.

Okay, how to make a directory plug-in. First of all, the best place to start is to start with the sample source code that we're going to provide on the upcoming SDK. You can build and install this plug-in. Once you've built this plug-in and installed it, it gives you an idea of how to take -- you can look at the entry points. You can look at the callback mechanisms. This is a working plug-in. It does nothing more than stub out all of the calls that you're going to be expected to process from client data, as well as it registers a single node.

After you've got your plug-in built, you're going to want to test it. Testing it is also going to be through some tools that we're going to provide. We have, we're going to provide a test app on the developer SDK. You again install it in the locations that I spoke about earlier.

To load your plugin you need to first stop the directory server and then relaunch it because the plugins are loaded at launch time. Right now they're not loadable on demand. That may change in the future. We haven't decided yet. And then you can verify that your plugin is loaded by looking into the log file.

Okay, again, you can compile and build a directory service API test client that we have. It will allow you to do two things. It will allow you to test your plugin as well as give you an idea of what clients are going to be requesting from your plugin so that you can get an idea of how to write your plugin to service request for data. And it gives you, again, ideas how to use callbacks. Okay, here are the-- we'll talk a little bit about this. We'll talk a little bit now about the seven entry points into your plugin. First one is validate.

Validate is called once at load time. It's basically kind of a handshaking. Are you who you say you are? Are you the kind of plugin I'm looking for? Okay, I'm going to load you. After all of the plugins have been loaded, your plugin then gets called with initialize. This is now the time for you to go and do any startup information or startup routines that you need like open up networking ports, open up a database file, spawn off threads, I'm not going to be able to do it.

Once initialization has been successfully completed, then plug-in state gets set to active, and that gets done through the set plug-in state call. Administrators can take plug-ins on and offline through the Directory Services control panel. And when they are taken offline or online, it comes through this set plug-in state. And that allows you to either, once you've been made active, to again bring things online that were performally offline, and again take things offline once you become inactive.

Process request. This is where all the heavy lifting gets done. Your plug-in is going to probably do 99% of its data handling through this particular call. This is where you're going to handle, again, all of the lookup information and all of the GET and SAT. Shutdown. This is called just before Directory Services Server Shutdown. Gives your plug-in a chance to clean up, close some files, shut down some network connections.

Configure, we allow all the plug-ins to configure themselves. Again, we don't know what you're going to write. We don't know anything about your plug-in. What happens is, in the directory services control panel, the administrator can select your plug-in and click on the configure button. The server then contacts your plug-in through this API, or this entry point, and then it's up to you. You can configure your app in any way you want. You can simply read a simple XML file, or you can launch an elaborate application with a great HI.

And then periodic task, for those of you who don't want to manage threads, you just want a simple process that gets called when you get called through the entry points, that's great, we'll also call you periodically to do some housekeeping, and this guarantees that you'll get some processor time. Okay, now here's those callbacks that I was talking about before. Right now we have four callbacks. What the plug-ins need to do is they need to register the plug-in.

So they register their nodes, making their nodes or their domains available to the directory server, as well as taking them offline when they've been made inactive, because they will no longer be able to accept, or they will no longer be given any processing requests as long as they're inactive. So this allows the node to bring them on and offline.

Unregister all is convenience called will allow you to take them all offline without having to do them individually. And then there's a log-in callback, which you can put in debugging information. As well as run time information into the directory service log. Okay, just a word to the wise. Remember that your plug-ins are going to be loaded by the directory service server.

The directory service server is running as a root process. Therefore, your plug-in is going to be running as a root process. So you should do all your development as root, and then test as non-root. So you know that it's doing the right thing. It's not giving non-root owners root access and doing bad things in the system that you normally wouldn't do as a non-root owner. Right now, I believe the Directory Services is locked down to read only by administrator, or read everyone, but write only by administrator. I believe that will be the same with Pulse DP4.

Okay, to sum up, what you need to do next is contact your WDR representative if you're interested in doing any directory service development. Please come and talk to us after so we can hopefully get you, we can get you on the contact list for early seeds of the SDK as well as get the copies of the directory service documentation as well as the plugin API documentation. And with that, I'll turn it back to David.

The directory services and other Apple technology, the directory services are really a low-level access technology, they don't necessarily dictate an H.I. or browser or anything like that. So we complement some other Apple technologies. We provide a common framework for higher-level software to be insulated from the particulars of a particular directory service.

One technology that we do complement is Network Service Location, which does have a directory service plug-in under development. So if you do a directory service plug-in, NSL will be able to browse your directory service via its directory service plug-in. So now you don't have to do two plug-ins, one for NSL and one for directory services.

Doing it in one place, the whole system benefits. What are the opportunities for you as developers, because we're all here to make money?

What are some additional resources? We have the Apple Developer Developer Connection. We're going to have our PDFs up there. We have documentation for the API, and we have documentation for the plug-in. We'll be posting those PDFs to Apple Developer Resources. Michael, is the API documentation in the Frameworks subdirectory? It will be in future builds or in wherever documentation goes in Mac OS X.

Directory Service API documentation will be available at the Apple Developer Web site and the API and the headers are installed with DP4. You have the Directory Service Client API. You had it in DP3 if you didn't know it, and you currently have it in DP4. So if you want to play with it, give us some feedback, tell us about some bugs.

We'd love to see anyone playing with the Directory Client API. Who would you contact if you're interested in developing and need Apple's assistance? Thomas Weier is your friend in this particular case. So contact Tom, pester him, tell him that you need access to Davo or Michael, and that you desperately want to develop the world's next greatest plug-in, and you need David's time now. And we'll be happy to work with you.