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 | state2
I am looking for feedback on this interface. Does it seem logical? Could it be improved to make it more user friendly or robust?
4
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.