Previous Page Index Next Page Microsoft Home Page

Return to Start Page

iiiChapter 4 Writing Web Pages to Access ILS Listings

This chapter explains the two ways you might use Internet Locator Server on Web pages: to provide a way to search for people who have already connected to the server using a real-time communication application, or to automatically register people who are visiting your site as being online.

Brief examples are provided as the methods are introduced. Information on complete, working templates can be found in Chapter 5, "Using the Templates."

iiii

Searching for Online Users

To search for online users, you must define the query, execute the query, and display the results.

Searches show users who are added by connecting to the server using a real-time communications application, as well as users who's listings are added by a Web page.

iiiiii

Specifying the Query

Users can search for everyone who is online, or search for specific people based on the specified values for the e-mail address, location, real-time application, and arbitrary attributes.

For all searches, CNA and APPID must be specified, although they can each be set to an asterisk (*). Partial values must have a trailing asterisk (*). In addition, the OBJ attribute must be set to "rtperson."

The query may be defined explicitly, or by an HTML form.

For example, the following query searches for all users who are using Microsoft NetMeeting:

<% ils.find("objtype=rtperson&cna=*&appid=ms-netmeeting") %>

Or, the following example searches for users with e-mail addresses beginning with "Ke" no matter what application they use. In this example, the parameters passed to the Find method are set in a variable:

<% findquery = "objtype=rtperson&cna=Ke*&appid=*"%>

<% ils.find(findquery) %>

You can create a form for the user to use to fill out the name they are looking for:

<form action=ilslist.asp method=post>

<input type=hidden name=objtype value=rtperson>

Enter a name to look for, followed by an asterisk.

<input size=30 name=cna>

<input type=hidden name=appid value="*">

<input type=submit>

</form>

If the user typed Bi*, the form would pass the following query to the page Ilslist.asp:

objtype=rtperson&cna=Bi*&appid=*

The Ilslist.asp would pass this information to the Find method.

<% ils.find(Request.form) %>

iii

Executing the Query

The Find method executes the query and looks up the information in the ILS database.

For example, on the page that receives the post, you would use the following to process the query:

<% ils.find(Request.form) %>

The Find method returns all the matches.

iiiiiii

Displaying the Results

After executing the query, the GetResult method is used to iterate through the list of users returned. For each user, all attributes are returned. An attribute can be retrieved by prefixing it with the variable name you used when you created the instance of the ILS component. If a variable is empty, it returns null.

For example, to display a list of the e-mail addresses of people found, you would use the following code:

<% do while ( ils.GetResult = "WPQR_SUCCESS" ) %>

<% loop %>

The TotalHits property shows how many matches were found.

Because the user list is dynamic, there is no easy way to break up the list of names returned into groups.iiiiii

Providing a Link to Connect to the User

If users have connected to your Web site using the Microsoft NetMeeting or Intel Internet Phone application, you can create a link in the result list that one user can click to connect with another. These links open the application, and initiate a call to the person listed.

There are two methods for creating these links. Each sends the correct information to the browser to start the application and to initiate a connection.

  1. Use Ulserver.dll, provided as part of your ILS installation, to provide the information to the browser. This method works with both Microsoft NetMeeting and Intel Internet Phone, but has the disadvantage that users may see a browser message warning them about downloading a file.
  2. Create an .asp page which provides the information for your browser directly. This method works when your users are either using Microsoft NetMeeting or Intel Internet Phone, but not both.

Important For either type of link to work, the person receiving the call must have the real-time communication application running on their computer. The link will start the application on the initiator's computer.



Note   Neither method works if the online listing is created by a Web page using the ILS server component Create and Modify methods: they can only be used when the listing is created by a person connecting with their real-time communications application. i


Providing a Link Using Ulserver.dll

The Ulserver.dll file is installed in the /Scripts virtual root on your server. The parameters you pass to Ulserver.dll specify how to open the application, and information on the person the user is trying to connect to. In the following example, the user's name will be hot. When clicked, the application specified in ils.appid will initiate a call to the person specified as ils.cna.

<a href="/scripts/ulserver.dll?action=resolve&uid=<% = ils.cna%>&appid=<% = ils.appid %>&protid=<% = ils.protid %>"><% = ils.dnaprot %></a><p>

