### push_set() example

Source: https://sansldap.readthedocs.io/en/latest/source/sansldap.html

Use this snippet to start writing a SET or SET_OF value. The writer must be used within a with statement to ensure the sequence is closed and written back to the parent writer.

```python
with writer.push_set() as seq_writer:
    seq_writer.write_octet_string(b"foo")
```

--------------------------------

### Custom LDAPControl example

Source: https://sansldap.readthedocs.io/en/latest/source/sansldap.html

Custom LDAPControl implementation that packs an integer size into a 4-byte value and unpacks it. Must inherit LDAPControl, set control_type, and implement get_value and unpack.

```python
@dataclasses.dataclass(frozen=True)
class CustomControl(LDAPControl):
    control_type: str = dataclasses.field(init=False, repr=False, default="1.2.3.4")
    value: t.Optional[bytes] = dataclasses.field(init=False, repr=False, default=None)

    size: int

    def get_value(
        self,
        options: ControlOptions,
    ) -> t.Optional[bytes]:
        return self.size.to_bytes(4)

    @classmethod
    def unpack(
        cls,
        control_type: str,
        critical: bool,
        value: t.Optional[bytes],
        options: ControlOptions,
    ) -> CustomControl:
        size = struct.unpack("<I", (value or b""))[0]

        return CustomControl(critical=critical, size=size)

```

--------------------------------

### data_to_send(amount=None)

Source: https://sansldap.readthedocs.io/en/latest/source/sansldap.html

Get data to send to the peer. Gets the data available in the outgoing buffer to send to the peer. If amount is not specified then the whole outgoing buffer is returned. Otherwise only the data up to the amount specified is returned.

```APIDOC
## data_to_send(amount=None)

### Description
Get data to send to the peer. Gets the data available in the outgoing buffer to send to the peer. If amount is not specified then the whole outgoing buffer is returned. Otherwise only the data up to the amount specified is returned.

### Parameters
- **amount** (`Optional`[`int`]) - Optional - The length of the output to return, otherwise all data will be returned if None.

### Returns
- **bytes** - The data to send to the peer.

```

--------------------------------

### Simple bind with sansldap

Source: https://sansldap.readthedocs.io/en/latest/events.html

Performs a simple bind with plaintext credentials. The example shows the client sending a BindRequest and the server responding with a BindResponse, including assertions on the request fields and the success result code. It also notes that a faulty bind can specify an error code.

```python
import sansldap

client = sansldap.LDAPClient()
server = sansldap.LDAPServer()

client.bind_simple("username", "password")
client_outgoing = client.data_to_send()

bind_request = server.receive(client_outgoing)[0]
assert isinstance(bind_request, sansldap.BindRequest)
assert isinstance(bind_request.authentication, sansldap.SimpleCredential)
assert bind_request.name == "username"
assert bind_request.authentication.password == "password"

# Can specify an error code on a faulty bind.
server.bind_response(bind_request.message_id)
server_outgoing = server.data_to_send()

bind_response = client.receive(server_outgoing)[0]
assert isinstance(bind_response, sansldap.BindResponse)
assert bind_response.result.result_code == sansldap.LDAPResultCode.SUCCESS

```

--------------------------------

### Search request with sansldap.LDAPClient and LDAPServer

Source: https://sansldap.readthedocs.io/en/latest/events.html

Performs a search request using sansldap.LDAPClient and sansldap.LDAPServer. The client sends a SearchRequest with an empty base object and the "defaultNamingContext" attribute; the server responds with a SearchResultEntry and a SearchResultDone. The example asserts the received messages and their contents, including the result code SUCCESS.

```python
import sansldap

client = sansldap.LDAPClient()
server = sansldap.LDAPServer()

# Client most likely needs to be bound before the search

# There are more options that can be provided for a request.
client.search_request("", attributes=["defaultNamingContext"])
client_outgoing = client.data_to_send()

search_request = server.receive(client_outgoing)[0]
assert isinstance(search_request, sansldap.SearchRequest)
assert search_request.base_object == ""
assert search_request.attributes == ["defaultNamingContext"]

server.search_result_entry(
    search_request.message_id,
    search_request.base_object,
    attributes=[
        sansldap.PartialAttribute("defaultNamingContext", [b"DC=domain,DC=test"]),
    ],
)
server.search_result_done(search_request.message_id)
server_outgoing = server.data_to_send()

responses = client.receive(server_outgoing)
assert len(responses) == 2
assert isinstance(responses[0], sansldap.SearchResultEntry)
assert isinstance(responses[1], sansldap.SearchResultDone)

assert len(responses[0].attributes) == 1
assert responses[0].attributes[0].name == "defaultNamingContext"
assert responses[0].attributes[0].values == [b"DC=domain,DC=test"]
assert responses[1].result.result_code == sansldap.LDAPResultCode.SUCCESS

```

--------------------------------

### Custom LDAPFilter example

Source: https://sansldap.readthedocs.io/en/latest/source/sansldap.html

Custom LDAPFilter implementation that packs and unpacks a string value using ASN1Writer and ASN1Reader. Must inherit LDAPFilter, set filter_id, and implement pack and unpack. The filter must be understood by both client and server.

```python
@dataclasses.dataclass(frozen=True)
class CustomFilter(LDAPFilter):
    filter_id: int = dataclasses.field(init=False, repr=False, default=1024)

    value: str

    def pack(
        self,
        writer: sansldap.asn1.ASN1Writer,
        options: FilterOptions,
    ) -> None:
        writer.write_octet_string(
            self.value.encode(options.string_encoding),
            tag=sansldap.asn1.ASN1Tag(
                sansldap.asn1.TagClass.CONTEXT_SPECIFIC,
                self.filter_id,
                False,
            ),
        )

    @classmethod
    def unpack(
        cls,
        reader: sansldap.asn1.ASN1Reader,
        options: FilterOptions,
    ) -> CustomFilter:
        value = reader.read_octet_string(
            sansldap.asn1.ASN1Tag(
                sansldap.asn1.TagClass.CONTEXT_SPECIFIC,
                cls.filter_id,
                False,
            ),
        ).decode("utf-8")
        return CustomFilter(value=value)

```

