coap_session.h File Reference

Defines the application visible session information. More...

`#include "coap_forward_decls.h"`
`#include "coap_io.h"`
`#include "coap_time.h"`
`#include "pdu.h"`
`#include "uthash.h"`
Include dependency graph for coap_session.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

## Data Structures

struct | coap_fixed_point_t
| Abstraction of a fixed point number that can be used where necessary instead of a float. More...
struct | coap_session_t

## Macros

#define | COAP_DEFAULT_SESSION_TIMEOUT 300
#define | COAP_PARTIAL_SESSION_TIMEOUT_TICKS (30 * COAP_TICKS_PER_SECOND)
#define | COAP_DEFAULT_MAX_HANDSHAKE_SESSIONS 100
#define | COAP_PROTO_NOT_RELIABLE(p) ((p)==COAP_PROTO_UDP || (p)==COAP_PROTO_DTLS)
#define | COAP_PROTO_RELIABLE(p) ((p)==COAP_PROTO_TCP || (p)==COAP_PROTO_TLS)
#define | COAP_SESSION_TYPE_CLIENT 1
| coap_session_type_t values More...
#define | COAP_SESSION_TYPE_SERVER 2
| server-side More...
#define | COAP_SESSION_TYPE_HELLO 3
| server-side ephemeral session for responding to a client hello More...
#define | COAP_SESSION_STATE_NONE 0
| coap_session_state_t values More...
#define | COAP_SESSION_STATE_CONNECTING 1
#define | COAP_SESSION_STATE_HANDSHAKE 2
#define | COAP_SESSION_STATE_CSM 3
#define | COAP_SESSION_STATE_ESTABLISHED 4
#define | COAP_DEFAULT_ACK_TIMEOUT ((coap_fixed_point_t){2,0})
| Number of seconds when to expect an ACK or a response to an outstanding CON message. More...
#define | COAP_DEFAULT_ACK_RANDOM_FACTOR ((coap_fixed_point_t){1,500})
| A factor that is used to randomize the wait time before a message is retransmitted to prevent synchronization effects. More...
#define | COAP_DEFAULT_MAX_RETRANSMIT 4
| Number of message retransmissions before message sending is stopped RFC 7252, Section 4.8 Default value of MAX_RETRANSMIT is 4. More...
#define | COAP_DEFAULT_NSTART 1
| The number of simultaneous outstanding interactions that a client maintains to a given server. More...
#define | SESSIONS_ADD(e, obj) HASH_ADD(hh, (e), addr_info, sizeof((obj)->addr_info), (obj))
#define | SESSIONS_DELETE(e, obj) HASH_DELETE(hh, (e), (obj))
#define | SESSIONS_ITER(e, el, rtmp) HASH_ITER(hh, (e), el, rtmp)
#define | SESSIONS_ITER_SAFE(e, el, rtmp) for ((el) = (e); (el) && ((rtmp) = (el)->hh.next, 1); (el) = (rtmp))
#define | SESSIONS_FIND(e, k, res)

## Typedefs

typedef struct coap_fixed_point_t | coap_fixed_point_t
| Abstraction of a fixed point number that can be used where necessary instead of a float. More...
typedef uint8_t | coap_session_type_t
typedef uint8_t | coap_session_state_t
typedef struct coap_session_t | coap_session_t

## Functions

