";
	$ds = pla_ldap_connect( $server_id );
	if( ! $ds )
		return false;

	$search = @ldap_read( $ds, $dn, 'objectClass=*', array( 'subschemaSubentry' ) );
	if( $debug ) { echo "Search result (ldap_read): "; var_dump( $search ); echo "\n"; }
	if( ! $search ) {
		if( $debug ) echo "_get_schema_dn() returning false. (search val is false)\n";
		return false;
	}

	if( ldap_count_entries( $ds, $search ) == 0 ) {
		if( $debug ) echo "_get_schema_dn() returning false (ldap_count_entries() == 0).\n";
		return false;
	}

	$entries = @ldap_get_entries( $ds, $search );
	if( $debug ) { echo "Entries (ldap_get_entries): "; var_dump( $entries ); echo "\n"; }
	if( ! $entries || ! is_array( $entries ) ) {
		if( $debug ) echo "_get_schema_dn() returning false (Bad entries val, false or not array).\n";
		return false;
	}

	$entry = isset( $entries[0] ) ? $entries[0] : false;
	if( ! $entry ) {
		if( $debug ) echo "_get_schema_dn() returning false (entry val is false)\n";
		return false;
	}

	$sub_schema_sub_entry = isset( $entry[0] ) ? $entry[0] : false;
	if( ! $sub_schema_sub_entry ) {
		if( $debug ) echo "_get_schema_dn() returning false (sub_schema_sub_entry val is false)\n";
		return false;
	}

	$schema_dn = isset( $entry[ $sub_schema_sub_entry ][0] ) ?
					$entry[ $sub_schema_sub_entry ][0] :
					false;

	if( $debug ) echo "_get_schema_dn() returning: \"" . $schema_dn . "\"\n";
	return $schema_dn;
}

/*
 * Fetches the raw schema array for the subschemaSubentry of the server. Note,
 * this function has grown many hairs to accomodate more LDAP servers. It is
 * needfully complicated. If you can find a better way to write it, feel free!
 *
 * @param $server_id - The server ID whose server you want to retrieve
 * @param $schema_to_fetch - A string indicating which type of schema to 
 *		fetch. Five valid values: 'objectclasses', 'attributetypes', 
 *		'ldapsyntaxes', 'matchingruleuse', or 'matchingrules'. 
 *		Case insensitive.
 * @param $dn (optional) This paremeter is the DN of the entry whose schema you
 * 		would like to fetch. Entries have the option of specifying
 * 		their own subschemaSubentry that points to the DN of the system
 * 		schema entry which applies to this attribute. If unspecified,
 *		this will try to retrieve the schema from the RootDSE subschemaSubentry.
 *		Failing that, we use some commonly known schema DNs. Default 
 *		value is the Root DSE DN (zero-length string)
 * @return an array of strings of this form:
 *    Array (
 *      [0] => "( 1.3.6.1.4.1.7165.1.2.2.4 NAME 'gidPool' DESC 'Pool ...
 *      [1] => "( 1.3.6.1.4.1.7165.2.2.3 NAME 'sambaAccount' DESC 'Sa ...
 *      etc.
 */
