GroupsService

From OpenSimulator

(Difference between revisions)
Jump to: navigation, search
(→‎GETMEMBERSHIP)
(→‎FINDGROUPS)
Line 59: Line 59:
 
</ServerResponse>
 
</ServerResponse>
 
</source>
 
</source>
 +
 +
====Notes====
 +
If you want to find a specific group, use the GetGroup call instead.
  
 
===GETGROUP===
 
===GETGROUP===

Revision as of 12:04, 30 July 2014

Contents

Introduction

OpenSimulator both has a core groups service which is not yet enabled by default and an external XmlRpc/Flotsam groups service. This page describes the service level interface to the core groups.

For information on actually configuring the V2 groups service, see the link above.

The API calls described here potentially allow an external caller to manipulate groups. At the moment, changes will not be seem by users that are online until they log back in. And those changes will not be explicitly notified to them.

For example PHP code that makes these calls, see https://github.com/justincc/opensimulator-tools/tree/master/integration/php/src/programs/groups

API

Calls

WIP - Only a small number of possible service calls are currently described

FINDGROUPS

This returns summary information for groups that match a given pattern.

The POST field is a urlencoded string like so 

RequestingAgentID=00000000-0000-0000-0000-000000000000&Query=abc&METHOD=FINDGROUPS

where

  • RequestingAgentID is always 00000000-0000-0000-0000-000000000000 for external calls
  • Query is the pattern to match. The query string follows SQL LIKE formatting where % is always appended and prepended. So "group" will match any string containing the string "group", such as "mygroupname" and "group1". An empty string will return all groups.

If successful, you will see a server response such as 

<?xml version="1.0"?>
<ServerResponse>
  <RESULT type="List">
    <n-0 type="List">
      <GroupID>6ed52fa7-d910-4b6f-a2a6-8c121c0561dd</GroupID>
      <Name>abc1</Name>
      <NMembers>1</NMembers>
      <SearchOrder>0</SearchOrder>
    </n-0>
    <n-1 type="List">
      <GroupID>c5cd5ae2-6b06-4118-b0ed-41556c8c2fac</GroupID>
      <Name>fooabcbar</Name>
      <NMembers>1</NMembers>
      <SearchOrder>0</SearchOrder>
    </n-1>
  </RESULT>
</ServerResponse>

If no matching group is found, then you will receive 

<?xml version="1.0"?>
<ServerResponse>
  <RESULT>NULL</RESULT>
  <REASON>No hits</REASON>
</ServerResponse>

Notes

If you want to find a specific group, use the GetGroup call instead.

GETGROUP

This returns information about a given group. One can retrieve information by group UUID or name.

Hence, there are two forms of query, one which specifies the group name and one which specifies the group UUID. The POST field of the group name version looks as follows 

RequestingAgentID=00000000-0000-0000-0000-000000000000&METHOD=GETGROUP&Name=group1

where

  • RequestingAgentID is always 00000000-0000-0000-0000-000000000000 for external calls
  • Name is the name of the group.

The POST field of the group UUID version is 

RequestingAgentID=00000000-0000-0000-0000-000000000000&METHOD=GETGROUP&GroupID=6ed52fa7-d910-4b6f-a2a6-8c121c0561dd
  • RequestingAgentID is always 00000000-0000-0000-0000-000000000000 for external calls
  • GroupID is the UUID of the group.

If the query finds a group, then a result like the following is returned 

<?xml version="1.0"?>
<ServerResponse>
  <RESULT type="List">
    <AllowPublish>False</AllowPublish>
    <Charter>Group Charter</Charter>
    <FounderID>f2f493c0-27d3-4cf2-be97-b44dfdad13b6</FounderID>
    <FounderUUI/>
    <GroupID>6ed52fa7-d910-4b6f-a2a6-8c121c0561dd</GroupID>
    <GroupName>group1</GroupName>
    <InsigniaID>00000000-0000-0000-0000-000000000000</InsigniaID>
    <MaturePublish>False</MaturePublish>
    <MembershipFee>0</MembershipFee>
    <OpenEnrollment>True</OpenEnrollment>
    <OwnerRoleID>97c9aecf-58c1-4a8d-a8b9-6eb0bedacd92</OwnerRoleID>
    <ServiceLocation/>
    <ShownInList>True</ShownInList>
    <MemberCount>2</MemberCount>
    <RoleCount>2</RoleCount>
  </RESULT>
</ServerResponse>

If no group is found then the following is returned. 

