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."
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.
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) %>
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.
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" ) %>
<% = ils.cna %><p>
<% 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
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.
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
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. |
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
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
To connect with Intel Internet Phone to a specific server
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 %>
<meta http-equiv="Refresh" content="600">
<% else if ils.ittl > 5 then %>
<meta http-equiv="Refresh" content="300">
<% else %>
<meta http-equiv="Refresh" content="100">
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 %>
<% REM Table displaying users goes here. %>
<% 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.
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.
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 = _
"cna=myemailname@mydomain" & _
"&obj=rtperson" & _
"&isec=1000" & _
"&iaddr=" & Request.ServerVariables("REMOTE_ADDR")
%>
<% 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."
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 = _
"cna=myemailname@mydomain" & _
"&modop=0" & _
"&obj=rtperson" & _
"&appid=ms-netmeeting" & _
"&appmime=text/iuls" & _
"&protid=h323" & _
"&protmime=text/h323"
%>
<% 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
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 %>
<% REM Display appropriate error messages. %>
<% = ils.error %>
<% else %>
<% REM Determine if there is a listing to display. %>
<% if (ils.getresult = "WPQR_SUCCESS" ) then %>
Congratulations, <% = ils.gna %>!
Here's your listing.<p>
<% fullname = ils.gna & " " & ils.fna %>
Name: <% = fullname %><p>
Display name: <% = ils.dna %><p>
E-mail address: <% = ils.cna %><p>
<% end if %>
<% end if %>
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 = _
"cna=myemailname@mydomain" & _
"&obj=rtperson"
%>
<% 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.
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:
For example, the following code sets ISEC to the Membership Broker ID number.
<input type=hidden name=ISEC value=<% = Request.ServerVariables("LOGON_USER") %>>
The following code could be used to make sure the same person is modifying or deleting the listing.
<% if Request.ServerVariables("LOGON_USER") = ils.isec then %>
<% REM Code to modify or delete listing %>
<% else %>
You can only delete your own listing.
<% end if %>
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 %>
There are no users online now.
<% end if %>
For complete examples of this, see Chapter 5, "Using the Templates."
The following methods and properties are provided:
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.
Find("parameter_string")
WPQR_SUCCESS if successful, WPQR_ERROR if unsuccessful.
If WPQR_ERROR is returned, use the Error property to retrieve the specific error message.
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. |
If the request is successful, the list of matches is available after a call to the GetResult method.
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")%>
Makes the attribute values available for use in the Active Server Pages script.
GetResult
WPQR_SUCCESS if successful, WPQR_ERROR if unsuccessful.
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.
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 %>
<% = ils.cna %>
<% loop %>
Shows the number of listings found in the database.
TotalHits
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.
WPQR_SUCCESS if successful, WPQR_ERROR if unsuccessful.
If WPQR_ERROR is returned, use the Error property to retrieve the specific error message.
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 %>
<% = ils.cna %><p>
<% loop %>
To display the number of matches, use the following:
<% = ils.TotalHits %>
Adds a listing to the ILS database for a user.
Create("Parameter_string")
WPQR_SUCCESS if successful, WPQR_ERROR if unsuccessful.
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.
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.
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 = _
"cna=myemailname@mydomain" & _
"&obj=rtperson" & _
"&isec=1000" & _
"&iaddr=" & Request.ServerVariables("REMOTE_ADDR")
%>
<% createperson = ils.create(AddInfo) %>
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.
Modify("Parameter_string")
WPQR_SUCCESS if successful, WPQR_ERROR if unsuccessful.
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.
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.
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") %>
Deletes all the listings of the specified user.
Delete("Parameter_string")
WPQR_SUCCESS if successful, WPQR_ERROR if unsuccessful.
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. |
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.
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") %>
If an error has occurred, returns error information.
Error
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). |
Since the ILS ActiveX server component only passes error codes, you should provide a friendly error message for each code.
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 %>
No users are online.
<% Elseif ( ils.Error = "WPQR_REFUSED" ) then %>
You don't have the authority to request this action.
<% Elseif ( ils.Error = "WPQR_MISSING_PARAMETERS" ) then %>
Your request didn't have all the required parameters.
<% Elseif ( ils.Error = "WPQR_BAD_PARAMETERS" ) then %>
Your request was invalid or incorrectly formatted
<% Elseif ( ils.Error = "WPQR_CONNECT_ERROR" ) then %>
Too many users at the moment, please try again later.
<% Elseif ( ils.Error = "WPQR_TIMEOUT" ) then %>
The query could not be completed, either due to heavy load on the server or to the complexity of the query.
<% Elseif ( ils.Error = "WPQR_RESOURCE_ERROR" ) then %>
The network appears to be down now. Please try again later.
<% Elseif (ils.Error = "WPQR_TOO_BROAD" ) then %>
Your query returned too many results. Narrow your query by
adding or changing information on the search form.
<% Elseif ( ils.Error = "WPQR_DUPLICATE" ) then %>
You do not have permission to modify this listing.
<% Elseif ( ils.Error = "WPQR_ERROR" ) then %>
An unspecified error has occurred.
<% End If %>
For complete examples of error messages, see Chapter 5, "Using the Templates."