coap_session_t * | coap_session_reference (coap_session_t *session)
| Increment reference counter on a session. More...
void | coap_session_release (coap_session_t *session)
| Decrement reference counter on a session. More...
void | coap_session_set_app_data (coap_session_t *session, void *data)
| Stores `data` with the given session. More...
void * | coap_session_get_app_data (const coap_session_t *session)
| Returns any application-specific data that has been stored with `session` using the function coap_session_set_app_data(). More...
void | coap_session_disconnected (coap_session_t *session, coap_nack_reason_t reason)
| Notify session that it has failed. More...
void | coap_session_send_csm (coap_session_t *session)
| Notify session transport has just connected and CSM exchange can now start. More...
void | coap_session_connected (coap_session_t *session)
| Notify session that it has just connected or reconnected. More...
void | coap_session_set_mtu (coap_session_t *session, unsigned mtu)
| Set the session MTU. More...
size_t | coap_session_max_pdu_size (const coap_session_t *session)
| Get maximum acceptable PDU size. More...
coap_session_t * | coap_new_client_session (struct coap_context_t *ctx, const coap_address_t *local_if, const coap_address_t *server, coap_proto_t proto)
| Creates a new client session to the designated server. More...
coap_session_t * | coap_new_client_session_psk (struct coap_context_t *ctx, const coap_address_t *local_if, const coap_address_t *server, coap_proto_t proto, const char *identity, const uint8_t *key, unsigned key_len)
| Creates a new client session to the designated server with PSK credentials. More...
coap_session_t * | coap_new_client_session_pki (struct coap_context_t *ctx, const coap_address_t *local_if, const coap_address_t *server, coap_proto_t proto, struct coap_dtls_pki_t *setup_data)
| Creates a new client session to the designated server with PKI credentials. More...
coap_session_t * | coap_new_server_session (struct coap_context_t *ctx, struct coap_endpoint_t *ep)
| Creates a new server session for the specified endpoint. More...
ssize_t | coap_session_send (coap_session_t *session, const uint8_t *data, size_t datalen)
| Function interface for datagram data transmission. More...
ssize_t | coap_session_write (coap_session_t *session, const uint8_t *data, size_t datalen)
| Function interface for stream data transmission. More...
ssize_t | coap_session_send_pdu (coap_session_t *session, coap_pdu_t *pdu)
| Send a pdu according to the session's protocol. More...
const char * | coap_session_str (const coap_session_t *session)
| Get session description. More...
ssize_t | coap_session_delay_pdu (coap_session_t *session, coap_pdu_t *pdu, struct coap_queue_t *node)
coap_endpoint_t * | coap_new_endpoint (struct coap_context_t *context, const coap_address_t *listen_addr, coap_proto_t proto)
| Create a new endpoint for communicating with peers. More...
void | coap_endpoint_set_default_mtu (coap_endpoint_t *endpoint, unsigned mtu)
| Set the endpoint's default MTU. More...
void | coap_free_endpoint (coap_endpoint_t *ep)
const char * | coap_endpoint_str (const coap_endpoint_t *endpoint)
| Get endpoint description. More...
coap_session_t * | coap_endpoint_get_session (coap_endpoint_t *endpoint, const struct coap_packet_t *packet, coap_tick_t now)
| Lookup the server session for the packet received on an endpoint, or create a new one. More...
coap_session_t * | coap_session_new_dtls_session (coap_session_t *session, coap_tick_t now)
| Create a new DTLS session for the `session`. More...
coap_session_t * | coap_session_get_by_peer (struct coap_context_t *ctx, const struct coap_address_t *remote_addr, int ifindex)
void | coap_session_free (coap_session_t *session)
void | coap_session_mfree (coap_session_t *session)
void | coap_session_set_max_retransmit (coap_session_t *session, unsigned int value)
| Set the CoAP maximum retransmit count before failure. More...
void | coap_session_set_ack_timeout (coap_session_t *session, coap_fixed_point_t value)
| Set the CoAP initial ack response timeout before the next re-transmit. More...
void | coap_session_set_ack_random_factor (coap_session_t *session, coap_fixed_point_t value)
| Set the CoAP ack randomize factor. More...
unsigned int | coap_session_get_max_transmit (coap_session_t *session)
| Get the CoAP maximum retransmit before failure. More...
coap_fixed_point_t | coap_session_get_ack_timeout (coap_session_t *session)
| Get the CoAP initial ack response timeout before the next re-transmit. More...
coap_fixed_point_t | coap_session_get_ack_random_factor (coap_session_t *session)
| Get the CoAP ack randomize factor. More...
coap_tid_t | coap_session_send_ping (coap_session_t *session)
| Send a ping message for the session. More...

## Detailed Description

Defines the application visible session information.

Definition in file coap_session.h.

## Macro Definition Documentation

## COAP_DEFAULT_MAX_HANDSHAKE_SESSIONS

#define COAP_DEFAULT_MAX_HANDSHAKE_SESSIONS 100

Definition at line 36 of file coap_session.h.

## COAP_DEFAULT_SESSION_TIMEOUT

#define COAP_DEFAULT_SESSION_TIMEOUT 300

Definition at line 34 of file coap_session.h.

## COAP_PARTIAL_SESSION_TIMEOUT_TICKS