--------------------------------

### Custom AuthenticationCredential subclass with pack and unpack

Source: https://sansldap.readthedocs.io/en/latest/source/sansldap.html

Shows how to implement a custom AuthenticationCredential subclass for use with sansldap.BindRequest. The example defines a frozen dataclass with a custom auth_id (1024) and implements pack and unpack methods that encode and decode a username:password string using the provided ASN.1 writer/reader and options. Both client and server must understand the custom credential.

```python
@dataclasses.dataclass(frozen=True)
class CustomAuth(a.AuthenticationCredential):
    auth_id: int = dataclasses.field(init=False, repr=False, default=1024)

    username: str
    password: str

    def pack(
        self,
        writer: sansldap.asn1.ASN1Writer,
        options: a.AuthenticationOptions,
    ) -> None:
        writer.write_octet_string(
            f"{self.username}:{self.password}".encode(options.string_encoding),
            tag=sansldap.asn1.ASN1Tag(
                sansldap.asn1.TagClass.CONTEXT_SPECIFIC,
                self.auth_id,
                False,
            ),
        )

    @classmethod
    def unpack(
        cls,
        reader: sansldap.asn1.ASN1Reader,
        options: a.AuthenticationOptions,
    ) -> CustomAuth:
        value = reader.read_octet_string(
            tag=sansldap.asn1.ASN1Tag(
                sansldap.asn1.TagClass.CONTEXT_SPECIFIC,
                cls.auth_id,
                False,
            ),
            hint="CustomAuth.value",
        ).decode(options.string_encoding)
        username, _, password = value.partition(":")

        return CustomAuth(username=username, password=password)

```

--------------------------------

### ASN1Writer.push_sequence

Source: https://sansldap.readthedocs.io/en/latest/source/sansldap.html

Gets a new writer to start writing values inside a sequence or sequence of object. Make sure to wrap the writer in a with statement to ensure the sequence is closed and written back to the parent writer.

```APIDOC
## ASN1Writer.push_sequence

### Description
Gets a new writer to start writing values inside a sequence or sequence of object. Make sure to wrap the writer in a with statement to ensure the sequence is closed and written back to the parent writer.

### Method
push_sequence

### Parameters
- **tag** (`Optional[ASN1Tag]`) - Optional - Optional tag to mark the sequence/sequence_of with.

### Returns
ASN1Writer - The writer object that can be used to write the sequence elements.
```

--------------------------------

### ASN1Writer.push_sequence_of

Source: https://sansldap.readthedocs.io/en/latest/source/sansldap.html

Gets a new writer to start writing values inside a sequence or sequence of object. Make sure to wrap the writer in a with statement to ensure the sequence is closed and written back to the parent writer.

```APIDOC
## ASN1Writer.push_sequence_of

### Description
Gets a new writer to start writing values inside a sequence or sequence of object. Make sure to wrap the writer in a with statement to ensure the sequence is closed and written back to the parent writer.

### Method
push_sequence_of

### Parameters
- **tag** (`Optional[ASN1Tag]`) - Optional - Optional tag to mark the sequence/sequence_of with.

### Returns
ASN1Writer - The writer object that can be used to write the sequence elements.

### Example
```
with writer.push_sequence() as seq_writer:
    seq_writer.write_octet_string(b"foo")
```
```

--------------------------------

### ASN1Writer.get_data

Source: https://sansldap.readthedocs.io/en/latest/source/sansldap.html

Gets the data written to the writer. This is used to get the final ASN.1 value after all the values have been written to it.

```APIDOC
## ASN1Writer.get_data

### Description
Gets the data written to the writer. This is used to get the final ASN.1 value after all the values have been written to it. It cannot be called on a child writer returned by push_sequence or push_set.

### Method
get_data

### Returns
bytearray - The data that has been written.
```

--------------------------------

### search_request(base_object=None, scope=SearchScope.SUBTREE, dereferencing_policy=DereferencingPolicy.NEVER, size_limit=0, time_limit=0, types_only=False, filter=None, attributes=None, controls=None)

Source: https://sansldap.readthedocs.io/en/latest/source/sansldap.html

Sends a Search Request. Creates a search request that can result in three different responses: SearchResultEntry, SearchResultReference, and SearchResultDone. The operation is not complete until SearchResultDone is received.

```APIDOC
## search_request(base_object=None, scope=SearchScope.SUBTREE, dereferencing_policy=DereferencingPolicy.NEVER, size_limit=0, time_limit=0, types_only=False, filter=None, attributes=None, controls=None)

### Description
Send a Search Request. Creates a search request that can result in three different responses: SearchResultEntry, SearchResultReference, and SearchResultDone. The operation is not complete until SearchResultDone is received.

### Method
search_request

### Parameters
- **base_object** (`Optional[str]`) - Optional - The name of the base object entry, or None/empty string for root, which the search is to be performed.
- **scope** (`Union[int, SearchScope]`) - Optional - The scope of the search. Defaults to SUBTREE.
- **dereferencing_policy** (`Union[int, DereferencingPolicy]`) - Optional - Indicates how alias entries are to be dereferenced. Defaults to NEVER.
- **size_limit** (`int`) - Optional - The maximum number of entries to be returned. A value of 0 has no restrictions.
- **time_limit** (`int`) - Optional - The maximum time, in seconds, allowed for the operation. A value of 0 has no time restrictions.
- **types_only** (`bool`) - Optional - Only return attribute names and no values in the search result.
- **filter** (`Optional[LDAPFilter]`) - Optional - The LDAP filter to search by.
- **attributes** (`Optional[List[str]]`) - Optional - A list of attributes to be returned from each entry that match the search filter. The default requests the return of all user attributes.
- **controls** (`Optional[List[LDAPControl]]`) - Optional - Optional client controls to send with the request.

### Returns
- `int` - The message id associated with the request.

```