The complete list of parameters that can be passed to Ulserver.dll are as follows:

Ulserver.dll Parameter and Values

Description

action=directory

Sets the action to Directory.

action=resolve

Sets the action to Resolve User.

uid=e-mail_address

Defines the e-mail address of the user to connect to.

appid=application_identifier

Defines which application to use to connect. Note that both people must have this application running on their system.

Can be ms-netmeeting or x-iphone.

protid=h323

Protocol id. Set to h323 for either Microsoft NetMeeting or Intel Internet Phone.

port=port_number

Port the application is on.

ipaddress=IP_address

Defines the IP address of the user to connect to. Must be in dotted decimal format, xxx.xxx.xxx.xxx. Note that this is not required if both users register themselves as online by using Microsoft NetMeeting or Intel Internet Phone.

i

Connecting Using an ASP Link

A link using an ASP page works the same way, except you pass the parameters to the ASP page, instead of to Ulserver.dll.

In the following example using Microsoft NetMeeting, the ASP page is named Connect.asp. The user's name will be hot. When clicked, the applicatioon will initiate a call to the person specified as ils.cna.

<a href="connect.asp?action=resolve&uid=<% = ils.cna%>&appid=ms-netmeeting&ip=<% = ils.iaddr %>&port=<% = ils.iprt %>">Connect to <%=ils.cna %> using Microsoft NetMeeting</a>

The Connect.asp page must include the following code to start Microsoft NetMeeting, and initiate the call to the person specified in ils.cna.

<% Response.ContentType = "text/iuls" %>

<IULS><

[res]

hr=0

ip=<% = Request("ip") %>

port=<% = Request("port") %>

mt=text/iuls

uid=<% = Request("uid") %>

url=action=resolve;appid=ms-netmeeting;protid=h323;uid=<% = Request("uid") %>

></IULS>

The following example uses Intel Internet Phone.

<p><a href="Connect.asp?action=resolve&uid=<% = ils.cna%>&appid=x-iphone&ip=<% = ils.iaddr %>&port=<% = ils.iprt %>" >Connect to <% = ils.cna %> using Intel Internet Phone</a>

The Connect.asp page must include the following code to start Microsoft NetMeeting, and initiate the call to the person specified in ils.cna.

<% Response.ContentType = "text/h323" %>

[res]

hresult=0

napps=1

ipaddress=<% = Request("ip") %>

portnum=<% = Request("port") %>

appid=

userid=<% = Request("uid") %>

appmime=application/x-iphone

protid=h323

queryurl=action=resolve;userid=<% = Request("uid") %>;protid=h323;ii

Useful Information on Connecting

You may want to provide the following information to your users for how to specify the server name with each real-time application.

To connect with Microsoft NetMeeting to a specific server

  1. On the Tools menu, click Options, and then click the My Information Tab.
  2. In the User Location Service Name box, type the name of your server, with no preceding http:// or backslashes. For example, if the server name is WebServer, the user would type WebServer.

To connect with Intel Internet Phone to a specific server

  1. Click the Options button, and then click User Information.
  2. In the Server Name area, click User Defined, and then type the path to Ulserver.dll on the server. For example, if the server the user is connecting to is called WebServer, the user would type http://WebServer/scripts/ulserver.dll?action=directory.iiii

Refreshing the Search Page

If you want the user to be able to have a page open for a long period of time and automatically see when people come online or leave, you can use the HTML <meta> tag to set the frequency of refresh.

For example, if you want a page with a ten minute time-out, just add the following line at the top of the page:

<meta http-equiv="Refresh" content="600">

You can check the user's ITTL value, the length of time the listing is valid, to find out how often the server refreshes the ILS listing and set the time for the refresh appropriately. Note that ITTL is set in minutes, and the refresh time period is set in seconds. For example:

<% if ils.ittl > 10 then %>

<% else if ils.ittl > 5 then %>

<% else %>

<% end if %>iiiiii

Displaying Listings With More than One Application

