Difference between revisions of "LlRemoteLoadScriptPin"

From Second Life Wiki
Jump to navigation Jump to search
m
m (than->then typo fix)
 
(18 intermediate revisions by 7 users not shown)
Line 1: Line 1:
{{LSL_Function/give|target|name|sim=*|uuid=false|type=script}}{{Issues/SVC-3321}}
{{LSL_Function
{{LSL_Function
|inject-2={{Issues/SVC-3321}}
{{LSL_Function/give|target|name|sim=*|uuid=false|type=script|prim=*}}{{LSL Function/boolean|running|if=*|bool=*|non-zero=*|td=the script is set as running|fd=the script is not set as running}}
|func_id=253|func_sleep=3.0|func_energy=10.0
|func_id=253|func_sleep=3.0|func_energy=10.0
|func=llRemoteLoadScriptPin
|func=llRemoteLoadScriptPin
|func_desc=Copy script {{LSLP|name}} into {{LSLP|target}} and set to {{LSLP|running}} with a {{LSLP|start_param}} only if {{LSLP|target}}'s [[llSetRemoteScriptAccessPin|pin]] matches {{LSLP|pin}}
|p1_type=key|p1_name=target|p1_desc
|p1_type=key|p1_name=target|p1_desc
|p2_type=string|p2_name=name|p2_desc
|p2_type=string|p2_name=name|p2_desc
|p3_type=integer|p3_name=pin|p3_desc=Must match pin set by [[llSetRemoteScriptAccessPin]]
|p3_type=integer|p3_name=pin|p3_desc=Must match pin set by [[llSetRemoteScriptAccessPin]]
|p4_type=integer|p4_name=running|p4_desc=boolean, if the script is to be set as running.
|p4_type=integer|p4_subtype=boolean|p4_name=running
|p5_type=integer|p5_name=start_param|p5_desc=value returned by [[llGetStartParameter]] in the target script.
|p5_type=integer|p5_name=start_param|p5_desc=value returned by [[llGetStartParameter]] in the target script.
|func_desc=Copy script '''name''' into '''target''' and if '''running''' start with '''start_param'''.
|func_footnote=Only works if the [[LSL Glossary#script owner|script owner]] can modify {{LSLP|target}}.
|func_footnote=Only works if the owner of the object this script is in can modify '''target'''.
|return_text
|return_text
|spec
|spec
|caveats=
|caveats=
* If '''name''' is present in the '''target''' prim's inventory then it is silently replaced.
* If {{LSLP|name}} is present in the {{LSLP|target}} prim's inventory then it is silently replaced.
* '''start_param''' only lasts until the script is reset.
* {{LSLP|start_param}} only lasts until the script is reset.
* If '''target''' is an {{LSLGC|Attachment|attachment}} owned by a different user, regardless of object modify rights granted, this function will silently (bug?) fail.{{Footnote|{{LSLGC|Attachment|Attachments}} can only be modified by their owner.|Attachments can only be modified by their owner.}}
* Only the owner of an {{LSLGC|Attachment|attachment}} can modify it while it is being worn.
* If '''pin''' fails to match, the error "Task ~Prim~ trying to illegally load script onto task ~Other_Prim~!" is shouted on [[DEBUG_CHANNEL]]. "~Prim~" and "~Other_Prim~" are substituted with the applicable prim names.
** If {{LSLP|target}} is an {{LSLGC|Attachment|attachment}} owned by a different user, regardless of object modify rights granted, this function will silently fail.
* If '''target''' is invalid then "Unable to add item!" is shouted on [[DEBUG_CHANNEL]]. '''target''' is invalid when...
* If {{LSLP|target}} is owned by a different user and modify permission has been granted to the script owner via [http://community.secondlife.com/t5/tkb/articleprintpage/tkb-id/English_KB@tkb/article-id/215 Edit, delete, or take my objects], the script owner must be connected to the sim for this function to succeed.  
** it equals the value returned by [[llGetKey]].
* If {{LSLP|pin}} fails to match, the error "Task ~Prim~ trying to illegally load script onto task ~Other_Prim~!" is shouted on [[DEBUG_CHANNEL]]. "~Prim~" and "~Other_Prim~" are substituted with the applicable prim names.
*In case the object containing the script with llRemoteLoadScriptPin() is deeded to a group, the script which is supposed to be transfered needs transfer permissions even when it's supposed to be transfered to another object which is deeded to the same group.
* If {{LSLP|target}} is the script's parent (<code>{{LSLPT|target}} == [[llGetKey]]()</code>) then "Unable to add item!" is shouted on [[DEBUG_CHANNEL]].
* If the object containing this script is deeded to a group, then script {{LSLP|name}} needs transfer permissions; even if {{LSLP|target}} is deeded to the same group.
* When the script is set to run (with {{LSLP|running}}, the running checkbox or [[llSetScriptState]]) [[state_entry]] will be queued.
|constants
|constants
|examples=
|examples=
<lsl>//Child Prim PIN setter
==== Basic Example ====
=====Script copier=====
<source lang="lsl2">//Copy a script to the second prim
integer PIN=1341134;
integer PIN=1341134;


default {
default {
state_entry() {
    state_entry() {
        llRemoteLoadScriptPin( llGetLinkKey(2), "some script", PIN, TRUE, 0xBEEEEEEF );
    }
}</source>
=====Pin setter=====
Simple script used for setting the pin for a prim, so you can later send scripts to it with llRemoteLoadScriptPin.
<source lang="lsl2">//Child Prim PIN setter
integer PIN=1341134;
 
default {
    state_entry() {
         llOwnerSay(llGetObjectName()+" : "+(string)llGetKey()+" is ready to accept a describer script using the agreed upon PIN.");
         llOwnerSay(llGetObjectName()+" : "+(string)llGetKey()+" is ready to accept a describer script using the agreed upon PIN.");
         llSetRemoteScriptAccessPin(PIN);
         llSetRemoteScriptAccessPin(PIN);
    }
}</source>
==== Rez and copy a file from a control object ====
Notes: There is currently no signing on the starting messages only the owner is checked.
this example rezs a prim from inventory that has a basic control file inside of it and does a basic handshake to setup the
pin and transfer the script.


after the transfert the helper script in the rezzed prim deletes itself.
===== Control prim =====
<source lang="lsl2">
integer controlchan = 0;
integer controlid = -1;
start()
{
    llSetTimerEvent(0);
    talkingto = NULL_KEY;
    integer a = (integer)llFrand(43);
    controlchan = a * a;
    controlchan -= controlchan * 3;
    controlid = llListen(controlchan,"","","set-connect");
    llRezObject("card",llGetPos()+<0,0,0.1>,<0,0,0>,ZERO_ROTATION,a);
    llSetTimerEvent(60);
}
key talkingto = NULL_KEY;
integer busy = FALSE;
integer accesspin = 0;
default
{
    timer()
    {
        llSetTimerEvent(0);
        llOwnerSay("Lost connection!");
        llListenRemove(controlid);
        busy = FALSE;
     }
     }
}</lsl>
    listen(integer chan,string name,key id,string message)
    {
        if(chan == controlchan)
        {
            if(llGetOwnerKey(id) == llGetOwner())
            {
                if(talkingto == NULL_KEY)
                {
                    if(message == "set-connect")
                    {
                        llSetTimerEvent(0);
                        talkingto = id;
                        llListenRemove(controlid);
                        controlid = llListen(controlchan,"",talkingto,"ready");
                        llRegionSayTo(id,controlchan,"auto-connect");
                        llSetTimerEvent(60);
                    }
                } 
                else if(id == talkingto)
                {
                    if(message == "ready")
                    {
                        llSetTimerEvent(0);
                        accesspin = (integer)llFrand(2345)+213;
                        llListenRemove(controlid);
                        controlid = llListen(controlchan,"",talkingto,"pinset");
                        llSleep(1);
                        llRegionSayTo(talkingto,controlchan,(string)accesspin);
                        llSetTimerEvent(60);
                    }
                    else if(message == "pinset")
                    {
                        llSetTimerEvent(0);
                        llListenRemove(controlid);
                        llRemoteLoadScriptPin(talkingto,"demo.lsl",accesspin,1,0);
                        llSleep(3);
                        llRegionSayTo(talkingto,controlchan,"finished");
                        llOwnerSay("Transfer of file finished - control file should have auto deleted itself!");
                        busy = FALSE;
                    }
                }
            } 
        }
    }
    touch_end(integer a)
    {
        if(busy == FALSE)
        {
            busy = TRUE;
            if(llGetOwner() == llDetectedKey(0))
            {
                start();
            }
        }
    }
}
</source>
 
===== rezzed prim =====
<source lang="lsl2">
integer listen_id = -1;
integer listen_chan = -1;
key details_from = NULL_KEY;
default
{
    on_rez(integer a)
    {
        if(a == 0)
        {
            llOwnerSay("- Direct rez -");
        }
        else
        {
            llOwnerSay("- Awaiting config connection -");
            listen_chan = a * a;
            listen_chan -= listen_chan * 3;
            listen_id = llListen(listen_chan,"","","auto-connect");
            llWhisper(listen_chan,"set-connect");
            llSetTimerEvent(30);
        }
    }
    timer()
    {
        llOwnerSay("Failed to connect to rezzer deleting myself!");
        llSetTimerEvent(0);
        llDie();
    }
    listen(integer chan,string name,key id,string message)
    {
        if(llGetOwnerKey(id) == llGetOwner())
        {
            if(message == "auto-connect")
            {
                llSetTimerEvent(0);
                llListenRemove(listen_id);
                listen_id = llListen(listen_chan,"",id,"");
                llRegionSayTo(id,listen_chan,"ready");
                details_from = id;
                llSetTimerEvent(30);               
            }
            else if(details_from != NULL_KEY)
            {
                llSetTimerEvent(0); 
                if(message == "finished")
                {
                    llSetRemoteScriptAccessPin((integer)message);
                    llRemoveInventory(llGetScriptName());       
                }
                else
                {
                    llSetRemoteScriptAccessPin((integer)message);
                    llRegionSayTo(id,listen_chan,"pinset");
                }
                llSetTimerEvent(30); 
            }
        }
    }
}
</source>
 
|helpers
|helpers
|also_functions={{LSL DefineRow||[[llSetRemoteScriptAccessPin]]|Used to setup a prim for remote loading}}
|also_functions={{LSL DefineRow||[[llSetRemoteScriptAccessPin]]|Used to setup a prim for remote loading}}
{{LSL DefineRow||[[llSetScriptState]]|Set a scripts running state}}
{{LSL DefineRow||[[llResetOtherScript]]|Reset another script in the prim}}
|also_tests
|also_tests
|also_events
|also_events
Line 43: Line 215:
|notes
|notes
|cat1=Script
|cat1=Script
|cat2
|cat2=Inventory
|cat3
|cat3
|cat4
|cat4
}}
}}

Latest revision as of 20:55, 1 April 2019

Summary

Function: llRemoteLoadScriptPin( key target, string name, integer pin, integer running, integer start_param );

Copy script name into target and set to running with a start_param only if target's pin matches pin

• key target prim UUID that is in the same region
• string name a script in the inventory of the prim this script is in
• integer pin Must match pin set by llSetRemoteScriptAccessPin
• integer running boolean, if TRUE[1] the script is set as running, if FALSE the script is not set as running
• integer start_param value returned by llGetStartParameter in the target script.

Only works if the script owner can modify target.

Caveats

  • This function causes the script to sleep for 3.0 seconds.
  • If target is not owned by the same person, and name does not have transfer permissions, an error is shouted on DEBUG_CHANNEL.
  • If name permissions do not allow copy, the transfer fails and an error is shouted on DEBUG_CHANNEL.
  • If target is not in the same region an error is shouted on DEBUG_CHANNEL.
  • When scripts are copied or moved between inventories, their state does not survive the transfer. Memory, event queue and execution position are all discarded.
  • If name is missing from the prim's inventory or it is not a script then an error is shouted on DEBUG_CHANNEL.
  • If name is present in the target prim's inventory then it is silently replaced.
  • start_param only lasts until the script is reset.
  • Only the owner of an attachment can modify it while it is being worn.
    • If target is an attachment owned by a different user, regardless of object modify rights granted, this function will silently fail.
  • If target is owned by a different user and modify permission has been granted to the script owner via Edit, delete, or take my objects, the script owner must be connected to the sim for this function to succeed.
  • If pin fails to match, the error "Task ~Prim~ trying to illegally load script onto task ~Other_Prim~!" is shouted on DEBUG_CHANNEL. "~Prim~" and "~Other_Prim~" are substituted with the applicable prim names.
  • If target is the script's parent (target == llGetKey()) then "Unable to add item!" is shouted on DEBUG_CHANNEL.
  • If the object containing this script is deeded to a group, then script name needs transfer permissions; even if target is deeded to the same group.
  • When the script is set to run (with running, the running checkbox or llSetScriptState) state_entry will be queued.

Important Issues

~ All Issues ~ Search JIRA for related Bugs
   stack trace error while running scripts after llRemoteLoadScriptPin

Examples

Basic Example

Script copier
//Copy a script to the second prim
integer PIN=1341134;

default {
    state_entry() {
        llRemoteLoadScriptPin( llGetLinkKey(2), "some script", PIN, TRUE, 0xBEEEEEEF );
    }
}
Pin setter

Simple script used for setting the pin for a prim, so you can later send scripts to it with llRemoteLoadScriptPin.

//Child Prim PIN setter
integer PIN=1341134;

default {
    state_entry() {
        llOwnerSay(llGetObjectName()+" : "+(string)llGetKey()+" is ready to accept a describer script using the agreed upon PIN.");
        llSetRemoteScriptAccessPin(PIN);
    }
}

Rez and copy a file from a control object

Notes: There is currently no signing on the starting messages only the owner is checked.

this example rezs a prim from inventory that has a basic control file inside of it and does a basic handshake to setup the pin and transfer the script.

after the transfert the helper script in the rezzed prim deletes itself.

Control prim
integer controlchan = 0;
integer controlid = -1;
start()
{
    llSetTimerEvent(0);
    talkingto = NULL_KEY;
    integer a = (integer)llFrand(43);
    controlchan = a * a;
    controlchan -= controlchan * 3;
    controlid = llListen(controlchan,"","","set-connect");
    llRezObject("card",llGetPos()+<0,0,0.1>,<0,0,0>,ZERO_ROTATION,a);
    llSetTimerEvent(60);
}
key talkingto = NULL_KEY;
integer busy = FALSE;
integer accesspin = 0;
default
{
    timer()
    {
        llSetTimerEvent(0);
        llOwnerSay("Lost connection!");
        llListenRemove(controlid);
        busy = FALSE;
    }
    listen(integer chan,string name,key id,string message)
    {
        if(chan == controlchan)
        {
            if(llGetOwnerKey(id) == llGetOwner())
            {
                if(talkingto == NULL_KEY)
                {
                    if(message == "set-connect")
                    {
                        llSetTimerEvent(0);
                        talkingto = id;
                        llListenRemove(controlid);
                        controlid = llListen(controlchan,"",talkingto,"ready");
                        llRegionSayTo(id,controlchan,"auto-connect");
                        llSetTimerEvent(60);
                    }
                }   
                else if(id == talkingto)
                {
                    if(message == "ready")
                    {
                        llSetTimerEvent(0);
                        accesspin = (integer)llFrand(2345)+213;
                        llListenRemove(controlid);
                        controlid = llListen(controlchan,"",talkingto,"pinset");
                        llSleep(1);
                        llRegionSayTo(talkingto,controlchan,(string)accesspin);
                        llSetTimerEvent(60);
                    }
                    else if(message == "pinset")
                    {
                        llSetTimerEvent(0);
                        llListenRemove(controlid);
                        llRemoteLoadScriptPin(talkingto,"demo.lsl",accesspin,1,0);
                        llSleep(3);
                        llRegionSayTo(talkingto,controlchan,"finished");
                        llOwnerSay("Transfer of file finished - control file should have auto deleted itself!");
                        busy = FALSE;
                    }
                } 
            }   
        }
    }
    touch_end(integer a)
    {
        if(busy == FALSE)
        {
            busy = TRUE;
            if(llGetOwner() == llDetectedKey(0))
            {
                start();
            }
        }
    }
}
rezzed prim
integer listen_id = -1;
integer listen_chan = -1;
key details_from = NULL_KEY;
default
{
    on_rez(integer a)
    {
        if(a == 0)
        {
            llOwnerSay("- Direct rez -");
        }
        else
        {
            llOwnerSay("- Awaiting config connection -");
            listen_chan = a * a;
            listen_chan -= listen_chan * 3;
            listen_id = llListen(listen_chan,"","","auto-connect");
            llWhisper(listen_chan,"set-connect");
            llSetTimerEvent(30);
        }
    }
    timer()
    {
        llOwnerSay("Failed to connect to rezzer deleting myself!");
        llSetTimerEvent(0);
        llDie();
    }
    listen(integer chan,string name,key id,string message)
    {
        if(llGetOwnerKey(id) == llGetOwner())
        {
            if(message == "auto-connect")
            {
                llSetTimerEvent(0);
                llListenRemove(listen_id);
                listen_id = llListen(listen_chan,"",id,"");
                llRegionSayTo(id,listen_chan,"ready");
                details_from = id;
                llSetTimerEvent(30);                 
            }
            else if(details_from != NULL_KEY)
            {
                llSetTimerEvent(0);  
                if(message == "finished")
                {
                    llSetRemoteScriptAccessPin((integer)message);
                    llRemoveInventory(llGetScriptName());         
                }
                else
                {
                    llSetRemoteScriptAccessPin((integer)message);
                    llRegionSayTo(id,listen_chan,"pinset");
                } 
                llSetTimerEvent(30);  
            }
        }
    }
}

See Also

Functions

•  llSetRemoteScriptAccessPin Used to setup a prim for remote loading
•  llSetScriptState Set a scripts running state
•  llResetOtherScript Reset another script in the prim

Deep Notes

History

  • Added in 1.2.6
  • In SL 1.25.4 this function will not copy/move any script into an attachment unless the script is full perm. (SVC-3725)
  • SL 1.25.5 will allow this function to copy/move a script into an attachment so long as the target has matching (or more restrictive) copy and transfer permissions. (SVC-3738)

All Issues

~ Search JIRA for related Issues
   stack trace error while running scripts after llRemoteLoadScriptPin

Footnotes

  1. ^ Any value that is not zero/FALSE is treated the same as TRUE. This behavior should not be depended upon.

Signature

function void llRemoteLoadScriptPin( key target, string name, integer pin, integer running, integer start_param );