--------------------------------

### StartTLS operation with sansldap

Source: https://sansldap.readthedocs.io/en/latest/events.html

Performs a StartTLS operation using the sansldap library. It sends an ExtendedRequest with the LDAP_START_TLS operation, verifies the server's ExtendedResponse, and notes that the TLS handshake must be performed on the socket to wrap future messages.

```python
import sansldap

client = sansldap.LDAPClient()
server = sansldap.LDAPServer()

client.extended_request(sansldap.ExtendedOperations.LDAP_START_TLS.value)
client_outgoing = client.data_to_send()

ext_request = server.receive(client_outgoing)[0]
assert isinstance(ext_request, sansldap.ExtendedRequest)
assert ext_request.name == sansldap.ExtendedOperations.LDAP_START_TLS.value

server.extended_response(ext_request.message_id)
server_outgoing = server.data_to_send()

ext_response = client.receive(server_outgoing)[0]
assert isinstance(ext_response, sansldap.ExtendedResponse)
assert ext_response.result.result_code == sansldap.LDAPResultCode.SUCCESS

# The TLS handshake needs to be performed on the socket to set up the TLS
# channel. Any future messages to send from data_to_send() needs to be wrapped
# by the TLS channel that was set up.

```

--------------------------------

### LDAPServer

Source: https://sansldap.readthedocs.io/en/latest/source/sansldap.html

LDAP server session class for sending server LDAP messages.

```APIDOC
## LDAPServer

### Description
LDAP Server session class used to send server LDAP messages.

### Methods
#### bind_response(message_id, sasl_creds=None, result_code=LDAPResultCode.SUCCESS, matched_dn=None, diagnostics_message=None, controls=None)

Send a Bind Response. Responds to a bind request. The state will be changed to `OPENED` unless the result code is `SASL_BIND_IN_PROGRESS`.

##### Parameters
- **message_id** - Required - The message ID of the bind request.
- **sasl_creds** - Optional - SASL credentials.
- **result_code** - Optional - The result code to send. Defaults to `LDAPResultCode.SUCCESS`.
- **matched_dn** - Optional - The matched DN.
- **diagnostics_message** - Optional - The diagnostics message.
- **controls** - Optional - A list of controls.

```

--------------------------------

### bind_simple(dn=None, password=None, controls=None)

Source: https://sansldap.readthedocs.io/en/latest/source/sansldap.html

Sends a Simple BIND request for anonymous, unauthenticated, or authenticated bind. Returns the message id associated with the request.

```APIDOC
## bind_simple(dn=None, password=None, controls=None)

### Description
Send a Simple BIND request. Creates a SIMPLE bind request to perform an anonymous, unauthenticated, or authenticated bind. The format of dn depends on the LDAP server implementation.

### Method
BIND (Simple)

### Parameters
- **dn** (`Optional[str]`) - Optional - The name of the Directory object that the client wishes to bind as. Set to None or an empty string to perform an anonymous bind.
- **password** (`Optional[str]`) - Optional - The password to bind with, set to None or an empty string to perform an unauthenticated bind.
- **controls** (`Optional[List[LDAPControl]]`) - Optional - Optional client controls to send with the request.

### Returns
- **int** - The message id associated with the request.
```

--------------------------------

### Write a SEQUENCE with push_sequence()

Source: https://sansldap.readthedocs.io/en/latest/source/sansldap.html

Use this snippet to write a SEQUENCE value. The writer must be used in a with statement to ensure the sequence is closed and written back to the parent writer.

```python
with writer.push_sequence() as seq_writer:
    seq_writer.write_octet_string(b"foo")

```

--------------------------------

### unpack(reader, options)

Source: https://sansldap.readthedocs.io/en/latest/source/sansldap.html

Unpacks raw bytes into a Python object using an ASN.1 reader.

```APIDOC
## unpack(reader, options)

### Description
Unpacks raw bytes into a Python object using an ASN.1 reader.

### Parameters
- **reader** (`ASN1Reader`) - Required - The reader used to read the ASN.1 data.
- **options** (`FilterOptions`) - Required - Options controlling how the filter is unpacked.

### Returns
An instance of the object that has been unpacked.

### Return Type
`LDAPFilter`
```

--------------------------------

### bind(dn, authentication, controls=None)

Source: https://sansldap.readthedocs.io/en/latest/source/sansldap.html

Sends a BIND request with a custom authentication credential. Returns the message id associated with the request.

```APIDOC
## bind(dn, authentication, controls=None)

### Description
Send a BIND request. Creates a bind request with the authentication payload specified. This can be used to bind with a custom set of credentials that have been registered with `LDAPSession.register_auth_credential()`. It is recommended to use `bind_simple()` or `bind_sasl()` instead of this function.

### Method
BIND

### Parameters
- **dn** (`str`) - Required - The name of the Directory object that the client wishes to bind as.
- **authentication** (`AuthenticationCredential`) - Required - The authentication object to bind with. This must be registered first with `LDAPSession.register_auth_credential()`.
- **controls** (`Optional[List[LDAPControl]]`) - Optional - Optional client controls to send with the request.

### Returns
- **int** - The message id associated with the request.
```

--------------------------------

### register_auth_credential(auth)

