curl/docs/libcurl/curl_multi_assign.md

c	SPDX-License-Identifier	Title	Section	Source	See-also	Protocol	Added-in
Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.	curl	curl_multi_assign	3	libcurl	curl_multi_setopt (3) curl_multi_socket_action (3) CURLMOPT_SOCKETFUNCTION (3)	All	7.15.5

NAME

curl_multi_assign - set data to associate with an internal socket

SYNOPSIS

#include <curl/curl.h>

CURLMcode curl_multi_assign(CURLM *multi_handle, curl_socket_t sockfd,
                            void *sockptr);

DESCRIPTION

This function creates an association in the multi handle between the given socket and a private pointer of the application. This is designed for curl_multi_socket_action(3) uses.

When set, the sockptr pointer is passed to all future socket callbacks for the specific sockfd socket, until the socket stops being monitored (CURL_POLL_REMOVE is sent to the CURLMOPT_SOCKETFUNCTION(3) callback).

If the given sockfd is not already in use by libcurl, this function returns an error.

libcurl only keeps one single pointer associated with a socket, so calling this function several times for the same socket makes the last set pointer get used.

It is acceptable to call this function from your multi callback functions.

%PROTOCOLS%

EXAMPLE

int main(void)
{
  CURLM *multi = curl_multi_init();
  int private = 123;
  curl_socket_t fd = 0; /* file descriptor to associate our data with */

  /* make our struct pointer associated with socket fd */
  CURLMcode mresult = curl_multi_assign(multi, fd, &private);
  if(mresult)
    printf("error: %s\n", curl_multi_strerror(mresult));
}

TYPICAL USAGE

In a typical application you allocate a struct or at least use some kind of semi-dynamic data for each socket that we must wait for action on when using the curl_multi_socket_action(3) approach.

When our socket-callback gets called by libcurl and we get to know about yet another socket to wait for, we can use curl_multi_assign(3) to point out the particular data so that when we get updates about this same socket again, we do not have to find the struct associated with this socket by ourselves.

%AVAILABILITY%

RETURN VALUE

This function returns a CURLMcode indicating success or error.

CURLM_OK (0) means everything was OK, non-zero means an error occurred, see libcurl-errors(3).