#define COAP_PARTIAL_SESSION_TIMEOUT_TICKS (30 * COAP_TICKS_PER_SECOND)

Definition at line 35 of file coap_session.h.

## COAP_PROTO_NOT_RELIABLE

#define COAP_PROTO_NOT_RELIABLE | ( |  | p | ) | ((p)==COAP_PROTO_UDP || (p)==COAP_PROTO_DTLS)

Definition at line 38 of file coap_session.h.

## COAP_PROTO_RELIABLE

#define COAP_PROTO_RELIABLE | ( |  | p | ) | ((p)==COAP_PROTO_TCP || (p)==COAP_PROTO_TLS)

Definition at line 39 of file coap_session.h.

## COAP_SESSION_STATE_CONNECTING

#define COAP_SESSION_STATE_CONNECTING 1

Definition at line 54 of file coap_session.h.

## COAP_SESSION_STATE_CSM

#define COAP_SESSION_STATE_CSM 3

Definition at line 56 of file coap_session.h.

## COAP_SESSION_STATE_ESTABLISHED

#define COAP_SESSION_STATE_ESTABLISHED 4

Definition at line 57 of file coap_session.h.

## COAP_SESSION_STATE_HANDSHAKE

#define COAP_SESSION_STATE_HANDSHAKE 2

Definition at line 55 of file coap_session.h.

## COAP_SESSION_STATE_NONE

#define COAP_SESSION_STATE_NONE 0

coap_session_state_t values

Definition at line 53 of file coap_session.h.

## COAP_SESSION_TYPE_CLIENT

#define COAP_SESSION_TYPE_CLIENT 1

coap_session_type_t values

client-side

Definition at line 45 of file coap_session.h.

## COAP_SESSION_TYPE_HELLO

#define COAP_SESSION_TYPE_HELLO 3

server-side ephemeral session for responding to a client hello

Definition at line 47 of file coap_session.h.

## COAP_SESSION_TYPE_SERVER

#define COAP_SESSION_TYPE_SERVER 2

server-side

Definition at line 46 of file coap_session.h.

## SESSIONS_ADD

#define SESSIONS_ADD | ( |  | e,
|  |  | obj
| ) |  | HASH_ADD(hh, (e), addr_info, sizeof((obj)->addr_info), (obj))

Definition at line 480 of file coap_session.h.

## SESSIONS_DELETE

#define SESSIONS_DELETE | ( |  | e,
|  |  | obj
| ) |  | HASH_DELETE(hh, (e), (obj))

Definition at line 483 of file coap_session.h.

## SESSIONS_FIND

#define SESSIONS_FIND | ( |  | e,
|  |  | k,
|  |  | res
| ) |  |

Value:
{ \
HASH_FIND(hh, (e), &(k), sizeof(k), (res)); \
}

Definition at line 492 of file coap_session.h.

## SESSIONS_ITER

#define SESSIONS_ITER | ( |  | e,
|  |  | el,
|  |  | rtmp
| ) |  | HASH_ITER(hh, (e), el, rtmp)

Definition at line 486 of file coap_session.h.

## SESSIONS_ITER_SAFE

#define SESSIONS_ITER_SAFE | ( |  | e,
|  |  | el,
|  |  | rtmp
| ) |  | for ((el) = (e); (el) && ((rtmp) = (el)->hh.next, 1); (el) = (rtmp))

Definition at line 489 of file coap_session.h.

## Typedef Documentation

## coap_fixed_point_t

typedef struct coap_fixed_point_t coap_fixed_point_t

Abstraction of a fixed point number that can be used where necessary instead of a float.

1,000 fractional bits equals one integer

## coap_session_state_t

typedef uint8_t coap_session_state_t

Definition at line 49 of file coap_session.h.

## coap_session_t

typedef struct coap_session_t coap_session_t

## coap_session_type_t

typedef uint8_t coap_session_type_t

Definition at line 41 of file coap_session.h.

## Function Documentation

## coap_endpoint_get_session()

coap_session_t* coap_endpoint_get_session | ( | coap_endpoint_t * | endpoint,
|  | const struct coap_packet_t * | packet,
|  | coap_tick_t | now
| ) |  |

Lookup the server session for the packet received on an endpoint, or create a new one.