Source: https://sansldap.readthedocs.io/en/latest/source/sansldap.html

Register a custom authentication credential. Registers a custom `AuthenticationCredential` class that can be used for a bind.

```APIDOC
## register_auth_credential(auth)

### Description
Register a custom authentication credential. Registers a custom `AuthenticationCredential` class that can be used for a bind.

### Parameters
- **auth** (`Type`[`AuthenticationCredential`]) - Required - The custom authentication credential type to register.

### Returns
- **None**

```

--------------------------------

### unpack(reader, options)

Source: https://sansldap.readthedocs.io/en/latest/source/sansldap.html

Unpacks raw filter bytes into a Python object.

```APIDOC
## unpack(reader, options)

### Description
Unpacks the raw bytes into the Python object.

### Parameters
- **reader** (`ASN1Reader`) - Required - The reader used to read the ASN.1 data.
- **options** (`FilterOptions`) - Required - Options that can be used to control how the filter is unpacked.

### Returns
An instance of the object that has been unpacked.

### Return Type
`LDAPFilter`

```

--------------------------------

### pack(writer, options)

Source: https://sansldap.readthedocs.io/en/latest/source/sansldap.html

Packs the filter structure into an ASN.1 writer for embedding in a SearchRequest filter value.

```APIDOC
## pack(writer, options)

### Description
Packs the filter structure into an ASN.1 writer for embedding in a SearchRequest filter value.

### Parameters
- **writer** (`ASN1Writer`) - Required - The writer used to write ASN.1 data.
- **options** (`FilterOptions`) - Required - Options controlling how the filter is packed.

### Return Type
`None`
```

--------------------------------

### pack(writer, options)

Source: https://sansldap.readthedocs.io/en/latest/source/sansldap.html

Packs the filter structure into an ASN.1 writer for embedding in a SearchRequest filter value.

```APIDOC
## pack(writer, options)

### Description
Packs the filter structure into the ASN.1 writer that is then embedded in the `SearchRequest` filter value. The tagged choice should also be included in the written value.

### Parameters
- **writer** (`ASN1Writer`) - Required - The writer used to write ASN.1 data
- **options** (`FilterOptions`) - Required - Options that can be used to control how the filter is packed.

### Return Type
`None`

```

--------------------------------

### receive(data)

Source: https://sansldap.readthedocs.io/en/latest/source/sansldap.html

Receives data from the peer and unpacks LDAP messages. Returns a list of complete LDAPMessage objects and buffers any remaining data internally. Raises ProtocolError on fatal parsing errors.

```APIDOC
## receive(data)

### Description
Receive data from the peer and unpack LDAP messages. Returns a list of complete LDAPMessage objects and buffers any remaining data internally. Raises ProtocolError on fatal parsing errors.

### Method
receive

### Parameters
- **data** (`Union[bytes, bytearray, memoryview]`) - Required - The data to process.

### Returns
- `t.List[LDAPMessage]` - A list of messages that have been unpacked.

### Raises
- **ProtocolError** - A protocol violation occurred and the connection is no longer valid.

```

--------------------------------

### register_control(control)

Source: https://sansldap.readthedocs.io/en/latest/source/sansldap.html

Register a custom LDAP control. Registers a custom `LDAPControl` class that can be used for controls in a request/response.

```APIDOC
## register_control(control)

### Description
Register a custom LDAP control. Registers a custom `LDAPControl` class that can be used for controls in a request/response.

### Parameters
- **control** (`Type`[`LDAPControl`]) - Required - The custom LDAP control type to register.

### Returns
- **None**

```

--------------------------------

### LDAPError

Source: https://sansldap.readthedocs.io/en/latest/source/sansldap.html

Base LDAP error class. All LDAP-related exceptions derive from this class.

```APIDOC
## LDAPError

### Description
Base LDAP error class. All LDAP-related exceptions derive from this class.
```

--------------------------------

### receive(data)

Source: https://sansldap.readthedocs.io/en/latest/source/sansldap.html

Receive data to process. Receives the data from the peer and unpack the messages found into LDAPMessages. Any complete LDAP messages received will be returned and any remaining data will be stored in an internal buffer. A ProtocolError indicates something fatal has occurred when trying to parse the incoming data and the connection is no longer in a valid state.

```APIDOC
## receive(data)

### Description
Receive data to process. Receives the data from the peer and unpack the messages found into LDAPMessages. Any complete LDAP messages received will be returned and any remaining data will be stored in an internal buffer. A ProtocolError indicates something fatal has occurred when trying to parse the incoming data and the connection is no longer in a valid state. The caller SHOULD send the notice of disconnection payload available in `data_to_send()` and MUST close the underlying connection.

### Parameters
- **data** (`Union`[`bytes`, `bytearray`, `memoryview`]) - Required - The data to process.

### Returns
- **t.List[LDAPMessage]** - A list of messages that have been unpacked.

### Raises
- **ProtocolError** - A protocol violation occurred and the connection is no longer valid.

```

--------------------------------

### LDAPMessage(message_id, controls)

Source: https://sansldap.readthedocs.io/en/latest/source/sansldap.html

Base LDAP message object with packing functionality.

```APIDOC
## LDAPMessage(message_id, controls)

### Description
The base LDAP Message object used for all LDAP messages. The base message structure is defined in RFC 4511 4.1.1. Message Envelope.

### Parameters
- **message_id** (`int`) - Required - The unique identifier for the request.
- **controls** (`List[LDAPControl]`) - Required - A list of controls associated with the message.
- **tag_number** - The protocolOp choice for this message type. This is defined on each LDAPMessage sub class.

### Attributes
- **controls** (`List[LDAPControl]`)
- **message_id** (`int`)
- **tag_number** (`int`) - Default: `0`

### Methods
#### pack(options)

Packs the current message and returns the bytes string that can be exchanged with the peer.

##### Returns
The ASN.1 BER encoded message.

##### Return Type
`bytes`

```

