Back to index

lightning-sunbird  0.9+nobinonly
Public Member Functions | Public Attributes | Protected Member Functions | Protected Attributes
nsAbLDAPAutoCompFormatter Class Reference

#include <nsAbLDAPAutoCompFormatter.h>

Inheritance diagram for nsAbLDAPAutoCompFormatter:
Inheritance graph
[legend]
Collaboration diagram for nsAbLDAPAutoCompFormatter:
Collaboration graph
[legend]

List of all members.

Public Member Functions

NS_DECL_ISUPPORTS
NS_DECL_NSILDAPAUTOCOMPFORMATTER
NS_DECL_NSIABLDAPAUTOCOMPFORMATTER 
nsAbLDAPAutoCompFormatter ()
virtual ~nsAbLDAPAutoCompFormatter ()
nsIAutoCompleteItem format (in nsILDAPMessage aMessage)
 Returns an nsIAutoCompleteItem generated from the data in the given nsILDAPMessage.
void getAttributes (out unsigned long aCount,[retval, array, size_is(aCount)] out string aAttrs)
 Gets a list of all the LDAP attributes that should be requested from the LDAP server when a lookup is done.
nsIAutoCompleteItem formatException (in long aState, in nsresult aErrorCode)
 This method formats an error condition into an nsIAutoCompleteItem for display to the user.

Public Attributes

attribute AString nameFormat
 All three Format attributes are templates, which work as follows:
attribute AString addressFormat
attribute AString commentFormat
const long STATE_UNBOUND = 0
 Possible states that can be passed in aState to formatException.
const long STATE_INITIALIZING = 1
const long STATE_BINDING = 2
const long STATE_BOUND = 3
const long STATE_SEARCHING = 4

Protected Member Functions

nsresult ProcessFormat (const nsAString &aFormat, nsILDAPMessage *aMessage, nsACString *aValue, nsCStringArray *aAttrs)
nsresult ParseAttrName (nsReadingIterator< PRUnichar > &aIter, nsReadingIterator< PRUnichar > &aIterEnd, PRBool aAttrRequired, nsCOMPtr< nsIConsoleService > &aConsoleSvc, nsACString &aAttrName)
nsresult AppendFirstAttrValue (const nsACString &aAttrName, nsILDAPMessage *aMessage, PRBool aAttrRequired, nsACString &aValue)

Protected Attributes

nsString mNameFormat
nsString mAddressFormat
nsString mCommentFormat

Detailed Description

Definition at line 46 of file nsAbLDAPAutoCompFormatter.h.


Constructor & Destructor Documentation

NS_DECL_ISUPPORTS NS_DECL_NSILDAPAUTOCOMPFORMATTER NS_DECL_NSIABLDAPAUTOCOMPFORMATTER nsAbLDAPAutoCompFormatter::nsAbLDAPAutoCompFormatter ( )

Definition at line 71 of file nsAbLDAPAutoCompFormatter.cpp.

{
}

Member Function Documentation

nsresult nsAbLDAPAutoCompFormatter::AppendFirstAttrValue ( const nsACString &  aAttrName,
nsILDAPMessage aMessage,
PRBool  aAttrRequired,
nsACString &  aValue 
) [protected]

Definition at line 639 of file nsAbLDAPAutoCompFormatter.cpp.

{
    // get the attribute values for the field which will be used 
    // to fill in nsIAutoCompleteItem::value
    //
    PRUint32 numVals;
    PRUnichar **values;

    nsresult rv;
    rv = aMessage->GetValues(PromiseFlatCString(aAttrName).get(), &numVals, 
                             &values);
    if (NS_FAILED(rv)) {

        switch (rv) {
        case NS_ERROR_LDAP_DECODING_ERROR:
            // this may not be an error, per se; it could just be that the 
            // requested attribute does not exist in this particular message,
            // either because we didn't request it with the search operation,
            // or because it doesn't exist on the server.
            //
            break;

        case NS_ERROR_OUT_OF_MEMORY:
        case NS_ERROR_UNEXPECTED:
            break;

        default:
            NS_ERROR("nsLDAPAutoCompleteSession::OnLDAPSearchEntry(): "
                     "unexpected return code from aMessage->getValues()");
            rv = NS_ERROR_UNEXPECTED;
            break;
        }

        // if this was a required attribute, don't append anything to aValue
        // and return the error code
        //
        if (aAttrRequired) {
            return rv;
        } else {
            // otherwise forget about this attribute, but return NS_OK, which
            // will cause our caller to continue processing nameFormat in 
            // order to generate an nsIAutoCompleteItem.
            //
            return NS_OK;
        }
    }

    // append the value to our string; then free the array of results
    //
    AppendUTF16toUTF8(values[0], aValue);
    NS_FREE_XPCOM_ALLOCATED_POINTER_ARRAY(numVals, values);

    // if this attribute wasn't required, we fall through to here, and return 
    // ok
    //
    return NS_OK;
}