Parameters

  endpoint | Active endpoint the packet was received on.
  packet | Received packet.
  now | The current time in ticks.

Returns
  The CoAP session or `NULL` if error.

## coap_endpoint_set_default_mtu()

void coap_endpoint_set_default_mtu | ( | coap_endpoint_t * | endpoint,
|  | unsigned | mtu
| ) |  |

Set the endpoint's default MTU.

This is the maximum message size that can be sent, excluding IP and UDP overhead.

Parameters

  endpoint | The CoAP endpoint.
  mtu | maximum message size

Definition at line 1001 of file coap_session.c.

## coap_free_endpoint()

void coap_free_endpoint | ( | coap_endpoint_t * | ep | ) |

Definition at line 1006 of file coap_session.c.

Here is the call graph for this function:
Here is the caller graph for this function:

## coap_new_client_session()

coap_session_t* coap_new_client_session | ( | struct coap_context_t * | ctx,
|  | const coap_address_t * | local_if,
|  | const coap_address_t * | server,
|  | coap_proto_t | proto
| ) |  |

Creates a new client session to the designated server.

Parameters

  ctx | The CoAP context.
  local_if | Address of local interface. It is recommended to use NULL to let the operating system choose a suitable local interface. If an address is specified, the port number should be zero, which means that a free port is automatically selected.
  server | The server's address. If the port number is zero, the default port for the protocol will be used.
  proto | Protocol.

Returns
  A new CoAP session or NULL if failed. Call coap_session_release to free.

Definition at line 766 of file coap_session.c.

Here is the call graph for this function:

## coap_new_client_session_pki()

coap_session_t* coap_new_client_session_pki | ( | struct coap_context_t * | ctx,
|  | const coap_address_t * | local_if,
|  | const coap_address_t * | server,
|  | coap_proto_t | proto,
|  | struct coap_dtls_pki_t * | setup_data
| ) |  |

Creates a new client session to the designated server with PKI credentials.

Parameters

  ctx | The CoAP context.
  local_if | Address of local interface. It is recommended to use NULL to let the operating system choose a suitable local interface. If an address is specified, the port number should be zero, which means that a free port is automatically selected.
  server | The server's address. If the port number is zero, the default port for the protocol will be used.
  proto | CoAP Protocol.
  setup_data | PKI parameters.

Returns
  A new CoAP session or NULL if failed. Call coap_session_release() to free.

Definition at line 841 of file coap_session.c.

Here is the call graph for this function:

## coap_new_client_session_psk()

coap_session_t* coap_new_client_session_psk | ( | struct coap_context_t * | ctx,
|  | const coap_address_t * | local_if,
|  | const coap_address_t * | server,
|  | coap_proto_t | proto,
|  | const char * | identity,
|  | const uint8_t * | key,
|  | unsigned | key_len
| ) |  |

Creates a new client session to the designated server with PSK credentials.

Parameters

  ctx | The CoAP context.
  local_if | Address of local interface. It is recommended to use NULL to let the operating system choose a suitable local interface. If an address is specified, the port number should be zero, which means that a free port is automatically selected.
  server | The server's address. If the port number is zero, the default port for the protocol will be used.
  proto | Protocol.
  identity | PSK client identity
  key | PSK shared key
  key_len | PSK shared key length

Returns
  A new CoAP session or NULL if failed. Call coap_session_release to free.

Definition at line 781 of file coap_session.c.

Here is the call graph for this function:

## coap_new_endpoint()

coap_endpoint_t* coap_new_endpoint | ( | struct coap_context_t * | context,
|  | const coap_address_t * | listen_addr,
|  | coap_proto_t | proto
| ) |  |

Create a new endpoint for communicating with peers.

Parameters

  context | The coap context that will own the new endpoint
  listen_addr | Address the endpoint will listen for incoming requests on or originate outgoing requests from. Use NULL to specify that no incoming request will be accepted and use a random endpoint.
  proto | Protocol used on this endpoint

Definition at line 918 of file coap_session.c.

Here is the call graph for this function:
Here is the caller graph for this function:

## coap_new_server_session()

coap_session_t* coap_new_server_session | ( | struct coap_context_t * | ctx,
|  | struct coap_endpoint_t * | ep
| ) |  |

Creates a new server session for the specified endpoint.

Parameters

  ctx | The CoAP context.
  ep | An endpoint where an incoming connection request is pending.

