Difference between revisions of "LlRequestPermissions"

From Second Life Wiki
Jump to navigation Jump to search
m
(Added two caveats (regarding state changes); cleaned up a tad.)
(5 intermediate revisions by 5 users not shown)
Line 15: Line 15:
* Permissions persist across state changes.
* Permissions persist across state changes.
* Regardless of whether granting is automatic, you should always use the [[run_time_permissions]] event.  Granting permissions takes time, and you shouldn't assume it's completed until the [[run_time_permissions]] handler gets invoked.
* Regardless of whether granting is automatic, you should always use the [[run_time_permissions]] event.  Granting permissions takes time, and you shouldn't assume it's completed until the [[run_time_permissions]] handler gets invoked.
* The menu-option "Stop Animating Me" will release certain permissions (PERMISSION_TRIGGER_ANIMATION and PERMISSION_OVERRIDE_ANIMATIONS), if the script which holds these permissions is in the same region as the agent, and the script is not attached to the permission granter.
* Permissions do not accumulate.
* Permissions do not accumulate.
** If a permission was requested with a previous call to this function and granted, then in subsequent call was not requested, that permission is released (lost).
** If a permission was requested with a previous call to this function and granted, then in subsequent call was not requested, that permission is released (lost).
** To request two or more permissions at the same time, use the bitwise OR <nowiki>(|) operator, e.g.:</nowiki> <lsl>llRequestPermissions(AvatarID, PERMISSION_TAKE_CONTROLS | PERMISSION_TRIGGER_ANIMATION)</lsl>
** To request two or more permissions at the same time, use the bitwise OR <nowiki>(|) operator, e.g.:</nowiki> <source lang="lsl2">llRequestPermissions(AvatarID, PERMISSION_TAKE_CONTROLS | PERMISSION_TRIGGER_ANIMATION)</source>
</div>
</div>
* Permissions are requested and granted separately for each script, even if they are located in the same object.
* It is currently not possible to request no permissions at all (see Issues below); as a workaround [[llResetScript]] can be used.
* It is currently not possible to request no permissions at all (see Issues below); as a workaround [[llResetScript]] can be used.
* Scripts may hold permissions for only one agent at a time. To hold permissions for multiple agents you must use more than one script.
* Scripts may hold permissions for only one agent at a time. To hold permissions for multiple agents you must use more than one script.
* The result of granting permissions affects the return of [[llGetPermissions]] and [[llGetPermissionsKey]] immediately, despite the [[run_time_permissions]] event being queued, or dropped if the object's event queue is full.
* The result of granting permissions affects the return of [[llGetPermissions]] and [[llGetPermissionsKey]] immediately, despite the [[run_time_permissions]] event being queued, or dropped if the object's event queue is full.
* Permission request dialogs never time out.
* Permission request dialogs never time out.
** If a script makes two permission requests, which ever response is last is considered the granted permissions.
* If a script makes two permission requests, whichever response is last is considered the granted permissions.
* The viewer limits permission requests from any agent to any other agent to 5 dialogs in 10 seconds
* The viewer limits permission requests from any agent to any other agent to 5 dialogs in 10 seconds.
* Permission requests and changing state ...
** Requesting a permission in one state, then changing state before the agent response, will cause [[run_time_permissions]] to be fired in the new state once the agent responds.
** Requesting only auto-granted permissions in one state, then immediately changing state, will never fire [[run_time_permissions]].
|notes=When an agent grants a script non-automatic permissions they will receive a notification (in chat) of - The '''name''' of the object that contains the script that has been granted perms, The name of the owner of the object, The location of the object in the order - Region name at '''position''' - and a statement of what permissions were granted. If the script that holds the permissions is in a child prim the '''name''' will be that of the child prim (not the object (root)) and '''position''' will be its [[llGetLocalPos|local]] position (relative to its root).
|notes=When an agent grants a script non-automatic permissions they will receive a notification (in chat) of - The '''name''' of the object that contains the script that has been granted perms, The name of the owner of the object, The location of the object in the order - Region name at '''position''' - and a statement of what permissions were granted. If the script that holds the permissions is in a child prim the '''name''' will be that of the child prim (not the object (root)) and '''position''' will be its [[llGetLocalPos|local]] position (relative to its root).
|examples=Request permission to animate an avatar
|examples=Request permission to animate an avatar
<lsl>
<source lang="lsl2">default
default
{
{
     touch_start(integer num_detected)
     touch_start(integer detected)
     {
     {
         key id = llDetectedKey(0);
         llRequestPermissions(llDetectedKey(0), PERMISSION_TRIGGER_ANIMATION);
        llRequestPermissions(id, PERMISSION_TRIGGER_ANIMATION);
     }
     }
 
     run_time_permissions(integer perm)
     run_time_permissions(integer perm)                                
     {
     {
         if (perm & PERMISSION_TRIGGER_ANIMATION)
         if (perm & PERMISSION_TRIGGER_ANIMATION)
         {
         {
             llStartAnimation("sit");
             llStartAnimation("sit");
             llSay(PUBLIC_CHANNEL, "Animation will end in 5.0 seconds.");
             llOwnerSay("animation will end in 5 seconds");
 
             llSetTimerEvent(5.0);
             llSetTimerEvent(5.0);
         }
         }
     }
     }
     timer()
     timer()
     {
     {
         llSetTimerEvent((float)FALSE);
         llSetTimerEvent(0.0);
 
         llStopAnimation("sit");
         llStopAnimation("sit");
     }
     }
}
}</source>
</lsl>
 