--------------------------------

### bind_sasl(mechanism, dn=None, cred=None, controls=None)

Source: https://sansldap.readthedocs.io/en/latest/source/sansldap.html

Sends a SASL BIND request using the specified mechanism and credential. Returns the message id associated with the request.

```APIDOC
## bind_sasl(mechanism, dn=None, cred=None, controls=None)

### Description
Send a SASL BIND request. Creates a SASL bind request using the mechanism and credential specified. A SASL bind operation may require multiple requests for the bind to be completed. It is up to the caller to process any server SASL credential responses in the BindResponse and then create a new SASL BindRequest with the new credential value.

### Method
BIND (SASL)

### Parameters
- **mechanism** (`str`) - Required - The SASL mechanism to authenticate with.
- **dn** (`Optional[str]`) - Optional - The user to bind as, this is typically not set for SASL as the cred contains the user information.
- **cred** (`Optional[bytes]`) - Optional - The SASL bytes to authenticate with.
- **controls** (`Optional[List[LDAPControl]]`) - Optional - Optional client controls to send with the request.

### Returns
- **int** - The message id associated with the request.
```

--------------------------------

### FilterApproxMatch(attribute, value)

Source: https://sansldap.readthedocs.io/en/latest/source/sansldap.html

An LDAP filter for approximate matching, checking if the attribute value matches a locally-defined approximate matching algorithm.

```APIDOC
## FilterApproxMatch(attribute, value)

### Description
An LDAP filter for approximate matching, checking if the attribute value matches a locally-defined approximate matching algorithm.

### Parameters
- **attribute** (`str`) - Required - The attribute to match against.
- **value** (`bytes`) - Required - The value to use as the approximate matching comparison.

### Attributes
- **attribute** (`str`) - The attribute to match against.
- **filter_id** (`int`) - The ASN.1 choice value for this filter (8).
- **value** (`bytes`) - The value to use as the approximate matching comparison.

### Methods
#### pack(writer, options)
Packs the filter structure into an ASN.1 writer.

Parameters:
- **writer** (`ASN1Writer`) - Required - The writer used to write ASN.1 data.
- **options** (`FilterOptions`) - Required - Options controlling how the filter is packed.

Return type: `None`

#### unpack(reader, options)
Unpacks raw bytes into a Python object.

Parameters:
- **reader** (`ASN1Reader`) - Required - The reader used to read the ASN.1 data.
- **options** (`FilterOptions`) - Required - Options controlling how the filter is unpacked.

Returns: An instance of the object that has been unpacked.

Return type: `LDAPFilter`
```

--------------------------------

### search_result_reference(message_id, uris, controls=None)

Source: https://sansldap.readthedocs.io/en/latest/source/sansldap.html

Send a Search Result Reference. Responds to a search request with a reference result. This is a result that indicates the server is unable, or unwilling, to search one or more non-local entries. The message contains reference(s) to one or more set of servers for the client to continue the operation.

```APIDOC
## search_result_reference(message_id, uris, controls=None)

### Description
Send a Search Result Reference. Responds to a search request with a reference result. This is a result that indicates the server is unable, or unwilling, to search one or more non-local entries. The message contains reference(s) to one or more set of servers for the client to continue the operation.

### Parameters
- **message_id** (`int`) - Required - The message id this is responding to.
- **uris** (`List`[`str`]) - Required - The references for the client.
- **controls** (`Optional`[`List`[`LDAPControl`]]) - Optional - Optional server controls to send with the request.

### Returns
- **int** - The message id associated with the request.

```

--------------------------------

### register_filter(filter)

Source: https://sansldap.readthedocs.io/en/latest/source/sansldap.html

Register a custom LDAP filter. Registers a custom `LDAPFilter` class that can be used for a SearchRequest.

```APIDOC
## register_filter(filter)

### Description
Register a custom LDAP filter. Registers a custom `LDAPFilter` class that can be used for a SearchRequest.

### Parameters
- **filter** (`Type`[`LDAPFilter`]) - Required - The custom LDAP filter type to register.

### Returns
- **None**

```

--------------------------------

### LDAPFilter

Source: https://sansldap.readthedocs.io/en/latest/source/sansldap.html

Base class for all LDAP filters. Supports standard LDAP filter types and allows custom filter implementations.

```APIDOC
## LDAPFilter

### Description
Base class for all LDAP filters. Supports standard LDAP filter types and allows custom filter implementations.

### Constructor
`LDAPFilter(filter_id: int)`

### Parameters
- **filter_id** (int) - Required - The ASN.1 choice value for this filter.

### Attributes
- **filter_id** (int) - The ASN.1 choice value for this filter.

### Methods
#### from_string(filter: str) -> LDAPFilter (classmethod)
Converts an LDAP filter string to a filter object based on RFC 4511 rules.

**Parameters:**
- **filter** (str) - Required - The LDAP filter string to convert.

**Returns:**
- LDAPFilter - The converted filter.

### Example
```
@dataclasses.dataclass(frozen=True)
class CustomFilter(LDAPFilter):
    filter_id: int = dataclasses.field(init=False, repr=False, default=1024)

    value: str

    def pack(
        self,
        writer: sansldap.asn1.ASN1Writer,
        options: FilterOptions,
    ) -> None:
        writer.write_octet_string(
            self.value.encode(options.string_encoding),
            tag=sansldap.asn1.ASN1Tag(
                sansldap.asn1.TagClass.CONTEXT_SPECIFIC,
                self.filter_id,
                False,
            ),
        )

    @classmethod
    def unpack(
        cls,
        reader: sansldap.asn1.ASN1Reader,
        options: FilterOptions,
    ) -> CustomFilter:
        value = reader.read_octet_string(
            sansldap.asn1.ASN1Tag(
                sansldap.asn1.TagClass.CONTEXT_SPECIFIC,
                cls.filter_id,
                False,
            ),
        ).decode("utf-8")
        return CustomFilter(value=value)
