module Treequel::Control

Virtual interface methods for Control modules.

Subclassing

To make a concrete derivative, include this module in a module that implements either #get_client_controls or #get_server_controls and each. Your implementation of each should super with a block that does the necessary extraction of the result controls and yields back to the original block.

Examples

module Treequel::MyControl
    include Treequel::Control

    # The control's OID
    OID = '1.3.6.1.4.1.984454.16.1'

    # If your control has some value associated with it, you can provide
    # an initializer to set up an instance variable or two.
    def initialize
        @my_control_value = 18
    end

    attr_accessor :my_control_value

    # This is the interface users will use to set values used in the control,
    # like so:
    #   branchset.controlled_somehow( value )
    def controlled_somehow( value )
        self.my_control_value = value
    end

    # This is overridden so you can fetch controls set by the server before
    # iterating. The #each in Treequel::Branchset will yield to this block
    # after performing a search.
    def each( &block )
        super do |branch|
            if my_control = branch.controls.find {|control| control.oid == OID }
                server_control_value = my_control.decode
                # ... do something with the returned server_control_value
            end

            block.call( branch )
        end
    end

    # This is how you inject your control into the search; Treequel::Branchset
    # will call this before running the search and add the results to its
    # server_controls. If you're implementing a client control, override
    # the #get_client_controls method instead. Be sure to super() so that any
    # controls registered before yours have a chance to add their objects too.
    def get_server_controls
        controls = super
        if self.my_control_value
            value = LDAP::Control.encode( self.my_control_value )
            controls << LDAP::Control.new( OID, value, true )
        end

        return controls
    end

end