Here is the call graph for this function:

Here is the caller graph for this function:

Returns an nsIAutoCompleteItem generated from the data in the given nsILDAPMessage.

Parameters:
aMessagemessage to be formatted
Returns:
resulting nsIAutoCompleteItem

This method formats an error condition into an nsIAutoCompleteItem for display to the user.

Specifically, the state that the session was in when the error occured (aState) is formatted into a general error message which is put in the value attribute of the item, and the specific error (aErrorCode) is formatted into another message which is put in an nsISupportsString in the param attribute of the item.

Parameters:
aStatestate of autocomplete session when error occurred
aErrorCodespecific error encountered
Returns:
newly generated item
void nsILDAPAutoCompFormatter::getAttributes ( out unsigned long  aCount,
[retval, array, size_is(aCount)] out string  aAttrs 
) [inherited]

Gets a list of all the LDAP attributes that should be requested from the LDAP server when a lookup is done.

This avoids wasting server time, bandwidth, and client time processing unused attributes.

Note that this is only required to be called by the nsILDAPAutoCompleteSession implementation when the nsILDAPAutoCompleteSession::formatter IDL attribute is set. . So if for some reason, the LDAP attributes to be returned by searches has to change (eg because the user changed a preference), the nsILDAPAutoCompleteSession::formatter IDL attribute should be re-set to the same object to force a new getAttributes() call.

Parameters:
aCountnumber of attributes in the array
aAttrslist of LDAP attributes to request
nsresult nsAbLDAPAutoCompFormatter::ParseAttrName ( nsReadingIterator< PRUnichar > &  aIter,
nsReadingIterator< PRUnichar > &  aIterEnd,
PRBool  aAttrRequired,
nsCOMPtr< nsIConsoleService > &  aConsoleSvc,
nsACString &  aAttrName 
) [protected]

Definition at line 585 of file nsAbLDAPAutoCompFormatter.cpp.

{
    // reset attrname, and move past the opening brace
    //
    ++aIter;

    // get the rest of the attribute name
    //
    do {

        // be sure we haven't run off the end
        //
        if (aIter == aIterEnd) {

            // abort; missing closing delimiter
            //
            if (aConsoleSvc) {
                aConsoleSvc->LogStringMessage(
                    NS_LITERAL_STRING(
                        "LDAP address book autocomplete formatter: error parsing format string: missing } or ]").get());

                NS_ERROR("LDAP address book autocomplete formatter: error "
                         "parsing format string: missing } or ]");
            }

            return NS_ERROR_ILLEGAL_VALUE;

        } else if ( (aAttrRequired && *aIter == PRUnichar('}')) || 
                    (!aAttrRequired && *aIter == PRUnichar(']')) ) {

            // done with this attribute
            //
            break;

        } else {

            // this must be part of the attribute name
            //
            aAttrName.Append(NS_STATIC_CAST(char,*aIter));
        }

        ++aIter;

    } while (1);

    return NS_OK;
}

Here is the caller graph for this function:

nsresult nsAbLDAPAutoCompFormatter::ProcessFormat ( const nsAString &  aFormat,
nsILDAPMessage aMessage,
nsACString *  aValue,
nsCStringArray *  aAttrs 
) [protected]

Definition at line 452 of file nsAbLDAPAutoCompFormatter.cpp.

