I am developing a telephony call model and thinking about how best to design the interface.One basic idea is that a call has a unique call identifier.  I have a list of calls and finding a specific call is easy by callid.Each call has zero or more parties.  A party has a device identifier (eg extension 201) and a state.  Eg my extension 201 can be alerting or established or whatever.I have a class to represent a call which has functions to find a party on the call,  I have the following findxxx functions:party* find_party_by_dn(const std::string& dn) const;int find_parties_by_dn(const std::string& dn, std::list<party*> pties) const;find_party_by_dn seems ok, but it has a problem in that a call may have 2 parties with the same device identifier. Eg a user may put a call on hold and make a new consult call to another device.  In which case the call has a party with dn 201 in state hold and another party with dn 201 and state dialling for example.So if I use function find_party_by_dn only the first party in the list with this dn will be returned.So I thought ah, why not return (well via reference) a list of parties with a given dn.  Hence the second function.  Does that seem like a useful interface?  Could it be improved?I also have these functions:party* find_party_by_state(const std::string& dn, pstate state) const;party* find_party_by_states(const std::string& dn, int states) const;In which case the caller needs to specify either a specific state or a number of states - eg state1 | state2I am looking for feedback on this interface.  Does it seem logical?  Could it be improved to make it more user friendly or robust?
Design of interface for finding one of something or a list
design;c++;interfaces
With your find_party_by_dn/find_parties_by_dn functions, you will see that in practice only one of them will get used (I predict it will be find_party_by_dn as that is the easier one). The reason for this is because the user of the function will not know if and when the search for a DN would return multiple results.In your particular case, I highly doubt the validity of the possibility that one DN represents multiple parties in a call, but if you have something like that, it is best to have just a single function that returns a list of the found items. If there is only one, then the list will simply be one long.With your find_party_by_state/find_party_by_states, there is less confusion about which function to use, but having two functions makes the interface more complicated than needed. You could just as easily offer one function find_party_by_state that accepts a bit-wise or combination of one or more states. There is no need to have a separate function for the special case of searching on one state.