OpenSim 0.6 IClientAPI

From OpenSimulator

(Difference between revisions)
Jump to: navigation, search
(→‎Porting Guide)
m (Robot: Cosmetic changes)
 
(10 intermediate revisions by 6 users not shown)
Line 1: Line 1:
 +
__NOTOC__
 +
{{Quicklinks}}
 +
{{archive}}
 +
<br />
 +
 
{{content}}
 
{{content}}
 
This page is under construction.
 
This page is under construction.
−
=Porting Guide=
+
= IClientAPI is Being Deprecated =
−
==OnNewClient vs OnClientConnect==
+
 
−
* OnNewClient is depreciated, please use OnClientConnect instead.
+
That's right! The horrendous IClientAPI interface is slowly being replaced with smaller sub-interfaces that clients may choose to implement or not. As such, please don't write any new methods that take IClientAPI as arguments; they should take IClientCore and test which interfaces those implement before trying to do things with them.
−
** Rationale: OnNewClient passes IClientAPI in it's parameter, IClientAPI is being depreciated.
+
 
 +
= Porting Guide =
 +
== OnNewClient vs OnClientConnect ==
 +
* OnNewClient is deprecated, please use OnClientConnect instead.
 +
** Rationale: OnNewClient passes IClientAPI in it's parameter, IClientAPI is being deprecated.
 