function _get_raw_schema( $server_id, $schema_to_fetch, $dn='' )
{
	global $lang;
	static $cache = null;

	// Swith to true to enable verbose output of schema fetching progress
	$debug = false;

	$ds = pla_ldap_connect( $server_id );
	if( ! $ds )
		return false;

	// error checking
	$schema_to_fetch = strtolower( $schema_to_fetch );
	$valid_schema_to_fetch = array( 'objectclasses', 'attributetypes', 'ldapsyntaxes', 
					'matchingrules', 'matchingruleuse'  );
	if( ! in_array( $schema_to_fetch, $valid_schema_to_fetch ) )
		pla_error( "Bad parameter provided to function to _get_raw_schema(). '" 
				. htmlspecialchars( $schema_to_fetch ) . "' is 
				not valid for the schema_to_fetch parameter." );
	
	// Minimize the hits to LDAP server by caching the result
	if( isset( $cache[ $server_id ][ $schema_to_fetch ] ) )
		return $cache[ $server_id ][ $schema_to_fetch ];

	// Try to get the schema DN from the specified entry. 
	$schema_dn = _get_schema_dn( $server_id, $dn, $debug );

	// Do we need to try again with the Root DSE?
	if( ! $schema_dn )
		$schema_dn = _get_schema_dn( $server_id, '', $debug );

	// Store the eventual schema retrieval in $schema_search
	$schema_search = null;

	if( $schema_dn ) {
		if( $debug ) { echo "Found the schema DN: "; var_dump( $schema_dn ); echo "\n"; }
		$schema_search = @ldap_read( $ds, $schema_dn, '(objectClass=*)',
							array( $schema_to_fetch ), 0, 0, 0, 
							LDAP_DEREF_ALWAYS );
		if( $schema_search === false ) {
			if( $debug ) echo "Did not find the schema at DN: $schema_dn.\n";
			$schema_search = null;
			unset( $schema_dn );
		} else {
			if( $debug ) echo "Found the schema at DN: $schema_dn.\n";
		}
	} 

	// Second chance: If the DN or Root DSE didn't give us the subschemaSubentry, ie $schema_search
	// is still null, use some common subSchemaSubentry DNs as a work-around.

	if( $debug && $schema_search == null )
		echo "Attempting work-arounds for 'broken' LDAP servers...\n";

	// cn=subschema for OpenLDAP
	if( $schema_search == null ) {
		if( $debug ) echo "Attempting with cn=subschema (OpenLDAP)...\n";
		// try with the standard DN
		$schema_search = @ldap_read($ds, 'cn=subschema', '(objectClass=*)',
				array( $schema_to_fetch ), 0, 0, 0, LDAP_DEREF_ALWAYS );
	}

	// cn=schema for Novell eDirectory
	if( $schema_search == null ) {
		if( $debug ) echo "Attempting with cn=schema (Novell)...\n";
		// try again, with a different schema DN
		$schema_search = @ldap_read($ds, 'cn=schema', '(objectClass=*)',
				array( $schema_to_fetch ), 0, 0, 0, LDAP_DEREF_ALWAYS );
	}

	// cn=schema,cn=configuration,dc=example,dc=com for ActiveDirectory
	if( $schema_search == null ) {
		// try again, with a different schema DN
		global $servers;
		$base_dn = isset( $servers[ $server_id ][ 'base' ] ) ?
				$servers[ $server_id ][ 'base' ] :
				null;
		if( $debug ) echo "Attempting with cn=schema,cn=configuration,$base_dn (ActiveDirectory)...\n";
		if( $base_dn != null )
			$schema_search = @ldap_read($ds, 'cn=schema,cn=configuration,' . $base_dn, '(objectClass=*)',
				array( $schema_to_fetch ), 0, 0, 0, LDAP_DEREF_ALWAYS );
	}

	// cn=Schema,ou=Admin,dc=example,dc=com for SiteServer
	if( $schema_search == null ) {
		// try again, with a different schema DN
		global $servers;
		$base_dn = isset( $servers[ $server_id ][ 'base' ] ) ?
				$servers[ $server_id ][ 'base' ] :
				null;
		if( $debug ) echo "Attempting with cn=Schema,ou=Admin,$base_dn (ActiveDirectory)...\n";
		if( $base_dn != null )
			$schema_search = @ldap_read($ds, 'cn=Schema,ou=Admin,' . $base_dn, '(objectClass=*)',
				array( $schema_to_fetch ), 0, 0, 0, LDAP_DEREF_ALWAYS );
	}

	// Shall we just give up?
	if( $schema_search == null ) 
		return false;

	// Did we get something unrecognizable?
	if( 'resource' != gettype( $schema_search ) ) {
		if( $debug ) "Returning false since schema_esarch is not of type 'resource'\n";
		return false;
	}
	
	$schema = @ldap_get_entries( $ds, $schema_search );
	if( $schema == false ) {
		if( $debug ) "Returning false since ldap_get_entries() returned false.\n";
		return false;
	}

	// Make a nice array of this form:
	// Array (
	//    [0] => "( 1.3.6.1.4.1.7165.1.2.2.4 NAME 'gidPool' DESC 'Pool ...
	//    [1] => "( 1.3.6.1.4.1.7165.2.2.3 NAME 'sambaAccount' DESC 'Sa ...
	//    etc.
	if( ! isset( $schema[0][$schema_to_fetch] ) ) {
		if( $debug ) "Returning false since '$schema_to_fetch' isn't in the schema array\n";
		return false;
	}

	$schema = $schema[0][$schema_to_fetch];
	unset( $schema['count'] );

	// Store the results in cache for subsequent calls
	$cache[ $server_id ][ $schema_to_fetch ] = $schema;

	return $schema;
}

/* 
 * Returns an associative array of objectClasses for the specified 
 * $server_id. Each array entry's key is the name of the objectClass
 * in lower-case. 
 * The sub-entries consist of sub-arrays called 'must_attrs' and 
 * 'may_attrs', and sub-entries called 'oid', 'name' and 'description'.
 */
function get_schema_objectclasses( $server_id, $dn=null )
{
	// cache the schema to prevent multiple schema fetches from LDAP server
	static $cache = array();
	if( isset( $cache[$server_id] ) ) {
		//echo "Using oclass cache.
";
		return $cache[$server_id];
	}

	$raw_oclasses = _get_raw_schema( $server_id, 'objectclasses', $dn );
	if( ! $raw_oclasses )
		return false;

	// build the array of objectClasses
	$object_classes = array();
	foreach( $raw_oclasses as $class_string  ) {
		if( $class_string == null || 0 == strlen( $class_string ) )
			continue;
		$object_class = new ObjectClass( $class_string );
		$name = $object_class->getName();
		$key = strtolower( $name );
		$object_classes[ $key ] = $object_class;
	}

	ksort( $object_classes );

	// cache the schema to prevent multiple schema fetches from LDAP server
	$cache[ $server_id ] = $object_classes;
	return( $object_classes );
}

/*
 * Returns the schema for a single ObjectClass
 */
function get_schema_objectclass( $server_id, $oclass_name, $dn=null )
{
	$oclass_name = strtolower( $oclass_name );
	$oclasses = get_schema_objectclasses( $server_id, $dn );
	if( ! $oclasses )
		return false;
	if( isset( $oclasses[ $oclass_name ] ) )
		return $oclasses[ $oclass_name ];
	else
		return false;
}

/*
 * Retrieves the schema for a single attribute.
 */
function get_schema_attribute( $server_id, $attr_name, $dn=null ) 
{
	$attr_name = real_attr_name( $attr_name );
	$schema_attrs = get_schema_attributes( $server_id, $dn );
	$attr_name = strtolower( $attr_name );
	$schema_attr = isset( $schema_attrs[ $attr_name ] ) ?
				$schema_attrs[ $attr_name ] :
				false;
	return $schema_attr;
}

/* 
 * Returns an array of AttributeType objects for the specified 
 * $server_id. Each array entry's key is the name of the attribute,
 * in lower-case.
 */
function get_schema_attributes( $server_id, $dn = null )
{
	// Cache gets filled in later (bottom). each subsequent call uses
	// the cache which has the attributes already fetched and parsed
	static $cache = null;
	if( isset( $cache[ $server_id ] ) )
		return $cache[ $server_id ];

	$raw_attrs = _get_raw_schema( $server_id, 'attributeTypes', $dn );
	if( ! $raw_attrs )
		return false;
	
	// build the array of attribueTypes
	$syntaxes = get_schema_syntaxes( $server_id, $dn );
	$attrs = array();
	/* 
     * bug 856832: create two arrays - one indexed by name (the standard
	 * $attrs array above) and one indexed by oid (the new $attrs_oid array
	 * below). This will help for directory servers, like IBM's, that use OIDs
	 * in their attribute definitions of SUP, etc
	 */
	$attrs_oid = array();
	foreach( $raw_attrs as $attr_string ) {
		if( $attr_string == null || 0 == strlen( $attr_string ) )
			continue;
		$attr = new AttributeType( $attr_string );
		if( isset( $syntaxes[ $attr->getSyntaxOID() ] ) ) {
			$syntax = $syntaxes[ $attr->getSyntaxOID() ];
			$attr->setType( $syntax->getDescription() );
		}
		$name = $attr->getName();
		$key = strtolower( $name );
		$attrs[ $key ] = $attr;
		
		/* 
		 * bug 856832: create an entry in the $attrs_oid array too. This
		 * will be a ref to the $attrs entry for maintenance and performance
		 * reasons 
		 */
		$oid = $attr->getOID();
		$attrs_oid[ $oid ] = &$attrs[ $key ];
	}

	add_aliases_to_attrs( $attrs );
	/* 
	 * bug 856832: pass the $attrs_oid array as a second (new) parameter
	 * to add_sup_to_attrs. This will allow lookups by either name or oid.
	 */
	add_sup_to_attrs( $attrs, $attrs_oid );

	ksort( $attrs );

	// cache the schema to prevent multiple schema fetches from LDAP server
	$cache[ $server_id ] = $attrs;
	return( $attrs );
}

/*
 * For each attribute that has multiple names, this function adds unique entries to 
 * the attrs array for those names. Ie, attributeType has name 'gn' and 'givenName'.
 * This function will create a unique entry for 'gn' and 'givenName'.
 */
function add_aliases_to_attrs( &$attrs )
{
	// go back and add data from aliased attributeTypes
	foreach( $attrs as $name => $attr ) {
		$aliases = $attr->getAliases();
		if( is_array( $aliases ) &&  count( $aliases ) > 0 ) {
			// foreach of the attribute's aliases, create a new entry in the attrs array
			// with its name set to the alias name, and all other data copied
			foreach( $aliases as $alias_attr_name ) {
				$new_attr = $attr;
				$new_attr->setName( $alias_attr_name );
				$new_attr->addAlias( $attr->getName() );
				$new_attr->removeAlias( $alias_attr_name );
				$new_attr_key = strtolower( $alias_attr_name );
				$attrs[ $new_attr_key ] = $new_attr;
			}
		}
	}
}

/*
 * Adds inherited values to each attributeType specified by the SUP directive. 
 * Supports infinite levels of inheritance.
 * Bug 856832: require a second paramter that has all attributes indexed by OID
 */
function add_sup_to_attrs( &$attrs, &$attrs_oid )
{
	$debug = false;
	if( $debug ) echo "
";

	if( $debug ) print_r( $attrs );
	
	// go back and add any inherited descriptions from parent attributes (ie, cn inherits name)
	foreach( $attrs as $key => $attr ) {
		if( $debug ) echo "Analyzing inheritance for attribute '" . $attr->getName() . "'\n";
		$sup_attr_name = $attr->getSupAttribute();
		$sup_attr = null;

		// Does this attribute have any inheritance happening here?
		if( null != trim( $sup_attr_name ) ) {

			// This loop really should traverse infinite levels of inheritance (SUP) for attributeTypes,
			// but just in case we get carried away, stop at 100. This shouldn't happen, but for
			// some weird reason, we have had someone report that it has happened. Oh well.
			$i = 0;
			while( $i++ < 100 /* 100 == INFINITY ;) */ ) {
				if( $debug ) echo "Top of loop.\n";

				/*
				 * Bug 856832: check if sup is indexed by OID. If it is,
				 * replace the OID with the appropriate name. Then reset
				 * $sup_attr_name to the name instead of the OID. This will
				 * make all the remaining code in this function work as
				 * expected.
				 */
				if( isset( $attrs_oid[$sup_attr_name] ) ) {
					$attr->setSupAttribute( $attrs_oid[$sup_attr_name]->getName() );
					$sup_attr_name = $attr->getSupAttribute();
				}
				
				if( ! isset( $attrs[ strtolower( $sup_attr_name ) ] ) ){ 
					pla_error( "Schema error: attributeType '" . $attr->getName() . "' inherits from 
								'" . $sup_attr_name . "', but attributeType '" . $sup_attr_name . "' does not
								exist." );
						return;
				}

				if( $debug ) echo " sup_attr_name: $sup_attr_name\n";
				$sup_attr = $attrs[ strtolower( $sup_attr_name ) ];
				if( $debug ) echo " Sup attr: " . $sup_attr->getName() . "\n";

				$sup_attr_name = $sup_attr->getSupAttribute();
				if( $debug ) echo " Does the sup attr itself have a sup attr?\n";

				// Does this superior attributeType not have a superior attributeType?
				if( null == $sup_attr_name || strlen( trim( $sup_attr_name ) ) == 0 ) {

					// Since this attribute's superior attribute does not have another superior
					// attribute, clone its properties for this attribute. Then, replace
					// those cloned values with those that can be explicitly set by the child
					// attribute attr). Save those few properties which the child can set here:
					if( $debug ) echo "  nope, this is the end of the inheritance chain after $i iterations.\n";
					$tmp_name = $attr->getName();
					$tmp_oid = $attr->getOID();
					$tmp_sup = $attr->getSupAttribute();
					$tmp_aliases = $attr->getAliases();
					$tmp_single_val = $attr->getIsSingleValue();


					if( $debug ) {
						echo "  populating values into attribute from sup attribute:\n";
						echo "Before: ";
						print_r( $attr );
					}

					// clone the SUP attributeType and populate those values
					// that were set by the child attributeType
					$attr = $sup_attr;
					$attr->setOID( $tmp_oid );
					$attr->setName( $tmp_name );
					$attr->setSupAttribute( $tmp_sup);
					$attr->setAliases( $tmp_aliases );

					if( $debug ) {
						echo "After (name, sup_attr, and aliases should not have changed!: ";
						print_r( $attr );
					}
					// only overwrite the SINGLE-VALUE property if the child explicitly sets it
					// (note: All LDAP attributes default to multi-value if not explicitly set SINGLE-VALUE)
					if( true == $tmp_single_val )
						$attr->setIsSingleValue( true );

					// replace this attribute in the attrs array now that we have populated
					// new values therein
					$attrs[$key] = $attr;

					// very important: break out after we are done with this attribute
					$sup_attr_name = null;
					$sup_attr = null;
					break;

				} else {

					// do nothing, move on down the chain of inheritance...
					if( $debug ) echo "  yup, march down the inheritance chain (iteration $i).\n";
					if( $debug ) { echo "  The sup attr is: "; var_dump( $sup_attr_name ); echo "\n"; }

				}
			}
		}
	}

	if( $debug ) echo "
\n";
}

/* 
 * Returns an array of MatchingRule objects for the specified server.
 * The key of each entry is the OID of the matching rule.
 */
function get_schema_matching_rules( $server_id, $dn=null )
{
	static $cache;

	// cache the schema to prevent multiple schema fetches from LDAP server
	if( isset( $cache[$server_id] ) ) {
		return $cache[$server_id];
	}

	// build the array of MatchingRule objects
	$raw_matching_rules = _get_raw_schema( $server_id, 'matchingRules', $dn );
	if( ! $raw_matching_rules )
		return false;
	$rules = array();
	foreach( $raw_matching_rules as $rule_string ) {
		if( $rule_string == null || 0 == strlen( $rule_string ) )
			continue;
		$rule = new MatchingRule( $rule_string );
		$key = strtolower( $rule->getName() );
		$rules[ $key ] = $rule;
	}

	ksort( $rules );

	// For each MatchingRuleUse entry, add the attributes who use it to the
	// MatchingRule in the $rules array.
	$raw_matching_rule_use = _get_raw_schema( $server_id, 'matchingRuleUse' );
	if( $raw_matching_rule_use != false ) {
		foreach( $raw_matching_rule_use as $rule_use_string ) {
			if( $rule_use_string == null || 0 == strlen( $rule_use_string ) )
				continue;
			$rule_use = new MatchingRuleUse( $rule_use_string );
			$key = strtolower( $rule_use->getName() );
			if( isset( $rules[ $key ] ) )
				$rules[ $key ]->setUsedByAttrs( $rule_use->getUsedByAttrs() );
		}
	} else {
		// No MatchingRuleUse entry in the subschema, so brute-forcing
		// the reverse-map for the "$rule->getUsedByAttrs()" data.
		$attrs = get_schema_attributes( $server_id, $dn );
		if( is_array( $attrs ) )
			foreach( $attrs as $attr ) {
				$rule_key = strtolower( $attr->getEquality() );
				if( isset( $rules[ $rule_key ] ) )
					$rules[ $rule_key ]->addUsedByAttr( $attr->getName() );
			}
	}

	// cache the schema to prevent multiple schema fetches from LDAP server
	$cache[$server_id] = $rules;
	return $rules;
}

/* 
 * Returns an array of Syntax objects that this LDAP server uses mapped to
 * their descriptions. The key of each entry is the OID of the Syntax.
 */
function get_schema_syntaxes( $server_id, $dn=null )
{
	static $cache;

	// cache the schema to prevent multiple schema fetches from LDAP server
	if( isset( $cache[$server_id] ) ) {
		return $cache[$server_id];
	}

	$raw_syntaxes = _get_raw_schema( $server_id, 'ldapSyntaxes', $dn );
	if( ! $raw_syntaxes )
		return false;

	// build the array of attributes
	$syntaxes = array();
	foreach( $raw_syntaxes as $syntax_string ) {
		$syntax = new Syntax( $syntax_string );
		$key = strtolower( trim( $syntax->getOID() ) );
		if( ! $key ) continue;
		$syntaxes[$key] = $syntax;
	}

	ksort( $syntaxes );

	// cache the schema to prevent multiple schema fetches from LDAP server
	$cache[$server_id] = $syntaxes;

	return $syntaxes;
}

?>