```
```

--------------------------------

### sansldap.asn1.ASN1Reader

Source: https://sansldap.readthedocs.io/en/latest/source/sansldap.html

Class used to read ASN.1 data. Provides methods to stream through data and peek at subsequent entries.

```APIDOC
## ASN1Reader

### Description
Class used to read ASN.1 data that is passed in. It provides an easy way to stream through the data as well as peek at the subsequent entries.

### Constructor
`ASN1Reader(data)`

#### Parameters
- **data** (`Union`[`bytes`, `bytearray`, `memoryview`]) - Required - The data to read from.

### Methods

#### get_remaining_data()
Gets the remaining data in the reader.

**Return type:** `bytes`

#### peek_header()
Get the next value header. Gets the header for the next value. This will not read the value so it will still be at the same position once run.

**Returns:** The header information including the tag information as well as the length of the next value.

**Return type:** `ASN1Header`

#### read_boolean(tag=None, header=None, hint=None)
Reads an ASN.1 BOOLEAN value.

**Parameters:**
- **tag** (`Optional`[`ASN1Tag`]) - Optional - The tag to validate with, defaults to the BOOLEAN universal tag.
- **header** (`Optional`[`ASN1Header`]) - Optional - Optional header from `peek_header()` to make the extraction more efficient.
- **hint** (`Optional`[`str`]) - Optional - A hint used in error messages to display what this step was used for.

**Returns:** The bool value.

**Return type:** `bool`

#### read_enumerated(enum_type, tag=None, header=None, hint=None)
Reads an ASN.1 ENUMERATED value.

**Parameters:**
- **enum_type** (`Type`[`TypeVar`(`T`, bound= `int`)]) - Required - The enum.IntEnum type to cast the integer value to.
- **tag** (`Optional`[`ASN1Tag`]) - Optional - The tag to validate with, defaults to the ENUMERATED universal tag.
- **header** (`Optional`[`ASN1Header`]) - Optional - Optional header from `peek_header()` to make the extraction more efficient.
- **hint** (`Optional`[`str`]) - Optional - A hint used in error messages to display what this step was used for.

**Returns:** The instance of enum_type that the value represents.

**Return type:** `T`

#### read_integer(tag=None, header=None, hint=None)
Reads an ASN.1 INTEGER value.

**Parameters:**
- **tag** (`Optional`[`ASN1Tag`]) - Optional - The tag to validate with, defaults to the INTEGER universal tag.
- **header** (`Optional`[`ASN1Header`]) - Optional - Optional header from `peek_header()` to make the extraction more efficient.
- **hint** (`Optional`[`str`]) - Optional - A hint used in error messages to display what this step was used for.

**Returns:** The int value.

**Return type:** `int`

#### read_octet_string(tag=None, header=None, hint=None)
Reads an ASN.1 OCTET_STRING value. As this returns a bytes string, it is useful to extract the raw ASN.1 value as long as the correct tag or header is provided.

**Parameters:**
- **tag** (`Optional`[`ASN1Tag`]) - Optional - The tag to validate with, defaults to the OCTET_STRING universal tag (primitive).
- **header** (`Optional`[`ASN1Header`]) - Optional - Optional header from `peek_header()` to make the extraction more efficient.
- **hint** (`Optional`[`str`]) - Optional - A hint used in error messages to display what this step was used for.

**Returns:** The octet string bytes.

**Return type:** `bytes`

#### read_sequence(tag=None, header=None, hint=None)
Reads an ASN.1 SEQUENCE or SEQUENCE_OF value. The returned reader can be used to then read the values inside the sequence.

**Parameters:**
- **tag** (`Optional`[`ASN1Tag`]) - Optional - The tag to validate with, defaults to the SEQUENCE/SEQUENCE_OF universal tag.
- **header** (`Optional`[`ASN1Header`]) - Optional - Optional header from `peek_header()` to make the extraction more efficient.
- **hint** (`Optional`[`str`]) - Optional - A hint used in error messages to display what this step was used for.

**Returns:** The ASN.1 reader object that can be used to read the sequence elements.

**Return type:** `ASN1Reader`

#### read_sequence_of(tag=None, header=None, hint=None)
Reads an ASN.1 SEQUENCE or SEQUENCE_OF value. The returned reader can be used to then read the values inside the sequence.

**Parameters:**
- **tag** (`Optional`[`ASN1Tag`]) - Optional - The tag to validate with, defaults to the SEQUENCE/SEQUENCE_OF universal tag.
- **header** (`Optional`[`ASN1Header`]) - Optional - Optional header from `peek_header()` to make the extraction more efficient.
- **hint** (`Optional`[`str`]) - Optional - A hint used in error messages to display what this step was used for.

**Returns:** The ASN.1 reader object that can be used to read the sequence elements.

**Return type:** `ASN1Reader`
```

--------------------------------

### unbind()

Source: https://sansldap.readthedocs.io/en/latest/source/sansldap.html

Send an unbind request. Sends the UnbindRequest message to the peer. This will mark the state as closed and no more operations can be issued after calling this function. The caller should also close the TCP connection once sending the UnbindRequest payload. No response is expected for this request.

```APIDOC
## unbind()

### Description
Send an unbind request. Sends the UnbindRequest message to the peer. This will mark the state as closed and no more operations can be issued after calling this function. The caller should also close the TCP connection once sending the UnbindRequest payload. No response is expected for this request.

### Returns
- **None**

```

