NAME

target_alloc - Bind an external connection point or force-push a subsegment

SYNOPSIS

vid:new_vid, aid:new_aid, int:new_cookie
target_alloc( string:cpoint, function:callback )
target_alloc( string:cpoint, string:passkey, function:callback )
target_alloc( string:cpoint, string:passkey, int:w, int:h, function:callback )
target_alloc( string:cpoint, int:w, int:h, function:callback )
target_alloc( vid:fsrv )
target_alloc( vid:fsrv, function:callback )
target_alloc( vid:fsrv, int:w, int:h, function:callback )
target_alloc( vid:fsrv, function:callback, string:type )
target_alloc( vid:fsrv, function:callback, number:tag )
target_alloc( vid:fsrv, int:w, int:h, function:callback, string:type )
target_alloc( vid:fsrv, int:w, int:h, function:callback, string:type, bool:forced )

DESCRIPTION

This functions controls server-side initiated allocation of segments or connection points. If the initial argument is of the cpoint form, the allocation will be a named connection point to which a client can connect. If the initial argument is of the fsrv form, a subsegment will be allocated and pushed to the client. This form is more specialised and intended as a server-side means of requesting and probing for client- side support for alternate views of whatever the fsrv connection current presents. This can be further specified by providing a type (debug, accessibility) and if a backend implementation should be forced or not (default=false). The form and use for callback is the same as in launch_target , please refer to that function for detailed documentation. The optional passkey form is an aditional authentication string that the connecting client is expected to be able to authenticate against in a platform defined function, typically as a simple string comparison or challenge-response and is not intended as a strong means of authentication. For such cases, the launch_target mechanism combined with the target/configuration database is preferred, as only the connection itself will be authenticated, the contents can still be subject to interception and tampering by a local attacker.

NOTES

1: To push new output segments, see define_recordtarget , define_nulltarget and define_feedtarget .
2: Each call that allows a non-authoritative connection is only valid once, if a connection fail to verify OR a connection is completed, the connection point will be removed.
3: The connection key is limited to 30 characters from the set [a-Z,_0-9] and the actual search path / mechanism is implementation defined.
4: The first example below will continuously listen for new connections under the 'nonauth' key. In a real-world setting, be sure to restrict the number of allowed connections to avoid running out of resources and to monitor for suspicious activities e.g. a high amount of connections or connection attempts in a short timeframe etc.
5: The connection point is consumed (closed, unlinked) when the first verified connection goes through. To re-use the connection point, invoke target_alloc again with the same key from within the callback handler.
6: for honoring explicit requests from a frameserver regarding new subsegments, use the accept_target function.
7: When a 'connected' event has been received, many applications expect a displayhint event before being able to proceed (with information about the current surface dimensions and density)

EXAMPLE

function target_alloc0()
      local chain_call = function()
            target_alloc("nonauth", function(source, status)
                  print(source, status.kind);
                  if (status.kind == "connected") then
                        chain_call();
                  end
            end);
      end
end

MISUSE

function target_alloc0()
      local a = fill_surface(32, 32, 255, 0, 0, 0);
      target_alloc(a, function(source, status)
      end);
end

MISUSE

function target_alloc1()
      vid = net_listen();
      target_alloc(vid, target_alloc);
end