If you create listings that include more than one application for a user, or if the user uses two or more applications to connect to a server, displaying the list of results is more complicated. The Find method returns one listing per user and associated application, so if there are two applications, the user would show up twice in the list. As a result, TotalHits is the number of users and associated applications, so is greater than just the number of users. You need to use scripting to present just one listing for each user, and either display the correct total or don't display the number of users found.

Depending on your search criteria, you may be able to get an accurate number of users by doing two calls to Find. For the first call, don't specify any APPID value and display the value of TotalHits. For the second, specify the APPID, but don't display TotalHits.

For example, to find everyone:

<% ils.find("obj=rtperson&cna=*") %>

There are <% = ils.TotalHits %> users online now.

<% ils.find("obj=rtperson&cna=*&appid=*") %>

<% do while ils.GetResult = TRUE %>

<% loop %>

The templates described in Chapter 5, "Using the Templates," provide working examples of presenting only one table row for each user, no matter how many applications they have.

iiiiiiii

Registering a User as Online

To register a user online, the Web page adds a listing for the user, and then for each application the user has available, modifies the listing to add the application information.

The methods described in this section should only be used if you are using a Web page to register users as online, rather than having the application itself do the registration.

iiiiiiiii

Adding a Listing for the User

To add a listing for a user, the Create method is used. You must specify the user's e-mail name, security token, and IP address. You can also specify a variety of other tags to be included in their listing. (For a complete list of tags that can be added, see Chapter 2, "The ILS Database.")

For example, the AddInfo string below is used to assemble the minimum parameters for the Create method. The IP address is taken from the HTTP header.

<% AddInfo = _

<% createperson = ils.create(AddInfo) %>

Note that there are many ways to collect the information for the listing: you can provide an HTML form for the user to fill out, you can read the information from a database such as the Personalization System User Property Database, or you can read the information from another database.

For complete examples of the forms used to collect information and display it for modifying, see Chapter 5, "Using the Templates."

iiiiiiii

Modifying the Listing

Once the basic listing for a person is added, it must be modified to add applications for the user. The Modify method is used to do several types of modification: adding an application, deleting an application, changing user information, and changing application information. The type of modification must be specified by using the Modop tag. All Modify calls require the CNA of the listing to modify.

For example, the following could be used to add the application Microsoft NetMeeting to an existing online user. NMInfo is used as a variable to assemble the minimum parameters for the Modify method when it is being used to add an application.

<% NMInfo = _

%>

<% modifyperson = ils.modify(NMInfo) %>

One easy way to do this is to pass the same ISEC value used to add the user, and compare it against the one in the listing. No severity checking is done by ILS. If you want security, your script must include it.iiiii

Displaying the Listing After It Is Created

When the online listing is complete after adding the user and the application, you can display the listing to the user for review using the GetResult method. The Response.Expires command is used to make sure the page is refreshed each time it is accessed, so that the newest listing is always displayed.

For example, the following code congratulates the user after successful creation of a listing, and displays the user's full name, display name, e-mail address, and home page.

<% Response.Expires=0 %>

<% REM Previous line makes sure newest version of listing is used. %>

<% set ils=Server.CreateObject("ms.ils") %>

<% if (ils.create(request.form) <> "WPQR_SUCCESS" ) then %>

<% else %>

<% end if %>

iiiiii

Deleting the Listing

To delete a listing for a user, the Delete method is used. You must specify the user's e-mail name.

Note that listings also are deleted when they expire. The time of expiration of a listing is determined by the ITTL tag used to create the listing, or, if not specified, by the default LDAP property, Time To Live.

For example, the following DeleteInfo string is used to assemble the minimum parameters for the Delete method:

<% DeleteInfo = _

<% deleteperson = ils.delete(DeleteInfo) %>

No security checking is done by ILS. If you want security, your script must include it. One easy way to do this is to pass the same ISEC value used to add the user and compare it against the one in the listing.

iiiiiiiiiiiiii

Authenticating the User

In order to protect online listings from being modified or deleted by anyone other than their owner, you should authenticate the user before allowing modification or deletion of the record. This authentication is done at the script level, because there are several types of authentication environments ILS can be used in.

In all authentication environments, ILS handles authentication based on the value of the ISEC attribute.