--------------------------------

### ASN1Tag.universal_tag

Source: https://sansldap.readthedocs.io/en/latest/source/sansldap.html

Generates a universal tag with the type specified.

```APIDOC
## ASN1Tag.universal_tag

### Description
Generates a universal tag with the type specified.

### Method
universal_tag

### Parameters
- **number** - Required - The tag number.
- **is_constructed** (`bool`) - Optional - Whether the value is constructed (True) or primitive (False). Defaults to False.

### Returns
ASN1Tag
```

--------------------------------

### FilterExtensibleMatch(rule, attribute, value, dn_attributes)

Source: https://sansldap.readthedocs.io/en/latest/source/sansldap.html

An LDAP filter for extensible matching, allowing custom rules and logic for attribute value checks.

```APIDOC
## FilterExtensibleMatch(rule, attribute, value, dn_attributes)

### Description
An LDAP filter for extensible matching, allowing custom rules and logic for attribute value checks.

### Parameters
- **rule** (`Optional[str]`) - Required - The rule name or OID string for the match, or None if attribute is set to follow normal rules.
- **attribute** (`Optional[str]`) - Required - The attribute to match against, or None to search all attributes if rule is set.
- **value** (`bytes`) - Required - The value to compare.
- **dn_attributes** (`bool`) - Required - Use the attributes that compose the entry's DN in the check.

### Attributes
- **attribute** (`Optional[str]`) - The attribute to match against.
- **dn_attributes** (`bool`) - Use the attributes that compose the entry's DN in the check.
- **filter_id** (`int`) - The ASN.1 choice value for this filter (9).

### Methods
#### pack(writer, options)
Packs the filter structure into an ASN.1 writer.

Parameters:
- **writer** (`ASN1Writer`) - Required - The writer used to write ASN.1 data.
- **options** (`FilterOptions`) - Required - Options controlling how the filter is packed.

Return type: `None`

#### unpack(reader, options)
Unpacks raw bytes into a Python object.

Parameters:
- **reader** (`ASN1Reader`) - Required - The reader used to read the ASN.1 data.
- **options** (`FilterOptions`) - Required - Options controlling how the filter is unpacked.

Returns: An instance of the object that has been unpacked.

Return type: `LDAPFilter`
```

--------------------------------

### sansldap.asn1.ASN1Header

Source: https://sansldap.readthedocs.io/en/latest/source/sansldap.html

A representation of an ASN.1 TLV as a tuple. Defines the ASN.1 Type Length Value (TLV) values as separate objects for easier parsing.

```APIDOC
## ASN1Header

### Description
A representation of an ASN.1 TLV as a tuple. Defines the ASN.1 Type Length Value (TLV) values as separate objects for easier parsing. This is returned by `ASN1Reader.peek_header()`.

### Constructor
`ASN1Header(tag, tag_length, length)`

#### Parameters
- **tag** (`ASN1Tag`) - Required - The tag details, including the class and tag number.
- **tag_length** (`int`) - Required - The length of the encoded tag.
- **length** (`int`) - Required - The length of the value the tag represents.

### Attributes
- **length** (`int`) - The length of the ASN.1 value.
- **tag** (`ASN1Tag`) - The ASN.1 tag details for the current entry.
- **tag_length** (`int`) - The length of the tag/length ASN.1 octets.
```

--------------------------------

### LDAPResult(result_code, matched_dn, diagnostics_message, referrals=None)

Source: https://sansldap.readthedocs.io/en/latest/source/sansldap.html

Base object for LDAP result messages.

```APIDOC
## LDAPResult(result_code, matched_dn, diagnostics_message, referrals=None)

### Description
The LDAPResult message is the base object that contains the various response results from a server. The LDAPResult structure is defined in RFC 4511 4.1.9. Result Message.

### Parameters
- **result_code** (`LDAPResultCode`) - Required - The result status of the operation.
- **matched_dn** (`str`) - Required - The subject to the name of the last entry used in finding the target of base object. Can be an empty string if not relevant.
- **diagnostics_message** (`str`) - Required - A string containing textual diagnostic messages. This is not standardized and should not be parsed, used for display purposes.
- **referrals** (`Optional[List[str]]`) - Optional - Used when the result_code is `REFERRAL`, contains the references to one or more servers/services that may be accessed by LDAP.

### Attributes
- **diagnostics_message** (`str`)
- **matched_dn** (`str`)
- **referrals** (`Optional[List[str]]`) - Default: `None`
- **result_code** (`LDAPResultCode`)

```

--------------------------------

### PagedResultControl(critical, size, cookie)

Source: https://sansldap.readthedocs.io/en/latest/source/sansldap.html

Control for Simple Paged Results. An LDAP control used to perform simple paging of search results. It is sent by the client to control the rate at which an LDAP server returns the results of an LDAP search operation.

```APIDOC
## PagedResultControl(critical, size, cookie)

### Description
Control for Simple Paged Results. An LDAP control used to perform simple paging of search results. It is sent by the client to control the rate at which an LDAP server returns the results of an LDAP search operation.

### Parameters
- **critical** (`bool`) - Required - Whether the control must be known by the server or not.
- **size** (`int`) - Required - The desired page size, this must be less than the size_limit set in a `SearchRequest` message.
- **cookie** (`bytes`) - Required - An opaque set of bytes used to identify the search operation as denoted by the server response.

### Attributes
- **control_type** (`str`) - '1.2.840.113556.1.4.319'
- **cookie** (`bytes`)

### Methods
- **get_value(options)** - Returns `Optional`[`bytes`]

```

--------------------------------

### extended_request(name, value=None, controls=None)

Source: https://sansldap.readthedocs.io/en/latest/source/sansldap.html