Returns
  A new CoAP session or NULL if failed. Call coap_session_release to free.

Definition at line 881 of file coap_session.c.

Here is the call graph for this function:
Here is the caller graph for this function:

## coap_session_connected()

void coap_session_connected | ( | coap_session_t * | session | ) |

Notify session that it has just connected or reconnected.

Parameters

  session | The CoAP session.

Definition at line 330 of file coap_session.c.

Here is the call graph for this function:
Here is the caller graph for this function:

## coap_session_delay_pdu()

ssize_t coap_session_delay_pdu | ( | coap_session_t * | session,
|  | coap_pdu_t * | pdu,
|  | struct coap_queue_t * | node
| ) |  |

Definition at line 251 of file coap_session.c.

Here is the call graph for this function:
Here is the caller graph for this function:

## coap_session_disconnected()

void coap_session_disconnected | ( | coap_session_t * | session,
|  | coap_nack_reason_t | reason
| ) |  |

Notify session that it has failed.

Parameters

  session | The CoAP session.
  reason | The reason why the session was disconnected.

Definition at line 387 of file coap_session.c.

Here is the call graph for this function:
Here is the caller graph for this function:

## coap_session_free()

void coap_session_free | ( | coap_session_t * | session | ) |

Definition at line 168 of file coap_session.c.

Here is the call graph for this function:
Here is the caller graph for this function:

## coap_session_get_ack_random_factor()

coap_fixed_point_t coap_session_get_ack_random_factor | ( | coap_session_t * | session | ) |

Get the CoAP ack randomize factor.

A factor that is used to randomize the wait time before a message is retransmitted to prevent synchronization effects.

Parameters

  session | The CoAP session.

Returns
  Current ack randomize value

Definition at line 63 of file coap_session.c.

## coap_session_get_ack_timeout()

coap_fixed_point_t coap_session_get_ack_timeout | ( | coap_session_t * | session | ) |

Get the CoAP initial ack response timeout before the next re-transmit.

Number of seconds when to expect an ACK or a response to an outstanding CON message.

Parameters

  session | The CoAP session.

Returns
  Current ack response timeout value

Definition at line 58 of file coap_session.c.

## coap_session_get_app_data()

void* coap_session_get_app_data | ( | const coap_session_t * | session | ) |

Returns any application-specific data that has been stored with `session` using the function coap_session_set_app_data().

This function will return `NULL` if no data has been stored.

Definition at line 91 of file coap_session.c.

## coap_session_get_by_peer()

coap_session_t* coap_session_get_by_peer | ( | struct coap_context_t * | ctx,
|  | const struct coap_address_t * | remote_addr,
|  | int | ifindex
| ) |  |

## coap_session_get_max_transmit()

unsigned int coap_session_get_max_transmit | ( | coap_session_t * | session | ) |

Get the CoAP maximum retransmit before failure.

Number of message retransmissions before message sending is stopped

Parameters

  session | The CoAP session.

Returns
  Current maximum retransmit value

Definition at line 53 of file coap_session.c.

## coap_session_max_pdu_size()

size_t coap_session_max_pdu_size | ( | const coap_session_t * | session | ) |

Get maximum acceptable PDU size.

Parameters

  session | The CoAP session.

Returns
  maximum PDU size, not including header (but including token).

Definition at line 187 of file coap_session.c.

Here is the caller graph for this function:

## coap_session_mfree()

void coap_session_mfree | ( | coap_session_t * | session | ) |

Definition at line 145 of file coap_session.c.

Here is the call graph for this function:
Here is the caller graph for this function:

## coap_session_reference()

coap_session_t* coap_session_reference | ( | coap_session_t * | session | ) |

Increment reference counter on a session.

Parameters

  session | The CoAP session.

Returns
  same as session

Definition at line 68 of file coap_session.c.

Here is the caller graph for this function:

## coap_session_release()

void coap_session_release | ( | coap_session_t * | session | ) |

Decrement reference counter on a session.

Note that the session may be deleted as a result and should not be used after this call.

Parameters

  session | The CoAP session.

Definition at line 74 of file coap_session.c.

Here is the call graph for this function:
Here is the caller graph for this function:

## coap_session_send()

ssize_t coap_session_send | ( | coap_session_t * | session,
|  | const uint8_t * | data,
|  | size_t | datalen
| ) |  |