<?xml version="1.0"?>
<ServerResponse>
  <RESULT>NULL</RESULT>
  <REASON>Group not found</REASON>
</ServerResponse>

GETGROUPMEMBERS

This returns settings for users that belong to a given group. The POST field is a urlencoded string like so 

RequestingAgentID=00000000-0000-0000-0000-000000000000&GroupID=6ed52fa7-d910-4b6f-a2a6-8c121c0561dd&METHOD=GETGROUPMEMBERS

where

  • RequestingAgentID is always 00000000-0000-0000-0000-000000000000 for external calls
  • GroupID is a group UUID.

If successful, you will see a server response such as 

<?xml version="1.0"?>
<ServerResponse>
  <RESULT type="List">
    <m-0 type="List">
      <AcceptNotices>True</AcceptNotices>
      <AccessToken/>
      <AgentID>f2f493c0-27d3-4cf2-be97-b44dfdad13b6</AgentID>
      <AgentPowers>349644697632766</AgentPowers>
      <Contribution>0</Contribution>
      <IsOwner>False</IsOwner>
      <ListInProfile>True</ListInProfile>
      <OnlineStatus/>
      <Title>Owner of group1</Title>
    </m-0>
  </RESULT>
</ServerResponse>

If no matching group is found, then 

<?xml version="1.0"?>
<ServerResponse>
  <RESULT>NULL</RESULT>
  <REASON>No members</REASON>
</ServerResponse>

GETMEMBERSHIP

This returns membership information for a given user for their active group, a specific group or all the groups to which they belong.

The POST field is a urlencoded string like so 

RequestingAgentID=00000000-0000-0000-0000-000000000000&AgentID=f2f493c0-27d3-4cf2-be97-b44dfdad13b6&GroupID=c5cd5ae2-6b06-4118-b0ed-41556c8c2fac&METHOD=GETMEMBERSHIP

where

  • RequestingAgentID is always 00000000-0000-0000-0000-000000000000 for external calls
  • AgentID is the user UUID for which we want to retreive membership information.
  • ALL (not shown) is an optional parameter which returns information about all the user's memberships. It will be active if it is present at all, whether blank or filled with any value. It will override any GroupID given.
  • GroupID is the group UUID for which we want membership information. If this is 00000000-0000-0000-0000-000000000000 or not present then information about the user's membership of their active group is returned.

If the user is found and a was specified and found, you will see a server response such as 

<?xml version="1.0"?>
<ServerResponse>
  <RESULT type="List">
    <AcceptNotices>True</AcceptNotices>
    <AccessToken/>
    <Active>True</Active>
    <ActiveRole>28d962e4-81d4-4a3a-91a4-974b76c31a7d</ActiveRole>
    <AllowPublish>False</AllowPublish>
    <Charter>Group Charter</Charter>
    <Contribution>0</Contribution>
    <FounderID>f2f493c0-27d3-4cf2-be97-b44dfdad13b6</FounderID>
    <GroupID>c5cd5ae2-6b06-4118-b0ed-41556c8c2fac</GroupID>
    <GroupName>group2</GroupName>
    <GroupPicture>00000000-0000-0000-0000-000000000000</GroupPicture>
    <GroupPowers>349644697632766</GroupPowers>
    <GroupTitle>Owner of group2</GroupTitle>
    <ListInProfile>True</ListInProfile>
    <MaturePublish>False</MaturePublish>
    <MembershipFee>0</MembershipFee>
    <OpenEnrollment>True</OpenEnrollment>
    <ShowInList>True</ShowInList>
  </RESULT>
</ServerResponse>

If the group was not found then you will see the response 

<?xml version="1.0"?>
<ServerResponse>
  <RESULT>NULL</RESULT>
  <REASON>No such membership</REASON>
</ServerResponse>

If the user was not found you will also see the response 

<?xml version="1.0"?>
<ServerResponse>
  <RESULT>NULL</RESULT>
  <REASON>No such membership</REASON>
</ServerResponse>

PUTGROUP

ADDAGENTTOGROUP

REMOVEAGENTFROMGROUP

PUTROLE

REMOVEROLE

GETGROUPROLES

GETROLEMEMBERS

AGENTROLE

GETAGENTROLES

SETACTIVE

UPDATEMEMBERSHIP

INVITE

ADDNOTICE

GETNOTICES

Retrieved from "http://opensimulator.org/index.php?title=GroupsService&oldid=39413"
Personal tools
General
About This Wiki