What is the purpose of the MachineState/EndpointState?

Question

I am currently writing a Trusted UCMA 5.0 Application that will change the Presence of different Users.

When publishing presence for an UserEndpoint, you can publish multiple different types of presence e.g.:
UserState: Available, Busy, Offline, ...
PhoneState: Is user currently in a call or conference
and some more including the EndpointState/MachineState.

So I can set a User Busy with the following code:

// ... init collaboration platform (trusted application) and create the UserEndpoint 
var presenceCategs = new PresenceCategory[]
{
    PresenceState.UserBusy,
    new Note("Will be back in 10 minutes"),
    PresenceState.EndpointAway
};

_userEndpoint.LocalOwnerPresence.BeginPublishPresence(presenceCategs, PublishPresenceCompleted, true);

// ...     
private void PublishPresenceCompleted(IAsyncResult ar)
{
    _userEndpoint.LocalOwnerPresence.EndPublishPresence(ar);
    Console.WriteLine("Publish Presence Complete");
}

The code works but the problem is I am unsure when/how to use EndpointState correctly.
The only documentation I found about the EndpointState / MachineState is not helping me further:

EndpointState

The availability of the endpoint owner from this particular endpoint.

https://msdn.microsoft.com/en-us/library/dn466019(v=office.16).aspx

As of now I couldn't observe any different or odd behaviour when changing or leaving out the EndpointState (e.g. PresenceState.EndpointAway when UserOnline)

So my main questions are:

• Whats the purpose of the EndpointState, for what will this information be used in S4B?

• How do I Set the EndpointState correctly? Is it really necessary to include the Machine state when updating the UserState or would this be ok?

      var presenceCategs = new PresenceCategory[]
           {
                  PresenceState.UserBusy,
           };
      _userEndpoint.LocalOwnerPresence.BeginPublishPresence(presenceCategs, PublishPresenceCompleted, true);
  

• What "rules"/Conventions do apply when changing the EndpointState?

Answer 1

I find presence to be a very confusing topic in SfB. As I understand it, every SIP endpoint can have it's OWN presence state.

So there are multiple layers of presence state PER "user". Each registered SIP endpoint has it's own presence "State", the contact card for the user has it's own presence state, every calendar event has it's own presence state. There is also the "aggregate" presence state that I believe is the sum total of the all the presence states that is what anyone else sees at any one time.

Given that then the page that you point to says:

EndpointState The availability of the endpoint owner from this particular endpoint.

Means that you are setting the current SIP endpoint (in your case the UserEndpoint's) presence ONLY to busy. So the user busy "state" will last as long as your UserEndpoint is alive for and also any other SIP endpoint logged in as that user will not change state.

UserState The availability preference of the endpoint owner.

So if you set the user state, it's not setting the state for just your SIP endpoint but will force any other logged in user endpoint to change to that state as well. So the presence state will last as long as it's changed by you or the another instance logged in instance of the user.

Which one you use depends on what you are trying to do.

The UserState option is good if you want to set the user state than let the UserEndpoint instance die. So it can live for the length of setting the user presence only.

The EndpointState can be used when you are keeping the UserEndpoint around for awhile and you don't what the users overall presence to be "Busy" unless you are the only presence instance alive to service User calls. So effectively you are just advertising your endpoints "presence" and not the users presence overall.