The four common types of authentication environments are:

  1. A non-authenticated environment. For example, an external Web site that is available to anyone. In a non-authenticated environment, there is no way to generate a unique ISEC for the user. If you have pages that explicitly add, modify and delete listings, you may want to protect them with a password-protected cover page.
  2. A Personalization System environment. For example, an external Web site that is available to anyone, but uses the Personalization System to recognize returning users. In this environment, you could verify that the Personalization System ID the user uses to modify or delete a listing is the same as the Personalization System ID that was used to create the listing.
  3. A Membership Broker-authenticated environment. For example, an ISP Web site with some information available to authorized users, and other information available to all users. In a Membership Broker-authenticated environment, you can find out the user's Membership Broker ID when they get to the page, and use it as the ISEC field in the ILS database. If they match, the user should be allowed to modify or delete the listing.
  1. An NTLM-authenticated environment. For example, a corporate intranet, where permissions are based on the user's NTLM permissions.

iiii

Error Handling

The Error property provides the specific error codes that may appear.

For example, you can use this method to provide friendly messages when problems occur:

<% if ( ils.Error = "WPQR_NO_MATCH" ) then %>

<% end if %>

For complete examples of this, see Chapter 5, "Using the Templates."

iiii

Methods

The following methods and properties are provided:

iii

Find

Searches for users with entries matching the value of the e-mail name passed in the query string, and prepares those entries to be passed back to the script.

Syntax

Find("parameter_string")

Returns

WPQR_SUCCESS if successful, WPQR_ERROR if unsuccessful.

If WPQR_ERROR is returned, use the Error property to retrieve the specific error message.

Settings

Parameter_string must include the following parameters:

Mandatory Parameters and Valid Settings

Description

OBJ=rtperson

Specifies that the search is for people who are online.

CNA=e-mail_address

Users with this exact e-mail address.

CNA=partial_e-mail_address*

Users with an e-mail name beginning with this partial e-mail address.

CNA=*

All users.

APPID=application_ID

Application user must be running in order to show up in the search results.

APPID=*

Users running any application.

Parameter_string may also include the following parameters:

Optional Parameters and Valid Settings

Description

MAXREQ=n

Displays only the top n users matched. The default is to return all the users matched up to the number set in the Entries tab of the LDAP service properties. Setting MAXREQ=0 is equivalent to not using the MAXREQ attribute:

LOCATION=location

Users with this exact location.

LOCATION=partial_location*

Users with locations beginning with this partial location.

ILSTn=value

Users with arbitrary attribute set to specified value.

ILSTn=partial_value*

Users with arbitrary attribute set to a value that begins with this partial value.

Remarks

If the request is successful, the list of matches is available after a call to the GetResult method.

Examples

To pass the parameter string from a form to the Request statement:

<% ils.Find(Request.Form)%>

Or, to explicitly find everyone online:

<% ils.Find("cna=*&obj=rtperson&appid=*")%>

Or, to explicitly find all users who have ILST9 set to "travel":

<% ils.Find("cna=*&obj=rtperson&appid=*&ilst9=travel")%>

iiii

GetResult

Makes the attribute values available for use in the Active Server Pages script.

Syntax

GetResult

Returns

WPQR_SUCCESS if successful, WPQR_ERROR if unsuccessful.

Remarks

After calling any of the methods that prepare values from the database, (Create, Modify, or Find) you must call GetResult to make the results available to your script file in the query string.

If WPQR_ERROR is returned, use the Error property to retrieve the specific error message.

Examples

After creating a listing, use the following line to make the attribute values available for use in the Active Server Pages script:

<% ils.GetResult %>

After searching for users, you need to iterate through the list of users returned:

<% do while ils.GetResult = TRUE %>

<% loop %>

iiii

TotalHits

Shows the number of listings found in the database.

Syntax

TotalHits

Settings

Maxreq is set to 0 to allow the maximum number of results to be displayed. If you want to limit the number of results displayed, set Maxreq to the maximum number that should be displayed.

Returns

WPQR_SUCCESS if successful, WPQR_ERROR if unsuccessful.

If WPQR_ERROR is returned, use the Error property to retrieve the specific error message.

Remarks