** IClientAPI Changes: IClientCore may not contain all the interfaces you want just yet, but if it does (see the list below for what's been ported so far), you should switch to OnClientConnect and then use IClientCore.[Try]Get<IClientInterface>().Method() instead of IClientAPI.Method();
 
** IClientAPI Changes: IClientCore may not contain all the interfaces you want just yet, but if it does (see the list below for what's been ported so far), you should switch to OnClientConnect and then use IClientCore.[Try]Get<IClientInterface>().Method() instead of IClientAPI.Method();
−
==Instant Message==
+
 
 +
== Instant Message ==
 
* Dropping fromAgentSession from SendInstantMessage (both overloaded versions)
 
* Dropping fromAgentSession from SendInstantMessage (both overloaded versions)
 
** Rationale: Session ID is both linden specific, and something that shouldnt be transmitted to users anyway ('''security''').
 
** Rationale: Session ID is both linden specific, and something that shouldnt be transmitted to users anyway ('''security''').
Line 13: Line 23:
 
** Rationale: IM Session ID's are unique to SL and we just multiplex the two users ID's to form this so it's static anyway.
 
** Rationale: IM Session ID's are unique to SL and we just multiplex the two users ID's to form this so it's static anyway.
 
** IClientAPI changes: Multiplex the ID inside your own implementations vs relying on the module to do it for you.
 
** IClientAPI changes: Multiplex the ID inside your own implementations vs relying on the module to do it for you.
−
==Bluebox==
+
== Bluebox ==
 
* Dropping sessionID from SendBlueBoxMessage
 
* Dropping sessionID from SendBlueBoxMessage
 
** Rationale: Session ID is both linden specific, and something that shouldnt be transmitted to users anyway ('''security''').
 
** Rationale: Session ID is both linden specific, and something that shouldnt be transmitted to users anyway ('''security''').
 
** IClientAPI changes: Insert this parameter into your packets manually if you need it, LLClientView.cs contains a reference to sessionID already. Be advised that this represents a security risk (giving the users one of the two shared secrets).
 
** IClientAPI changes: Insert this parameter into your packets manually if you need it, LLClientView.cs contains a reference to sessionID already. Be advised that this represents a security risk (giving the users one of the two shared secrets).
 +
== Chat ==
 +
* Dropping SendChatMessage(bytes[]...) - the overload with string still works however.
 +
** Rationale: We arent using this, and sending the bytes raw instead of a string is poor methodology.
 +
** IClientAPI Changes: Drop this method if you arent using it.
 +
 +
= Example Conversion =
 +
== InstantMessageModule.cs ==
 +
=== Old ===
 +
        private void OnNewClient(IClientAPI client)
 +
        {
 +
            client.OnInstantMessage += OnInstantMessage;
 +
        }
 +
 +
=== New ===
 +
        void OnClientConnect(IClientCore client)
 +
        {
 +
            IClientIM clientIM;
 +
            if(client.TryGet(out clientIM))
 +
            {
 +
                clientIM.OnInstantMessage += OnInstantMessage;
 +
            }
 +
        }
 +
=== Comments ===
 +
Isnt this messier? I see more code! What's this IClientIM thing?
 +
 +
The short answer here is we're now using multiple interfaces to represent clients. Rather than dictating that every client must obey IClientAPI.cs - we can say clients can pick and choose the bits and pieces they want to implement.
 +
 +
The extra code is mostly in checking that the client supports Instant Messaging before attempting to handle IM's for it. If the client doesnt support that interface, it will lead to a crash if you try use it.

Latest revision as of 19:45, 3 March 2012

Languages Languages: 

En.png English

Imbox obsolete.png

This article or section is archived information.
The information in this page is no longer current, but it is being kept for historical reasons.
Do not delete this information, since it may hold historical value.


Imbox content.png

This article or section contains incomplete information.
Please help us by completing the content on this page.

This page is under construction.

[edit] IClientAPI is Being Deprecated

That's right! The horrendous IClientAPI interface is slowly being replaced with smaller sub-interfaces that clients may choose to implement or not. As such, please don't write any new methods that take IClientAPI as arguments; they should take IClientCore and test which interfaces those implement before trying to do things with them.

[edit] Porting Guide

[edit] OnNewClient vs OnClientConnect

  • OnNewClient is deprecated, please use OnClientConnect instead.
    • Rationale: OnNewClient passes IClientAPI in it's parameter, IClientAPI is being deprecated.
    • IClientAPI Changes: IClientCore may not contain all the interfaces you want just yet, but if it does (see the list below for what's been ported so far), you should switch to OnClientConnect and then use IClientCore.[Try]Get<IClientInterface>().Method() instead of IClientAPI.Method();

[edit] Instant Message

  • Dropping fromAgentSession from SendInstantMessage (both overloaded versions)
    • Rationale: Session ID is both linden specific, and something that shouldnt be transmitted to users anyway (security).
    • IClientAPI changes: Insert this parameter into your packets manually if you need it, LLClientView.cs contains a reference to sessionID already. Be advised that this represents a security risk (giving the users one of the two shared secrets).
  • Dropping imSessionID from SendInstantMessage (both overloaded versions)
    • Rationale: IM Session ID's are unique to SL and we just multiplex the two users ID's to form this so it's static anyway.
    • IClientAPI changes: Multiplex the ID inside your own implementations vs relying on the module to do it for you.

[edit] Bluebox

  • Dropping sessionID from SendBlueBoxMessage
    • Rationale: Session ID is both linden specific, and something that shouldnt be transmitted to users anyway (security).
    • IClientAPI changes: Insert this parameter into your packets manually if you need it, LLClientView.cs contains a reference to sessionID already. Be advised that this represents a security risk (giving the users one of the two shared secrets).

[edit] Chat

  • Dropping SendChatMessage(bytes[]...) - the overload with string still works however.
    • Rationale: We arent using this, and sending the bytes raw instead of a string is poor methodology.
    • IClientAPI Changes: Drop this method if you arent using it.

[edit] Example Conversion

[edit] InstantMessageModule.cs

[edit] Old 

       private void OnNewClient(IClientAPI client)
       {
           client.OnInstantMessage += OnInstantMessage;
       }

[edit] New 

       void OnClientConnect(IClientCore client)
       {
           IClientIM clientIM;
           if(client.TryGet(out clientIM))
           {
               clientIM.OnInstantMessage += OnInstantMessage;
           }
       }

[edit] Comments

Isnt this messier? I see more code! What's this IClientIM thing?

The short answer here is we're now using multiple interfaces to represent clients. Rather than dictating that every client must obey IClientAPI.cs - we can say clients can pick and choose the bits and pieces they want to implement.

The extra code is mostly in checking that the client supports Instant Messaging before attempting to handle IM's for it. If the client doesnt support that interface, it will lead to a crash if you try use it.

Retrieved from "http://opensimulator.org/index.php?title=OpenSim_0.6_IClientAPI&oldid=28360"
Personal tools
General
About This Wiki