SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
brief: |
  Identifies a message queue object by the specified object name.
copyrights:
- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
definition:
  default:
    body: null
    params:
    - ${../../type/if/name:/name} ${.:/params[0]/name}
    - ${/c/if/uint32_t:/name} ${.:/params[1]/name}
    - ${../../type/if/id:/name} *${.:/params[2]/name}
    return: ${../../status/if/code:/name}
  variants: []
description: |
  This directive obtains the message queue identifier associated with the
  message queue name specified in ``${.:/params[0]/name}``.

  The node to search is specified in ``${.:/params[1]/name}``.  It shall be

  * a valid node number,

  * the constant ${../../object/if/search-all-nodes:/name} to search in all nodes,

  * the constant ${../../object/if/search-local-node:/name} to search in the local
    node only, or

  * the constant ${../../object/if/search-other-nodes:/name} to search in all nodes
    except the local node.
enabled-by: true
index-entries: []
interface-type: function
links:
- role: interface-placement
  uid: header
- role: interface-ingroup
  uid: group
name: rtems_message_queue_ident
notes: |
  If the message queue name is not unique, then the message queue identifier
  will match the first message queue with that name in the search order.
  However, this message queue identifier is not guaranteed to correspond to the
  desired message queue.  The message queue identifier is used with other
  message related directives to access the message queue.

  If node is ${../../object/if/search-all-nodes:/name}, all nodes are searched with
  the local node being searched first.  All other nodes are searched with the
  lowest numbered node searched first.

  If node is a valid node number which does not represent the local node, then
  only the message queues exported by the designated node are searched.

  This directive does not generate activity on remote nodes.  It accesses only
  the local copy of the global object table.
params:
- description: is the object name to look up.
  dir: null
  name: name
- description: is the node or node set to search for a matching object.
  dir: null
  name: node
- description: |
    is the pointer to an object identifier variable.  The object identifier of
    an object with the specified name will be stored in this variable, in case
    of a successful operation.
  dir: out
  name: id
return:
  return: null
  return-values:
  - description: |
      The requested operation was successful.
    value: ${../../status/if/successful:/name}
  - description: |
      The ${.:/params[2]/name} parameter was ${/c/if/null:/name}.
    value: ${../../status/if/invalid-address:/name}
  - description: |
      The ${.:/params[0]/name} parameter was 0.
    value: ${../../status/if/invalid-name:/name}
  - description: |
      There was no object with the specified name on the specified nodes.
    value: ${../../status/if/invalid-name:/name}
  - description: |
      In multiprocessing configurations, the specified node was invalid.
    value: ${../../status/if/invalid-node:/name}
type: interface