To request two (or more) different permissions at the same time you can using the bitwise OR <nowiki>(|)</nowiki> or precompute the value.
<lsl>llRequestPermissions(AvatarID, PERMISSION_TAKE_CONTROLS | PERMISSION_TRIGGER_ANIMATION);


integer perms = PERMISSION_TAKE_CONTROLS | PERMISSION_TRIGGER_ANIMATION;
To request two (or more) permissions at the same time, use the bitwise OR <nowiki>(|)</nowiki> [[LSL_Operators|operator]].
llRequestPermissions(AvatarID, perms);</lsl>
<source lang="lsl2">llRequestPermissions(AvatarID, PERMISSION_TAKE_CONTROLS | PERMISSION_TRIGGER_ANIMATION);</source>
: - or -
<source lang="lsl2">integer perms = PERMISSION_TAKE_CONTROLS | PERMISSION_TRIGGER_ANIMATION;
llRequestPermissions(AvatarID, perms);</source>


|helpers
|helpers

Revision as of 06:41, 19 December 2015

Summary

Function: llRequestPermissions( key agent, integer permissions );

Ask agent for permissions to run certain classes of functions.

• key agent – avatar UUID that is in the same region
• integer permissions – Permission mask (bitfield containing the permissions to request).

Script execution continues without waiting for a response. When a response is given, a run_time_permissions event is put in the event queue.

Constants Action Category Granter Automatically granted when…
PERMISSION_DEBIT 0x2 take money from agent's account Money Owner
PERMISSION_TAKE_CONTROLS 0x4 take agent's controls Control Anyone sat on, attached
PERMISSION_TRIGGER_ANIMATION 0x10 start or stop Animations on agent Animation Anyone sat on, attached
PERMISSION_ATTACH 0x20 attach/detach from agent Attachment Owner or Anyone attached
PERMISSION_CHANGE_LINKS 0x80 change links Link Owner
PERMISSION_TRACK_CAMERA 0x400 track the agent's camera position and rotation Camera Anyone sat on, attached
PERMISSION_CONTROL_CAMERA 0x800 control the agent's camera
(must be sat on or attached; automatically revoked on stand or detach) 		Camera Anyone sat on, attached
PERMISSION_TELEPORT 0x1000 teleport the agent Teleport Anyone[1]
PERMISSION_SILENT_ESTATE_MANAGEMENT 0x4000 manage estate access without notifying the owner of changes Estate Owner
PERMISSION_OVERRIDE_ANIMATIONS 0x8000 configure the overriding of default animations on agent Animation Anyone attached
PERMISSION_RETURN_OBJECTS 0x10000 Used by llReturnObjectsByOwner and llReturnObjectsByID to return objects from parcels Cleanup Owner, Group Owner

