/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
 *
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"

/**
 * This interface is a catch-all for any LDAP functionality that is needed
 * in XPCOM and not provided elsewhere.
 */
[scriptable, uuid(69de6fbc-2e8c-4482-bf14-358d68b785d1)]
interface nsILDAPService : nsISupports {

    /**
     * Generates and returns an LDAP search filter by substituting
     * aValue, aAttr, aPrefix, and aSuffix into aPattern.
     *
     * Exposes the functionality of ldap_create_filter() via XPCOM.
     *
     * There is some documentation on the filter template format
     * (passed in via aPattern) here:
     * https://docs.oracle.com/cd/E19957-01/817-6707/filter.html
     *
     * @param aMaxSize   maximum size (in char) of string to be
     *                   created and returned (including final \0)
     * @param aPattern   pattern to be used for the filter
     * @param aPrefix    prefix to prepend to the filter
     * @param aSuffix    suffix to be appended to the filer
     * @param aAttr      replacement for %a in the pattern
     * @param aValue     replacement for %v in the pattern
     *
     * @exception NS_ERROR_INVALID_ARG      invalid parameter passed in
     * @exception NS_ERROR_OUT_OF_MEMORY    allocation failed
     * @exception NS_ERROR_NOT_AVAILABLE    filter longer than maxsiz chars
     * @exception NS_ERROR_UNEXPECTED       ldap_create_filter returned
     *                                      unexpected error code
     */
    AUTF8String createFilter(in unsigned long aMaxSize, in AUTF8String aPattern,
                             in AUTF8String aPrefix, in AUTF8String aSuffix,
                             in AUTF8String aAttr, in AUTF8String aValue);
};