2

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?

Improve this question
4
  • 1
    std::find_if
    – ratchet freak
    Commented Sep 4, 2013 at 10:39
  • What might your user be trying to accomplish in calling these APIs? Is timeliness necessary? e.g. phone calls are asynchronous, so the states could change at any time during the API call. If timeliness isn't important and the user is likely to want the states at the time of the API call, you probably want to return a summary of the states at the time the API call was made. This way they could do any searching or whatever they want on the raw or perhaps a limited form of the data.
    – Joel
    Commented Sep 4, 2013 at 10:49
  • I think it would be useful to get a "data model" done first before you decide on the functions to use. I have a sketched a quick model I can show you if you like it is an ERD. I am not C++ programmer.
    – NoChance
    Commented Sep 4, 2013 at 14:37
  • @ratchetfreak having discussed with peers I will try to make it more generic eg call will be collection of parties and allow caller to pass a predicate. So your comment hit a note.
    – user619818
    Commented Sep 5, 2013 at 12:17

1 Answer 1

Reset to default
0

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.

Improve this answer

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.