\documentclass{article}
\usepackage{ulem}
\pagestyle{headings}
\begin{document}
\tableofcontents

Horde Group APIAbstractFunctional ChangesChallengesHorde\_Group\_Basecreate(\$name)rename(\$gid, \$newName)remove(\$gid)exists(\$gid)getName(\$gid)listAll()listUsers(\$gid, \$recurse = false)listGroups(\$user)addUser(\$gid, \$username)removeUser(\$gid, \$username)search(\$name)

\part{Horde Group API}
This document is intended to clarify the Horde Group API, and to provide a solid target for applications to move toward for Horde4.  Motivation for this document was spurred from the conversation between the Bens on IRC regarding the "proper" way to handle groups with LDAP.


\noindent\rule{\textwidth}{1pt}
\section{Abstract}
In its simplest terms a group consists of an ID and a Name.  The ID is unique to that group and is unchanging.  The name is a human-friendly name that can be changed as desired.  The source and/or format of the group ID should not be of concern to the application using it, and should always be obtained/modified/stored through the group API calls.  The group ID is the \textbf{only} acceptable method as to refer to a group, as it is guaranteed to be unique (uniqueness being the job of the driver).  The group name is strictly for interface use.

\section{Functional Changes}
Horde 4 will deviate from Horde 3 in these key ways:

\begin{itemize}
\item{The groups collection will be flat.  Groups cannot be created as children of existing groups.}
\begin{itemize}
\item{Groups can belong to other groups.  In this way complex collections of users can be expressed without duplication.}
\end{itemize}
\end{itemize}
\section{Challenges}
\begin{itemize}
\item{Make sure we handle group structures that represent an infinite loop}
\begin{itemize}
\item{Create a UI that allows administrators to be able to view all effective users in a group (including those that are a part of the group through group membership).}
\item{How do we handle backends that can't support nested group membership?  Example: LDAP can store this information but cannot integrate with other systems like Unix, which has not concept of nested groups.}
\end{itemize}
\end{itemize}

\noindent\rule{\textwidth}{1pt}
\section{Horde\_Group\_Base}
This is the class that does the work of reading from/saving to the group storage backend.

\subsection{create(\$name)}
Creates a new group and returns a new group ID.

\begin{itemize}
\item{Add handlers for \$name and \$parent parameters from newGroup() (?)}
\end{itemize}
\subsection{rename(\$gid, \$newName)}
Changes the name of a group without affecting its membership list

\subsection{remove(\$gid)}
Removes a group from the groups system permanently.

\subsection{exists(\$gid)}
Boolean: Check if a group exists in the system.

\subsection{getName(\$gid)}
Returns a group name.

\subsection{listAll()}
Returns an array of all groups, in the format gid => name.

\subsection{listUsers(\$gid, \$recurse = false)}
Get a list of every user that is a part of this group ONLY.

If \$recurse is true then also check member groups' user lists.

\subsection{listGroups(\$user)}
Returns an array of group IDs representing the user's membership

\subsection{addUser(\$gid, \$username)}
Add a user to a group.

\begin{itemize}
\item{Should be able to handle arrays for both parameters.}
\end{itemize}
\subsection{removeUser(\$gid, \$username)}
Remove a user from a group.

\begin{itemize}
\item{Should be able to handle arrays for both parameters.}
\end{itemize}
\subsection{search(\$name)}
Returns a list of group IDs that match the name (substring search?)

\end{document}