If the Find that TotalHits is based on includes the APPID parameter, and if user has multiple applications, there will be multiple listings for that user, causing the number returned by TotalHits to be higher than the actual number of users found.

Depending on your search criteria, you may be able to get an accurate number of users by doing two calls to Find. For the first call, don't specify any APPID parameter and display the value of TotalHits. For the second, specify the APPID, but don't display TotalHits.

For example, to find everyone:

<% ils.find("obj=rtperson&cna=*") %>

There are <% = ils.TotalHits %> users online now.

<% ils.find("obj=rtperson&cna=*&appid=*") %>

<% do while ils.GetResult = TRUE %>

<% loop %>

Examples

To display the number of matches, use the following:

<% = ils.TotalHits %>

iiii

Create

Adds a listing to the ILS database for a user.

Syntax

Create("Parameter_string")

Returns

WPQR_SUCCESS if successful, WPQR_ERROR if unsuccessful.

Settings

Parameter_string is a string containing the attributes that make up the user's listing. Parameter_string must include the following attributes.

Mandatory Parameters and Valid Settings

Description

OBJ=rtperson

Specifies that the search is for people who are online.

CNA=e-mail_address

User's e-mail address.

ISEC=security_token

Security token for user. Must be a 32-bit dword.

IADDR=ip_address

IP address for the user's computer. This must be entered as a dotted decimal, xxx.xxx.xxx.xxx. This information typically comes from Request.ServerVariables("REMOTE_ADDR").

In addition, any of the user attributes listed in Chapter 2, "The ILS Database" can be included in the parameter string.

Remarks

If successful, the created listing is available after a call to the GetResult method.

If WPQR_ERROR is returned, use the Error property to retrieve the specific error message.

Examples

To create a listing based on the information passed to the page by an HTML form:

<% ils.create(Request.form) %>

Or, to explicitly pass the minimum parameters for the Create method, you can assemble the parameter string and then pass it in. The IP address is taken from the HTTP header.

<% AddInfo = _

<% createperson = ils.create(AddInfo) %>

iiiiiii

Modify

Changes the information associated with a given listing, including adding an application to a listing, modifying user information, modifying application information, or deleting an application.

Syntax

Modify("Parameter_string")

Returns

WPQR_SUCCESS if successful, WPQR_ERROR if unsuccessful.

Settings

Parameter_string is a string containing the attributes that make up the user's listing. The attributes must be separated by an ampersand (&).

The following parameters are mandatory for all values of Modop:

Mandatory Parameters and Valid Settings

Description

OBJ=rtperson

Specifies that the search is for people who are online.

CNA=e-mail_address

User's e-mail address.

MODOP=n

Type of modification being done:

0 Adds an application to an existing user.

1 Deletes an application from an existing user.

2 Changes user information for an existing user.

3 Changes application information for an existing user.

If Modop is set to 0 , the following parameters are also mandatory for Modify:

Mandatory Parameters and Valid Settings

Description

APPID=application_ID

Application identifier.

ms-netmeeting Application identifier for Microsoft NetMeeting.

x-iphone Application identifier for Intel Internet Phone.

APPMIME=mime_type

MIME type for the application.

text/iuls Application MIME-type for Microsoft NetMeeting.

text/iuls Application MIME-type for Intel Internet Phone.

PROTID=protocol

Protocol ID for the application.

h323 Protocol ID for Microsoft NetMeeting.

h323 Protocol ID for Intel Internet Phone.

PROTMIME=mime_type

Protocol MIME-type for the application.

text/h323 Protocol MIME-type for Microsoft NetMeeting.

text/h323 Protocol MIME-type for Intel Internet Phone.

If Modop is set to 3 , the following parameters are also mandatory for Modify:

Mandatory Parameters and Valid Settings

Description



APPID=application_ID

Application identifier.

ms-netmeeting Application identifier for Microsoft NetMeeting.

x-iphone Application identifier for Intel Internet Phone.

If Modop is set to 2, any of the user attributes listed in Chapter 2, "The ILS Database" can be included in the parameter string.

If Modop is set to 2 or 3, if a previously set attribute is not included as a parameter, the existing value is used. You must explicitly set an attribute to null to remove it.

