Method: Net::LDAP#search

Defined in:

lib/net/ldap.rb

#search(args = {}) ⇒ Object

Searches the LDAP directory for directory entries. Takes a hash argument with parameters. Supported parameters include:

• :base (a string specifying the tree-base for the search);

• :filter (an object of type Net::LDAP::Filter, defaults to objectclass=*);

• :attributes (a string or array of strings specifying the LDAP attributes to return from the server);

• :return_result (a boolean specifying whether to return a result set).

• :attributes_only (a boolean flag, defaults false)

• :scope (one of: Net::LDAP::SearchScope_BaseObject, Net::LDAP::SearchScope_SingleLevel, Net::LDAP::SearchScope_WholeSubtree. Default is WholeSubtree.)

#search queries the LDAP server and passes each entry to the caller-supplied block, as an object of type Net::LDAP::Entry. If the search returns 1000 entries, the block will be called 1000 times. If the search returns no entries, the block will not be called.

– ORIGINAL TEXT, replaced 04May06. #search returns either a result-set or a boolean, depending on the value of the :return_result argument. The default behavior is to return a result set, which is a hash. Each key in the hash is a string specifying the DN of an entry. The corresponding value for each key is a Net::LDAP::Entry object. If you request a result set and #search fails with an error, it will return nil. Call #get_operation_result to get the error information returned by the LDAP server. ++ #search returns either a result-set or a boolean, depending on the value of the :return_result argument. The default behavior is to return a result set, which is an Array of objects of class Net::LDAP::Entry. If you request a result set and #search fails with an error, it will return nil. Call #get_operation_result to get the error information returned by the LDAP server.

When :return_result => false, #search will return only a Boolean, to indicate whether the operation succeeded. This can improve performance with very large result sets, because the library can discard each entry from memory after your block processes it.

treebase = "dc=example,dc=com"
filter = Net::LDAP::Filter.eq( "mail", "a*.com" )
attrs = ["mail", "cn", "sn", "objectclass"]
ldap.search( :base => treebase, :filter => filter, :attributes => attrs, :return_result => false ) do |entry|
  puts "DN: #{entry.dn}"
  entry.each do |attr, values|
    puts ".......#{attr}:"
    values.each do |value|
      puts "          #{value}"
    end
  end
end

– This is a re-implementation of search that replaces the original one (now renamed searchx and possibly destined to go away). The difference is that we return a dataset (or nil) from the call, and pass _each entry_ as it is received from the server to the caller-supplied block. This will probably make things far faster as we can do useful work during the network latency of the search. The downside is that we have no access to the whole set while processing the blocks, so we can’t do stuff like sort the DNs until after the call completes. It’s also possible that this interacts badly with server timeouts. We’ll have to ensure that something reasonable happens if the caller has processed half a result set when we throw a timeout error. Another important difference is that we return a result set from this method rather than a T/F indication. Since this can be very heavy-weight, we define an argument flag that the caller can set to suppress the return of a result set, if he’s planning to process every entry as it comes from the server.

REINTERPRETED the result set, 04May06. Originally this was a hash of entries keyed by DNs. But let’s get away from making users handle DNs. Change it to a plain array. Eventually we may want to return a Dataset object that delegates to an internal array, so we can provide sort methods and what-not.

# File 'lib/net/ldap.rb', line 627

def search args = {}
  args[:base] ||= @base
  result_set = (args and args[:return_result] == false) ? nil : []

  if @open_connection
    @result = @open_connection.search( args ) {|entry|
      result_set << entry if result_set
      yield( entry ) if block_given?
    }
  else
    @result = 0
    conn = Connection.new( :host => @host, :port => @port, :encryption => @encryption )
    if (@result = conn.bind( args[:auth] || @auth )) == 0
      @result = conn.search( args ) {|entry|
        result_set << entry if result_set
        yield( entry ) if block_given?
      }
    end
    conn.close
  end

  @result == 0 and result_set
end