Sends an Extended request to perform custom operations on the server. Returns the message id associated with the request.

```APIDOC
## extended_request(name, value=None, controls=None)

### Description
Send an Extended request. Creates an extended request to perform custom operations on the server. An extended request must be supported by both the client and server.

### Method
EXTENDED

### Parameters
- **name** (`str`) - Required - The extended request OID string.
- **value** (`Optional[bytes]`) - Optional - The value for the request, can be None if the request does not have a value.
- **controls** (`Optional[List[LDAPControl]]`) - Optional - Optional client controls to send with the request.

### Returns
- **int** - The message id associated with the request.
```

--------------------------------

### LDAPResultCode(value)

Source: https://sansldap.readthedocs.io/en/latest/source/sansldap.html

Enumeration of known LDAP result codes.

```APIDOC
## LDAPResultCode(value)

### Description
The known LDAP result codes.

### Enum Values
- `ADMIN_LIMIT_EXCEEDED` = 11
- `AFFECTS_MULTIPLE_DSAS` = 71
- `ALIAS_DEREFERENCING_PROBLEM` = 36
- `ALIAS_PROBLEM` = 33
- `ATTRIBUTE_OR_VALUE_EXISTS` = 20
- `AUTH_METHOD_NOT_SUPPORTED` = 7
- `BUSY` = 51
- `COMPARE_FALSE` = 5
- `COMPARE_TRUE` = 6
- `CONFIDENTIALITY_REQUIRED` = 13
- `CONSTRAINT_VIOLATION` = 19
- `ENTRY_ALREADY_EXISTS` = 68
- `INAPPROPRIATE_AUTHENTICATION` = 48
- `INAPPROPRIATE_MATCHING` = 18
- `INSUFFICIENT_ACCESS_RIGHTS` = 50
- `INVALID_ATTRIBUTE_SYNTAX` = 21
- `INVALID_CREDENTIALS` = 49
- `INVALID_DN_SYNTAX` = 34
- `LOOP_DETECT` = 54
- `NAMING_VIOLATION` = 64
- `NOT_ALLOWED_ON_NON_LEAF` = 66
- `NOT_ALLOWED_ON_RDN` = 67
- `NO_SUCH_ATTRIBUTE` = 16
- `NO_SUCH_OBJECT` = 32
- `OBJECT_CLASS_MODS_PROHIBITED` = 69
- `OBJECT_CLASS_VIOLATION` = 65
- `OPERATIONS_ERROR` = 1
- `OTHER` = 80
- `PROTOCOL_ERROR` = 2
- `REFERRAL` = 10
- `SASL_BIND_IN_PROGRESS` = 14
- `SIZE_LIMIT_EXCEEDED` = 4
- `STRONG_AUTH_REQUIRED` = 8
- `SUCCESS` = 0
- `TIME_LIMIT_EXCEEDED` = 3
- `UNAVAILABLE` = 52
- `UNAVAILABLE_CRITICAL_EXTENSION` = 12
- `UNDEFINED_ATTRIBUTE_TYPE` = 17
- `UNWILLING_TO_PERFORM` = 53

```

--------------------------------

### ASN1Reader.skip_value

Source: https://sansldap.readthedocs.io/en/latest/source/sansldap.html

Skips the next value as indicated by the header.

```APIDOC
## ASN1Reader.skip_value

### Description
Skips the next value as indicated by the header.

### Method
skip_value

### Parameters
- **header** (`ASN1Header`) - Required - The header which contains the metadata of the next value to skip.

### Returns
None
```

--------------------------------

### FilterEquality(attribute, value)

Source: https://sansldap.readthedocs.io/en/latest/source/sansldap.html

An LDAP filter for equality matching, checking if the attribute is set to the specified value.

```APIDOC
## FilterEquality(attribute, value)

### Description
An LDAP filter for equality matching, checking if the attribute is set to the specified value.

### Parameters
- **attribute** (`str`) - Required - The attribute to match against.
- **value** (`bytes`) - Required - The value of the attribute to check.

### Attributes
- **attribute** (`str`) - The attribute to match against.
- **filter_id** (`int`) - The ASN.1 choice value for this filter (3).
- **value** (`bytes`) - The value of the attribute to check.

### Methods
#### pack(writer, options)
Packs the filter structure into an ASN.1 writer.

Parameters:
- **writer** (`ASN1Writer`) - Required - The writer used to write ASN.1 data.
- **options** (`FilterOptions`) - Required - Options controlling how the filter is packed.

Return type: `None`

#### unpack(reader, options)
Unpacks raw bytes into a Python object.

Parameters:
- **reader** (`ASN1Reader`) - Required - The reader used to read the ASN.1 data.
- **options** (`FilterOptions`) - Required - Options controlling how the filter is unpacked.

Returns: An instance of the object that has been unpacked.

Return type: `LDAPFilter`
```

--------------------------------

### ASN1Reader.read_set_of

Source: https://sansldap.readthedocs.io/en/latest/source/sansldap.html

Reads an ASN.1 SET or SET_OF value. The returned reader can be used to then read the values inside the set.

```APIDOC
## ASN1Reader.read_set_of

### Description
Reads an ASN.1 SET or SET_OF value. The returned reader can be used to then read the values inside the set.

### Method
read_set_of

### Parameters
- **tag** (`Optional[ASN1Tag]`) - Optional - The tag to validate with, defaults to the SET/SET_OF universal tag.
- **header** (`Optional[ASN1Header]`) - Optional - Optional header from `peek_header()` to make the extraction more efficient.
- **hint** (`Optional[str]`) - Optional - A hint used in error messages to display what this step was used for.

### Returns
ASN1Reader - The ASN.1 reader object that can be used to read the set elements.
```