{
    nsresult rv;    // temp for return values

    // get some iterators to parse aFormat
    //
    nsReadingIterator<PRUnichar> iter, iterEnd;
    aFormat.BeginReading(iter);
    aFormat.EndReading(iterEnd);

    // get the console service for error logging
    //
    nsCOMPtr<nsIConsoleService> consoleSvc = 
        do_GetService("@mozilla.org/consoleservice;1", &rv);
    if (NS_FAILED(rv)) {
        NS_WARNING("nsAbLDAPAutoCompFormatter::ProcessFormat(): "
                   "couldn't get console service");
    }

    PRBool attrRequired = PR_FALSE;     // is this attr required or optional?
    nsCAutoString attrName;             // current attr to get

    // parse until we hit the end of the string
    //
    while (iter != iterEnd) {

        switch (*iter) {            // process the next char

        case PRUnichar('{'):

            attrRequired = PR_TRUE;  // this attribute is required

            /*FALLTHROUGH*/

        case PRUnichar('['):

            rv = ParseAttrName(iter, iterEnd, attrRequired, consoleSvc, 
                               attrName);
            if ( NS_FAILED(rv) ) {

                // something unrecoverable happened; stop parsing and 
                // propagate the error up the stack
                //
                return rv;
            }

            // if we're building an array
            if ( aAttrs ) { 

                // and it doesn't already contain this string
                if (aAttrs->IndexOfIgnoreCase(attrName) == -1) { 

                    // add it
                    if (!aAttrs->AppendCString(attrName)) {
                        
                        // current AppendCString always returns PR_TRUE;
                        // if we hit this error, something has changed in
                        // that code
                        //
                        NS_ERROR(
                            "nsAbLDAPAutoCompFormatter::ProcessFormat():"
                            " aAttrs->AppendCString(attrName) failed");
                        return NS_ERROR_UNEXPECTED;
                    }
                }
            } else {

                // otherwise, append the first value of this attr to aValue
                // XXXdmose should do better than this; bug 76595

                rv = AppendFirstAttrValue(attrName, aMessage, attrRequired, 
                                          *aValue);
                if ( NS_FAILED(rv) ) {

                    // something unrecoverable happened; stop parsing and 
                    // propagate the error up the stack
                    //
                    return rv;
                }
            }

            attrName.Truncate();     // clear out for next pass
            attrRequired = PR_FALSE; // reset to the default for the next pass

            break;

        case PRUnichar('\\'):

            // advance the iterator and be sure we haven't run off the end
            //
            ++iter;
            if (iter == iterEnd) {

                // abort; missing escaped char
                //
                if (consoleSvc) {
                    consoleSvc->LogStringMessage(
                        NS_LITERAL_STRING(
                            "LDAP addressbook autocomplete formatter: error parsing format string: premature end of string after \\ escape").get());

                    NS_ERROR("LDAP addressbook autocomplete formatter: error "
                             "parsing format string: premature end of string "
                             "after \\ escape");
                }

                return NS_ERROR_ILLEGAL_VALUE;
            }

            /*FALLTHROUGH*/

        default:
            
            // if we're not just building an array of attribute names, append
            // this character to the item we're generating.
            //
            if (!aAttrs) {

                // this character gets treated as a literal
                //
                AppendUTF16toUTF8(nsDependentString(iter.get(), 1), *aValue); //XXXjag poke me about string generators
            }
        }

        ++iter; // advance the iterator
    }

    return NS_OK;
}

Here is the call graph for this function:


Member Data Documentation

Definition at line 85 of file nsIAbLDAPAutoCompFormatter.idl.

Definition at line 86 of file nsIAbLDAPAutoCompFormatter.idl.

Definition at line 58 of file nsAbLDAPAutoCompFormatter.h.

Definition at line 59 of file nsAbLDAPAutoCompFormatter.h.

Definition at line 57 of file nsAbLDAPAutoCompFormatter.h.

All three Format attributes are templates, which work as follows:

Required LDAP attributes are delimited by curly braces, and optional LDAP attributes are determined by brackets. Backslash escapes any character, including itself. Someday perhaps we'll rev this interface and change these to a more flexible format; perhaps something regexp based.

If any of these are unset, components implementing this interface are free to choose reasonable defaults. As an example, the "@mozilla.org/ldap-autocomplete-formatter;1?type=addrbook" implementation currently happens to use the following default strings:

nameFormat: "[cn]" addressFormat: "{mail}" commentFormat: ""

and generates autocomplete items like this:

value: John Doe john..nosp@m.doe@.nosp@m.foo.o.nosp@m.rg comment: Foo Organization

Note that nsILDAPAutoCompFormatter::getAttributes() is only required to be called by the nsILDAPAutoCompleteSession implementation when the nsILDAPAutoCompleteSession::formatter IDL attribute is set. So if for some reason the format attributes exposed through this interface get changed (eg a user changes their prefs), it is the changing code's responsibly to re-set the nsILDAPAutoCompleteSession::formatter IDL attribute to the same object to force a new getAttributes() call.

Definition at line 84 of file nsIAbLDAPAutoCompFormatter.idl.

Definition at line 104 of file nsILDAPAutoCompFormatter.idl.

Definition at line 105 of file nsILDAPAutoCompFormatter.idl.

Definition at line 103 of file nsILDAPAutoCompFormatter.idl.

Definition at line 106 of file nsILDAPAutoCompFormatter.idl.

Possible states that can be passed in aState to formatException.

Definition at line 102 of file nsILDAPAutoCompFormatter.idl.


The documentation for this class was generated from the following files: