Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
net_open(3)			 Arcan Lua API			   net_open(3)

NAME
       net_open	- Make an outbound connection to a data	source.

SYNOPSIS
       vid or BADID
       net_open( str:host, function:handler(source:vid,	strtbl:status) )
       net_open(  str:host,  str:dst, function:handler(source:vid, strtbl:sta-
       tus) )

DESCRIPTION
       This creates an outbound	connection to a	network	resource speaking  the
       a12 protocol. If	host  starts with an @ sign and	matches	a known	tag in
       the keystore, the connection information	and authentication credentials
       will  be	 picked	from there. If hosts  starts with a ? sign it works as
       with '@'	but the	connection will	only probe which roles the target sup-
       ports (source, sink or directory) and return that as  a	message	 event
       before terminating.

       If  the host  is	a tag, the optional dst	 argument can be used to over-
       ride the	hosts assigned to the tag but still use	the keymaterial.  This
       is  mainly to work with discovery modes such as 'passive' where the tag
       was found, but using a dynamic address.

       The connection behaves  just  as	 if  it	 had  been  initiated  through
       launch_target	or  or target_alloc  but the primary segment will be a
       network type referencing	the connection itself and the actual  resource
       will come as a segment_request.

       If  host	   starts  with	the reserved identifier	@stdin it will try and
       connect to an attached monitor and communicate through it with  an  ex-
       ternal  directory  server and the associated appl- group	of others run-
       ning the	same appl through the same directory.

       The restricted short (alnum _) identifier used server  side  is	deter-
       mined  first by the arcan-net --ident argument (or when opening the di-
       rectory through net_discover ) and, on collision, generated by the  di-
       rectory	server.	 The one actually used will be provided	in a 'message'
       event as	'a12:join= XXXXXX ' where the Xs are substituted with the  ac-
       tual identity.

       Any  higher  level 'nickname' system is expected	to be implemented as a
       nested application specific protocol within the appl- message group.

       Should the connection be	severed, an a12:disconnected will  be  issued,
       and when	if/it can be resumed, a12:reconnected.

       Message events received in this format must follow the argument packing
       in  builtin/string.lua:strings.unpack_shmif_argstr(src) (key=value with
       ':' as separator,  being	substituted to ':'). They have quite short re-
       strictions (78b)	and are	not intended for large	datastream  serialisa-
       tion  since they	can have large amplification and trigger throttling in
       the processing chain. For large transfers we have open_nonblock	or us-
       ing the directory to create a direct channel to a  specific  user.  The
       server end will enforce a prefix	of from=name and reserve the use of an
       'a12' key anywhere. It will reject messages which attempts to use that.

NOTES
       1      with  @stdin:user	 expect	 deliveries to have multipart, meaning
	      they need	to be concatenated until a terminating multipart=false
	      arrives.

       2

EXAMPLE
       function	net_open0()
	     net_open("laptop",
	     function(source, status)
		   if status.kind == "segment_request" then
			 accept_target(0, 0,
			       function(source,	status)
				     if	status.kind == "resized" then
					   show_image(source)
					   resize_image(source,	status.width, status.height)
				     end
			       end
			 )
		   end
		   if status.kind == "terminated" then
			 print("died", status.last_words)
			 delete_image(source)
			 return	shutdown()
	     end)
       end

EXAMPLE
       function	net_open1()
	     local vid = net_open("@stdin:me",
		   function(source, status)
			 if status.kind	== "message" then
			 end
		   end
	     )
	     if	not valid_vid(vid) then
		   print("not connected	to a directory server")
	     end
       end

SEE ALSO:
       net_discover(3) launch_target(3)

network				  April	2025			   net_open(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=net_open&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>

home | help