Caveats

  • A dialog is presented to the agent to grant these permissions except when granted automatically as shown in the table above.
  • If object is attached to agent, "automatic" permissions are granted without notification upon request.
  • Permissions persist across state changes.
  • Regardless of whether granting is automatic, you should always use the run_time_permissions event. Granting permissions takes time, and you shouldn't assume it's completed until the run_time_permissions handler gets invoked.
  • The menu-option "Stop Animating Me" will release certain permissions (PERMISSION_TRIGGER_ANIMATION and PERMISSION_OVERRIDE_ANIMATIONS), if the script which holds these permissions is in the same region as the agent, and the script is not attached to the permission granter.
  • Permissions do not accumulate.
    • If a permission was requested with a previous call to this function and granted, then in subsequent call was not requested, that permission is released (lost).
    • To request two or more permissions at the same time, use the bitwise OR (|) operator, e.g.: 
      llRequestPermissions(AvatarID, PERMISSION_TAKE_CONTROLS | PERMISSION_TRIGGER_ANIMATION)
  • Permissions are requested and granted separately for each script, even if they are located in the same object.
  • It is currently not possible to request no permissions at all (see Issues below); as a workaround llResetScript can be used.
  • Scripts may hold permissions for only one agent at a time. To hold permissions for multiple agents you must use more than one script.
  • The result of granting permissions affects the return of llGetPermissions and llGetPermissionsKey immediately, despite the run_time_permissions event being queued, or dropped if the object's event queue is full.
  • Permission request dialogs never time out.
  • If a script makes two permission requests, whichever response is last is considered the granted permissions.
  • The viewer limits permission requests from any agent to any other agent to 5 dialogs in 10 seconds.
  • Permission requests and changing state ...
    • Requesting a permission in one state, then changing state before the agent response, will cause run_time_permissions to be fired in the new state once the agent responds.
    • Requesting only auto-granted permissions in one state, then immediately changing state, will never fire run_time_permissions.

Important Issues

~ All Issues ~ Search JIRA for related Bugs
Issue Type-Bug.gif Status-Open.gif SVC-1006 A     Unable to release script permissions

Examples

Request permission to animate an avatar 

default
{
    touch_start(integer detected)
    {
        llRequestPermissions(llDetectedKey(0), PERMISSION_TRIGGER_ANIMATION);
    }
    run_time_permissions(integer perm)
    {
        if (perm & PERMISSION_TRIGGER_ANIMATION)
        {
            llStartAnimation("sit");
            llOwnerSay("animation will end in 5 seconds");
            llSetTimerEvent(5.0);
        }
    }
    timer()
    {
        llSetTimerEvent(0.0);
        llStopAnimation("sit");
    }
}

To request two (or more) permissions at the same time, use the bitwise OR (|) operator. 

llRequestPermissions(AvatarID, PERMISSION_TAKE_CONTROLS | PERMISSION_TRIGGER_ANIMATION);
- or -
integer perms = PERMISSION_TAKE_CONTROLS | PERMISSION_TRIGGER_ANIMATION;
llRequestPermissions(AvatarID, perms);

Notes

When an agent grants a script non-automatic permissions they will receive a notification (in chat) of - The name of the object that contains the script that has been granted perms, The name of the owner of the object, The location of the object in the order - Region name at position - and a statement of what permissions were granted. If the script that holds the permissions is in a child prim the name will be that of the child prim (not the object (root)) and position will be its local position (relative to its root).

See Also

Events

•  run_time_permissions – Permission receiver event

Functions

•  llGetPermissions – Get the permissions granted
•  llGetPermissionsKey – Get the avatar who granted permissions.

Articles

•  Script permissions

Deep Notes

All Issues

~ Search JIRA for related Issues
Issue Type-Bug.gif Status-Open.gif SVC-1006 A     Unable to release script permissions
Issue Type-New Feature.gif Status-Open.gif SVC-8067 A     Improved Permissions Handling

Footnotes

Signature

function void llRequestPermissions( key agent, integer permissions );
Retrieved from "https://wiki.secondlife.com/w/index.php?title=LlRequestPermissions&oldid=1198453"