Remarks

If successful, the modified listing is available after a call to the GetResult method.

If WPQR_ERROR is returned, use the Error property to retrieve the specific error message.

Examples

To modify a listing based on the information passed to the page by an HTML form:

<% ils.modify(Request.form) %>

To add an application to a user named Kim@xyz.com:

<% ils.modify("obj=rtperson&cna=kim@xyz.com&modop=0&appid=ms-NetMeeting&protid=h323&appmime=text/iuls&protmime=text/h323") %>

iii

Delete

Deletes all the listings of the specified user.

Syntax

Delete("Parameter_string")

Returns

WPQR_SUCCESS if successful, WPQR_ERROR if unsuccessful.

Settings

Parameter_string must include the following:

Mandatory Parameters and Valid Settings

Description

OBJ=rtperson

Specifies that the search is for people who are online.

CNA=e-mail_address

User's e-mail address.

Remarks

If WPQR_ERROR is returned, use the Error property to retrieve the specific error message.

To delete an application from a user, use the Modify method.

Examples

To delete a listing based on the information passed to the page by an HTML form:

<% ils.delete(Request.form) %>

To delete a listing explicitly:

<% ils.delete("cna=myemailname@here.com&obj=rtperson") %>

iii

Error

If an error has occurred, returns error information.

Syntax

Error

Returns

The following tables describe the error codes returned from the Error property.

These error codes might result from any method.

Generic Error Code

Description

WPQR_SUCCESS

The requested command completed successfully.

WPQR_BAD_PARAMETERS

The parameters passed to the last command were invalid or poorly formatted.

WPQR_MISSING_PARAMETERS

Required parameters for the function were missing.

WPQR_RESOURCE_ERROR

System was unable to allocate a required resource.

WPQR_CONNECT_ERROR

System was unable to connect to a required resource.

WPQR_TIMEOUT

Request took too long to process. The value for the time-out length is set on the Service tab of the LDAP service properties in Internet Service Manager. The default is 600 seconds.

WPQR_ERROR

Unspecified operation error.

The following error codes are used by the Create, Modify and Delete methods.

Error Code

Description

WPQR_REFUSED

(Modify and Delete only) The requesting agent does not have the authority to request this command.

WPQR_NO_MATCH

(Modify only) The record to be modified was not found.

(Delete only) The record to be deleted was not found.

WPQR_DUPLICATE

(Create and Modify only) A duplicate listing already exists in the database. Note that this implies that a listing already exists for this user, but with a different security token, so the error message you display should tell people that they don't have permission to update this listing.

The following error codes are used by the Find method.

Error Code

Description

WPQR_NO_MATCH

The query did not result in any matches.

WPQR_TOO_BROAD

The query had too many matches (more than the number of hits specified in the LDAP service properties in Internet Service Manager).

Remarks

Since the ILS ActiveX server component only passes error codes, you should provide a friendly error message for each code.

Examples

The following line shows how you can return the error code.

<% = ils.error %>

The following example shows how you can provide a detailed error message for each error code.

<% if ( ils.Error = "WPQR_NO_MATCH" ) then %>

<% Elseif ( ils.Error = "WPQR_REFUSED" ) then %>

<% Elseif ( ils.Error = "WPQR_MISSING_PARAMETERS" ) then %>

<% Elseif ( ils.Error = "WPQR_BAD_PARAMETERS" ) then %>

<% Elseif ( ils.Error = "WPQR_CONNECT_ERROR" ) then %>

<% Elseif ( ils.Error = "WPQR_TIMEOUT" ) then %>

<% Elseif ( ils.Error = "WPQR_RESOURCE_ERROR" ) then %>

<% Elseif (ils.Error = "WPQR_TOO_BROAD" ) then %>

<% Elseif ( ils.Error = "WPQR_DUPLICATE" ) then %>

<% Elseif ( ils.Error = "WPQR_ERROR" ) then %>

<% End If %>

For complete examples of error messages, see Chapter 5, "Using the Templates."

Previous Page Index Next Page Microsoft Home Page

Return to Start Page


© 1996-1997 Microsoft Corporation. All rights reserved.