Function interface for datagram data transmission.

This function returns the number of bytes that have been transmitted, or a value less than zero on error.

Parameters

  session | Session to send data on.
  data | The data to send.
  datalen | The actual length of `data`.

Returns
  The number of bytes written on success, or a value less than zero on error.

Definition at line 216 of file coap_session.c.

Here is the call graph for this function:
Here is the caller graph for this function:

## coap_session_send_csm()

void coap_session_send_csm | ( | coap_session_t * | session | ) |

Notify session transport has just connected and CSM exchange can now start.

Parameters

  session | The CoAP session.

Definition at line 288 of file coap_session.c.

Here is the call graph for this function:
Here is the caller graph for this function:

## coap_session_send_pdu()

ssize_t coap_session_send_pdu | ( | coap_session_t * | session,
|  | coap_pdu_t * | pdu
| ) |  |

Send a pdu according to the session's protocol.

This function returns the number of bytes that have been transmitted, or a value less than zero on error.

Parameters

  session | Session to send pdu on.
  pdu | The pdu to send.

Returns
  The number of bytes written on success, or a value less than zero on error.

Definition at line 683 of file net.c.

Here is the call graph for this function:
Here is the caller graph for this function:

## coap_session_send_ping()

coap_tid_t coap_session_send_ping | ( | coap_session_t * | session | ) |

Send a ping message for the session.

Parameters

  session | The CoAP session.

Returns
  COAP_INVALID_TID if there is an error

Definition at line 314 of file coap_session.c.

Here is the call graph for this function:
Here is the caller graph for this function:

## coap_session_set_ack_random_factor()

void coap_session_set_ack_random_factor | ( | coap_session_t * | session,
|  | coap_fixed_point_t | value
| ) |  |

Set the CoAP ack randomize factor.

A factor that is used to randomize the wait time before a message is retransmitted to prevent synchronization effects.

Parameters

  session | The CoAP session.
  value | The value to set to. The default is 1.5 and should not normally get changed.

Definition at line 42 of file coap_session.c.

Here is the call graph for this function:

## coap_session_set_ack_timeout()

void coap_session_set_ack_timeout | ( | coap_session_t * | session,
|  | coap_fixed_point_t | value
| ) |  |

Set the CoAP initial ack response timeout before the next re-transmit.

Number of seconds when to expect an ACK or a response to an outstanding CON message.

Parameters

  session | The CoAP session.
  value | The value to set to. The default is 2 and should not normally get changed.

Definition at line 32 of file coap_session.c.

Here is the call graph for this function:

## coap_session_set_app_data()

void coap_session_set_app_data | ( | coap_session_t * | session,
|  | void * | data
| ) |  |

Stores `data` with the given session.

This function overwrites any value that has previously been stored with `session`.

Definition at line 85 of file coap_session.c.

## coap_session_set_max_retransmit()

void coap_session_set_max_retransmit | ( | coap_session_t * | session,
|  | unsigned int | value
| ) |  |

Set the CoAP maximum retransmit count before failure.

Number of message retransmissions before message sending is stopped

Parameters

  session | The CoAP session.
  value | The value to set to. The default is 4 and should not normally get changed.

Definition at line 23 of file coap_session.c.

Here is the call graph for this function:

## coap_session_set_mtu()

void coap_session_set_mtu | ( | coap_session_t * | session,
|  | unsigned | mtu
| ) |  |

Set the session MTU.

This is the maximum message size that can be sent, excluding IP and UDP overhead.

Parameters

  session | The CoAP session.
  mtu | maximum message size

Definition at line 204 of file coap_session.c.

Here is the caller graph for this function:

## coap_session_write()

ssize_t coap_session_write | ( | coap_session_t * | session,
|  | const uint8_t * | data,
|  | size_t | datalen
| ) |  |

Function interface for stream data transmission.

This function returns the number of bytes that have been transmitted, or a value less than zero on error. The number of bytes written may be less than datalen because of congestion control.

Parameters

  session | Session to send data on.
  data | The data to send.
  datalen | The actual length of `data`.

Returns
  The number of bytes written on success, or a value less than zero on error.

Definition at line 237 of file coap_session.c.

Here is the call graph for this function:
Here is the caller graph for this function: