VgaGames4

VgaGames4 - network man-pages

[.. upper level ..]

# vg4->nw->connect()

Connect to network-server.

SYNTAX
int vg4->nw->connect(const char *ip, int minclients, int maxclients, const char *name, void (*cbkf)(const char * const *clpp, int cl_nr, void *vdata), void *vdata)
FUNCTION PARAMETERS

ip | internet-address (ipv4 or ipv6) or name of the network-server
minclients | min. number of clients (1 to maxclients), or 0 = doesn't matter
maxclients | max. number of clients (1 to 8), or 0 = doesn't matter
name | Name of the client, or NULL = use its hostname as name
cbkf | Callback function for displaying connected clients, or NULL = no function, Parameters: - clpp: array of client-names connected so far - cl_nr: number of clients in clpp - vdata: arbitrary data
vdata | Arbitrary data, which is passed to the callback function cbkf

RETURN VALUE
Returns the client-number as a positive integer, or 0 = Got exit-request or -1 = Error
DESCRIPTION
Connect to network-server. The internet-address ip can be queried by vg4->nw->get_ip(). The name sets the name of the client visible to others. This function will block until all clients are connected. Until minclients are connected, it won't return. It will return automatically if maxclients are connected. To inform the user about the progress, the callback function cbkf can be set which shall display the connected clients. This callback function will be called at each new connection. To cancel the connection the escape-key can be pressed. To force the network-server end waiting for connections (if minclients are connected) the spacebar or return-key can be pressed. All clients are represented by their returned client-number. The client-numbers begin with 1 and are incremented for each new client.
EXAMPLE

    /* search for network-server and connect to it showing progress on window */

    /* callback-function for showing progress at connecting to network-server */
    static void
    show_progress(const char * const *clients, int anz, void *vdata)
    {
      int i1;
      char btxt[512];
      size_t blen;
      struct VG_Image *img;
      char *sdata = (char *)vdata;

      /* create text containing the clients in a list */
      if (sdata != NULL) { snprintf(btxt, sizeof(btxt), "%s:\n", sdata); }
      blen = strlen(btxt);
      for (i1 = 0; i1 < anz; i1++) {
        snprintf(btxt + blen, sizeof(btxt) - blen, " - %d = <%s>\n", i1+1, clients[i1]);
        blen = strlen(btxt);
      }

      /* show text */
      img = vg4->font->totext(btxt, NULL, NULL, NULL, NULL);
      vg4->window->clear();
      vg4->window->copy(img, NULL, NULL);
      vg4->window->flush();
      vg4->image->destroy(img);
    }

    /* connect to network-server */
    static VG_BOOL
    connect_to_nwserver(int max_connections, int *clnr, int *clmax)
    {
      char remhost[128], *ipsrv;

      if (clnr == NULL || clmax == NULL) { return VG_FALSE; }

      /* set ports to default (unnecessary call) */
      vg4->nw->set_ports(0, 0);

      /* check if network-server runs (just for demonstration) */
      if (!vg4->nw->check_server(NULL)) {
        fprintf(stderr, "Network-server not running.\n");
        return VG_FALSE;
      }

      /* get IP of network-server */
      ipsrv = vg4->nw->get_ip(remhost, sizeof(remhost));
      if (ipsrv == NULL) { return VG_FALSE; }

      /* output info */
      printf("Network-server: %s (IP=%s)\n", remhost, ipsrv);

      /* connect to network-server, blocking until all clients connected, showing progress */
      *clnr = vg4->nw->connect(ipsrv, 0, max_connections, NULL, show_progress, "Clients");
      free(ipsrv);
      if (*clnr <= 0) { return VG_FALSE; }

      /* get number of clients */
      *clmax = vg4->nw->numberofclients(NULL);

      /* output info */
      printf("Client-number %d of %d clients\n", *clnr, *clmax);
      fflush(stdout);

      return VG_TRUE;
    }

SEE ALSO
vg4->nw->set_ports() vg4->nw->get_ip() vg4->nw->close() vg4->nw->is_connected() vg4->nw->numberofclients()